Detailed description

Standard authentication OATH.

See HSM technical documentation about operating details, specifications used, licenses and module trade name.

Functions
bool	OATHCheck (string masterKeyId, string otp, ref byte[] bBlob)
	Check OTP value.

bool	OATHCheck (string masterKeyId, string otp, ref byte[] bBlob, int dwFlag)
	Check OTP value.

bool	OATHCheck (string masterKeyId, string otp, byte[] bBlob)

bool	OATHCheck (string masterKeyId, string otp, byte[] bBlob, int dwFlag)

byte[]	OATHBlobResync (string szMasterKeyId, string szOTP1, string szOTP2, byte[] bOATHBlob)
	Re-synchronizes a blob OATH by displaying two continuous OTP values.

byte[]	OATHBlobResync (string szMasterKeyId, string szOTP1, string szOTP2, byte[] bOATHBlob, int dwFlags)
	Resynchronizes an OATH blob OATH providing two consecutive OTP values, with support for updating the blob format.

byte[]	OATHGetKey (string szMasterKey, byte[] pbInBlob)
	Retrieves the seed of the key generating the blob from OATH.

DinamoApi.OATH_PSKC_TRANSLATE_OUTPUT[]	OATHPskcTranslate (string szMasterKeyId, string szPSK, byte[] pbPSKC)
	Imports seeds enveloped in the PSKC (Portable Symmetric Key Container) standard, RFC 6030.

byte[]	OATHIssueGenerateHOTP (string szMasterKeyId)
	Generates a HOATH blob, i.e. an event token. The seed will be generated randomly by the HSM.

byte[]	OATHIssueGenerateHOTP (string szMasterKeyId, byte seedLen)
	Generates a HOATH blob, i.e. an event token from a seed size.

byte[]	OATHIssueImportHOTP (string szMasterKeyId, byte[] bSeed)
	Imports a HOATH blob, i.e. an event token from a supplied seed.

byte[]	OATHIssueGenerateTOTP (string szMasterKeyId)
	Generates a TOTP blob, i.e. an event token. The seed will be generated randomly by the HSM.

byte[]	OATHIssueGenerateTOTP (string szMasterKeyId, short step)
	Generates a TOTP blob, i.e. an event token. The seed will be generated randomly by the HSM.

byte[]	OATHIssueGenerateTOTP (string szMasterKeyId, short step, ulong offset)
	Generates a TOTP blob, i.e. an event token. The seed will be generated randomly by the HSM.

byte[]	OATHIssueGenerateTOTP (string szMasterKeyId, short step, ulong offset, byte seedLen)
	Generates a TOTP blob, i.e. an event token. The seed will be generated randomly by the HSM.

byte[]	OATHIssueImportTOTP (string szMasterKeyId, byte[] bSeed)
	Imports a TOTP blob, i.e. an event token from a supplied seed.

byte[]	OATHIssueImportTOTP (string szMasterKeyId, byte[] bSeed, short step)
	Imports a TOTP blob, i.e. an event token from a supplied seed.

byte[]	OATHIssueImportTOTP (string szMasterKeyId, byte[] bSeed, short step, ulong offset)
	Imports a TOTP blob, i.e. an event token from a supplied seed.

string	EncodeBase32 (byte[] data)
	Utility function for encoding Base32. Standard encoding for OATH generators in sofware.

string	OATHGetNext (string szMasterKeyId, byte lenOTP, byte[] bBlob)
	Retrieves the next value for the OTP.

Functions

◆ OATHCheck() [1/4]

bool OATHCheck	(	string	masterKeyId,
		string	otp,
		ref byte[]	bBlob )

inline

Check OTP value.

Parameters

masterKeyId	Name of the master key, used to protect the blobs, of maximum size DinamoApi.MAX_OBJ_ID_FQN_LEN.
otp	OTP to be checked for minimum size DinamoApi.ISSUE_OATH_MIN_OTP_LEN and maximum DinamoApi.ISSUE_OATH_MAX_OTP_LEN.
bBlob	Byte array containing the blob that will be used to generate the OTP. This buffer will be rewritten with the updated blob.

Exceptions

DinamoException.DinamoException In case of error

Returns: >True if the OTP passed in the function parameter is valid. In this case, it is important to persist the returned bBlob to avoid REPLAY attacks.

Examples: oath.cs.

◆ OATHCheck() [2/4]

bool OATHCheck	(	string	masterKeyId,
		string	otp,
		ref byte[]	bBlob,
		int	dwFlag )

inline

Check OTP value.

Parameters

masterKeyId Name of the master key, used to protect the blobs, of maximum size DinamoApi.MAX_OBJ_ID_FQN_LEN.

otp OTP to be checked for minimum size DinamoApi.ISSUE_OATH_MIN_OTP_LEN and maximum DinamoApi.ISSUE_OATH_MAX_OTP_LEN.

bBlob Byte array containing the blob that will be used to generate the OTP. This buffer will be rewritten with the updated blob.

dwFlag

Starting from firmware version 4.0.2, this parameter can be used to pass the size of the authentication look-ahead window. The default is 10 intervals, plus or minus. For HOTP tokens, intervals are counted by the number of events; for TOTP tokens, they are counted by the number of time-steps.

Value	Meaning
0	Uses the default value of 10 intervals.
DinamoApi.MAX_OTP_LOOK_AHEAD_INTERVAL	Defines the value of the authentication look-ahead window.

Returns: True if the OTP passed in the function parameter is valid. In this case, it is important to persist the returned bBlob to avoid REPLAY attacks.

Exceptions

DinamoException.DinamoException In case of error

◆ OATHCheck() [3/4]

bool OATHCheck	(	string	masterKeyId,
		string	otp,
		byte[]	bBlob )

inline

Obsolete: Use OATHCheck with bBlob as a reference.

◆ OATHCheck() [4/4]

bool OATHCheck	(	string	masterKeyId,
		string	otp,
		byte[]	bBlob,
		int	dwFlag )

inline

Obsolete: Use OATHCheck with bBlob as a reference.

◆ OATHBlobResync() [1/2]

byte[] OATHBlobResync	(	string	szMasterKeyId,
		string	szOTP1,
		string	szOTP2,
		byte[]	bOATHBlob )

inline

Re-synchronizes a blob OATH by displaying two continuous OTP values.

Parameters

szMasterKeyId	Name of the master key, used to protect the blobs, of maximum size DinamoApi.MAX_OBJ_ID_FQN_LEN.
szOTP1	First OTP. Minimum length: DinamoApi.ISSUE_OATH_MIN_OTP_LEN; maximum length: DinamoApi.ISSUE_OATH_MAX_OTP_LEN.
szOTP2	The second OTP following the first. Minimum length: DinamoApi.ISSUE_OATH_MIN_OTP_LEN; maximum length: DinamoApi.ISSUE_OATH_MAX_OTP_LEN.
bOATHBlob	The OATH blob OATH will have the OTP verified. This buffer will be overwritten with the updated blob.

Returns: Blob from OATH resynchronized, result of the operation.

Exceptions

DinamoException.DinamoException Throws exception in case of error.

Starting with firmware version 4.0.2, the window will be extended by 200 intervals in both directions. For HOTP tokens, the intervals are counted by the number of events; for TOTP tokens, they are counted by the number of time steps.
If the error DinamoApi.D_OATH_BLOB_UPDATE is returned, this call must be retried using the OATHBlobResync(string,string,string,byte[],int) overload with the DinamoApi.OATH flag, which expands the buffer to DinamoApi.ISSUE_OATH_OUTPUT_MAX_BLOB_LEN and automatically repeats the operation to migrate the blob to the v2 format.

◆ OATHBlobResync() [2/2]

byte[] OATHBlobResync	(	string	szMasterKeyId,
		string	szOTP1,
		string	szOTP2,
		byte[]	bOATHBlob,
		int	dwFlags )

inline

Resynchronizes an OATH blob OATH providing two consecutive OTP values, with support for updating the blob format.

Parameters

szMasterKeyId	Name of the master key, used to protect the blobs, of maximum size DinamoApi.MAX_OBJ_ID_FQN_LEN.
szOTP1	First OTP. Minimum length: DinamoApi.ISSUE_OATH_MIN_OTP_LEN; maximum length: DinamoApi.ISSUE_OATH_MAX_OTP_LEN.
szOTP2	The second OTP following the first. Minimum length: DinamoApi.ISSUE_OATH_MIN_OTP_LEN; maximum length: DinamoApi.ISSUE_OATH_MAX_OTP_LEN.
bOATHBlob	The OATH blob OATH will have the OTP verified. This buffer will be overwritten with the updated blob.
dwFlags	Operation flags. When DinamoApi.OATH is specified and the firmware returns DinamoApi.D_OATH_BLOB_UPDATE, the method automatically expands the buffer to DinamoApi.ISSUE_OATH_OUTPUT_MAX_BLOB_LEN and repeats the call to migrate the blob to the v2 format. See details in the DinamoApi.OATH specification.

Returns: Blob from OATH resynchronized, result of the operation.

Exceptions

DinamoException.DinamoException Throws exception in case of error.

Starting with firmware version 4.0.2, the window will be extended by 200 intervals in both directions. For HOTP tokens, the intervals will be counted by the number of events; for TOTP tokens, they will be counted by the number of time steps.

◆ OATHGetKey()

byte[] OATHGetKey	(	string	szMasterKey,
		byte[]	pbInBlob )

inline

Retrieves the seed of the key generating the blob from OATH.

Parameters

szMasterKey	Name of the master key, used to protect the blobs, of maximum size DinamoApi.MAX_OBJ_ID_FQN_LEN.
pbInBlob	Blob content

Returns: Seed of the key in the form of a byte array.

Exceptions

DinamoException.DinamoException In case of error

Examples: oath.cs.

◆ OATHPskcTranslate()

DinamoApi.OATH_PSKC_TRANSLATE_OUTPUT[] OATHPskcTranslate	(	string	szMasterKeyId,
		string	szPSK,
		byte[]	pbPSKC )

inline

Imports seeds enveloped in the PSKC (Portable Symmetric Key Container) standard, RFC 6030.

Parameters

szMasterKeyId	Name of the master key, used to protect the blobs, of maximum size DinamoApi.MAX_OBJ_ID_FQN_LEN.
szPSK	Transport key that protects the seeds reported in pbPSKC.
pbPSKC	Contents of the file containing the seeds that will be transformed into blobs in HSM format

Returns: Array of DinamoApi structures .OATH_PSKC_TRANSLATE_OUTPUT. This structure will internally contain the blobs of the seeds translated into the HSM format and the identifier of each seed.

Exceptions

DinamoException.DinamoException In case of error

◆ OATHIssueGenerateHOTP() [1/2]

byte[] OATHIssueGenerateHOTP ( string szMasterKeyId )

inline

Generates a HOATH blob, i.e. an event token. The seed will be generated randomly by the HSM.

Parameters

szMasterKeyId Name of the master key, used to protect the blobs, of maximum size DinamoApi.MAX_OBJ_ID_FQN_LEN

Returns: Blob from OATH, the result of the operation.

Exceptions

DinamoException.DinamoException In case of error

This function is used when it is possible to assign a seed to a soft token. A seed with the size of a SHA1 will be generated

◆ OATHIssueGenerateHOTP() [2/2]

byte[] OATHIssueGenerateHOTP	(	string	szMasterKeyId,
		byte	seedLen )

inline

Generates a HOATH blob, i.e. an event token from a seed size.

Parameters

szMasterKeyId	Name of the master key, used to protect the blobs, of maximum size DinamoApi.MAX_OBJ_ID_FQN_LEN
seedLen	Seed in binary format.

Returns: Blob from OATH, the result of the operation.

Exceptions

DinamoException.DinamoException In case of error

This function is used when the seed is provided by a soft token software device (e.g. a cell phone app) or a hard_token hadware device (e.g. a sequence generator keychain).

◆ OATHIssueImportHOTP()

byte[] OATHIssueImportHOTP	(	string	szMasterKeyId,
		byte[]	bSeed )

inline

Imports a HOATH blob, i.e. an event token from a supplied seed.

Parameters

szMasterKeyId	Name of the master key, used to protect the blobs, of maximum size DinamoApi.MAX_OBJ_ID_FQN_LEN
bSeed	Seed in binary format.

Exceptions

DinamoException.DinamoException In case of error

Returns: Blob from OATH, the result of the operation.

◆ OATHIssueGenerateTOTP() [1/4]

byte[] OATHIssueGenerateTOTP ( string szMasterKeyId )

inline

Generates a TOTP blob, i.e. an event token. The seed will be generated randomly by the HSM.

Parameters

szMasterKeyId Name of the master key, used to protect the blobs, of maximum size DinamoApi.MAX_OBJ_ID_FQN_LEN

Returns: Blob from OATH, the result of the operation.

Exceptions

DinamoException In case of error

This function is used when it is possible to assign a seed to a soft token

Examples: oath.cs.

◆ OATHIssueGenerateTOTP() [2/4]

byte[] OATHIssueGenerateTOTP	(	string	szMasterKeyId,
		short	step )

inline

Generates a TOTP blob, i.e. an event token. The seed will be generated randomly by the HSM.

Parameters

szMasterKeyId	Name of the master key, used to protect the blobs, of maximum size DinamoApi.MAX_OBJ_ID_FQN_LEN
step	Time interval used in the calculation, also known as the time window for value change.

Returns: Blob from OATH, the result of the operation.

Exceptions

DinamoException.DinamoException In case of error

◆ OATHIssueGenerateTOTP() [3/4]

byte[] OATHIssueGenerateTOTP	(	string	szMasterKeyId,
		short	step,
		ulong	offset )

inline

Generates a TOTP blob, i.e. an event token. The seed will be generated randomly by the HSM.

Parameters

szMasterKeyId	Name of the master key, used to protect the blobs, of maximum size DinamoApi.MAX_OBJ_ID_FQN_LEN
step	Time interval used in the calculation, also known as the time window for value change.
offset	Clock delay to be considered.

Returns: Blob from OATH, the result of the operation.

Exceptions

DinamoException In case of error

◆ OATHIssueGenerateTOTP() [4/4]

byte[] OATHIssueGenerateTOTP	(	string	szMasterKeyId,
		short	step,
		ulong	offset,
		byte	seedLen )

inline

Generates a TOTP blob, i.e. an event token. The seed will be generated randomly by the HSM.

Parameters

szMasterKeyId	Name of the master key, used to protect the blobs, of maximum size DinamoApi.MAX_OBJ_ID_FQN_LEN
step	Time interval used in the calculation, also known as the time window for value change.
offset	Clock delay to be considered.
seedLen	Seed size.

Returns: Blob from OATH, the result of the operation.

Exceptions

DinamoException In case of error

◆ OATHIssueImportTOTP() [1/3]

byte[] OATHIssueImportTOTP	(	string	szMasterKeyId,
		byte[]	bSeed )

inline

Imports a TOTP blob, i.e. an event token from a supplied seed.

Parameters

szMasterKeyId	Name of the master key, used to protect the blobs, of maximum size DinamoApi.MAX_OBJ_ID_FQN_LEN
bSeed	Seed in binary format.

Returns: Blob from OATH, the result of the operation.

Exceptions

DinamoException.DinamoException In case of error

◆ OATHIssueImportTOTP() [2/3]

byte[] OATHIssueImportTOTP	(	string	szMasterKeyId,
		byte[]	bSeed,
		short	step )

inline

Imports a TOTP blob, i.e. an event token from a supplied seed.

Parameters

szMasterKeyId	Name of the master key, used to protect the blobs, of maximum size DinamoApi.MAX_OBJ_ID_FQN_LEN
bSeed	Seed in binary format.
step	Time interval used in the calculation, also known as the time window for value change.

Returns: Blob from OATH, the result of the operation.

Exceptions

DinamoException.DinamoException In case of error

◆ OATHIssueImportTOTP() [3/3]

byte[] OATHIssueImportTOTP	(	string	szMasterKeyId,
		byte[]	bSeed,
		short	step,
		ulong	offset )

inline

Imports a TOTP blob, i.e. an event token from a supplied seed.

Parameters

szMasterKeyId	Name of the master key, used to protect the blobs, of maximum size DinamoApi.MAX_OBJ_ID_FQN_LEN
bSeed	Seed in binary format.
step	Time interval used in the calculation, also known as the time window for value change.
offset	Clock delay to be considered.

Returns: Blob from OATH, the result of the operation.

Exceptions

DinamoException.DinamoException In case of error

◆ EncodeBase32()

string EncodeBase32 ( byte[] data )

inline

Utility function for encoding Base32. Standard encoding for OATH generators in sofware.

Derived from https://github.com/google/google-authenticator-android/blob/master /AuthenticatorApp/src/main/java/com/google/android/apps/authenticator/Base32String .java

Parameters

data	Generated seed

Returns: Data encoded in BASE32.

Examples: oath.cs.

◆ OATHGetNext()

string OATHGetNext	(	string	szMasterKeyId,
		byte	lenOTP,
		byte[]	bBlob )

inline

Retrieves the next value for the OTP.

Parameters

szMasterKeyId	Name of the master key, used to protect the blobs, of maximum size DinamoApi.MAX_OBJ_ID_FQN_LEN
lenOTP	Size of the OTP that will be generated, which can be a value between DinamoApi.ISSUE_OATH_MIN_OTP_LEN and DinamoApi.ISSUE_OATH_MAX_OTP_LEN.
bBlob	Byte array containing the blob that will be used to generate the OTP.

Returns: Value of the next token

Exceptions

DinamoException Throws exception in case of error.