Detailed description

Standard authentication OATH.

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[]	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

Return: >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

As of firmware version 4.0.2, the size of the authentication look-ahead window can be set in this parameter. The default is 10 intervals more or less. In the case of HOTP tokens, the intervals will be counted by number of events; in the case of TOTP tokens, they will be counted by number of time-steps.

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

Return: 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()

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 value from OATH.
szOTP2	Second value of OATH
bOATHBlob	Blob of OATH

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

Exceptions

DinamoException.DinamoException In case of error

◆ 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

Return: 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

Return: 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

Return: 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.

Return: 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

Return: 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

Return: 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.

Return: 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.

Return: 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.

Return: 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.

Return: 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.

Return: 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.

Return: 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

Return: 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.

Return: Value of the next token

Exceptions

DinamoException Throws exception in case of error.