Detailed description

Standard authentication OATH.

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

Functions
int AAP_API	DOATHIssueBlob (HSESSIONCTX hSession, char szMasterKeyId, DWORD dwParamBlobType, void pvParamBlob, DWORD dwParamBlobLen, BYTE pbOTPBlob, DWORD pdwOTPBlobLen, DWORD dwFlags)

int AAP_API	DOATHCheckOTP (HSESSIONCTX hSession, char szMasterKeyId, char szOTP, BYTE pbOATHBlob, DWORD pdwOATHBlobLen, DWORD dwFlags)

int AAP_API	DOATHGetNextOTP (HSESSIONCTX hSession, char szMasterKeyId, BYTE bOTPLen, BYTE pbOATHBlob, DWORD dwOATHBlobLen, char *szOTP, DWORD dwFlags)

int AAP_API	DOATHOcraGen (HSESSIONCTX hSession, DWORD dwSetup, BYTE bOTPLen, const char szSK, const char szSuite, const BYTE pbCounter, const BYTE pbQuestion, BYTE bQuestionLen, const BYTE pbPinHash, const char szSession, const BYTE pbTimestamp, char szOTP, DWORD dwFlags)

int AAP_API	DOATHGetBlobInfo (const HSESSIONCTX hSession, char szMasterKey, BYTE pbInBlob, DWORD dwInBlobLen, DWORD dwOutBlobType, BYTE pbOutInfo, DWORD pdwOutInfoLen, DWORD dwParam)

int AAP_API	DOATHBlobResync (HSESSIONCTX hSession, char szMasterKeyId, char szOTP1, char szOTP2, BYTE pbOATHBlob, DWORD *pdwOATHBlobLen, DWORD dwFlags)

int AAP_API	DOATHPskcTranslate (HSESSIONCTX hSession, char szMasterKey, BYTE pbPSK, BYTE bPSKLen, BYTE pbPSKC, DWORD dwPSKCLen, void pvBlobList, DWORD pdwBlobListQuantity, DWORD dwParam)

Functions

◆ DOATHIssueBlob()

int AAP_API DOATHIssueBlob	(	HSESSIONCTX	hSession,
		char *	szMasterKeyId,
		DWORD	dwParamBlobType,
		void *	pvParamBlob,
		DWORD	dwParamBlobLen,
		BYTE *	pbOTPBlob,
		DWORD *	pdwOTPBlobLen,
		DWORD	dwFlags )

#include <dinamo.h>

Generates or imports a blob OATH for use in HSM.

Parameters

[in] hSession Context acquired through the DOpenSession() function.

[in] szMasterKeyId The name of the master key, used to protect the blobs, with a maximum length of MAX_OBJ_ID_FQN_LEN.

[in]

dwParamBlobType

The following table is supported.

Value	Meaning
ISSUE_OATH_GENERATE_HOTP	Type of `pvParamBlob:` ISSUE_OTP_BLOB structure. Generates HOTP blob in the HSM. The seed is generated inside the HSM. The following structure parameters must be filled in: `bSeedLen` and `bTruncationOffset`. The others must be set to zero.
ISSUE_OATH_GENERATE_TOTP	Type of `pvParamBlob:` ISSUE_OTP_BLOB structure. Generates TOTP blob in HSM. The seed is generated inside the HSM. The following structure parameters must be filled in: `bSeedLen`, `bTruncationOffset`, `wTimeStep` and `otT0`. The others must be set to zero.
ISSUE_OATH_IMPORT_HOTP	Type of `pvParamBlob:` ISSUE_OTP_BLOB structure. Imports a HOTP blob. The seed is passed by parameter. The following structure parameters must be filled in: `bSeedLen`, `pbSeed` and `bTruncationOffset`. The others must be set to zero.
ISSUE_OATH_IMPORT_TOTP	Type of `pvParamBlob:` ISSUE_OTP_BLOB structure. Imports a TOTP blob. Seed is passed by parameter. The following structure parameters must be filled in: `bUseDefaultMovingFactor`, `bSeedLen`, `pbSeed`, `bTruncationOffset`, `wTimeStep` and `otT0`. The others must be set to zero.

[in] pvParamBlob Pointer to the data or structures specified in dwParamBlobType.

[in] dwParamBlobLen Size of the data or structure specified in dwParamBlobType.

[out] pbOTPBlob Buffer with a minimum size of ISSUE_OATH_OUTPUT_MAX_BLOB_LEN that will contain the generated blob.

[in,out] pdwOTPBlobLen Size of the buffer pointed to by pbOTPBlob. On input it should contain the size of the pbOTPBlob buffer on output it will contain the size of the blob written to the allocated buffer.

[in] dwFlags Reserved for future use (must be 0).

Returns: 0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

Examples: gen_check_oath.c.

◆ DOATHCheckOTP()

int AAP_API DOATHCheckOTP	(	HSESSIONCTX	hSession,
		char *	szMasterKeyId,
		char *	szOTP,
		BYTE *	pbOATHBlob,
		DWORD *	pdwOATHBlobLen,
		DWORD	dwFlags )

#include <dinamo.h>

Checks an OTP value for a given blob OATH.

Parameters

[in] hSession Context acquired through the DOpenSession() function.

[in] szMasterKeyId The name of the master key, used to protect the blobs, with a maximum length of MAX_OBJ_ID_FQN_LEN.

[in] szOTP OTP to be verified with a minimum size of ISSUE_OATH_MIN_OTP_LEN and a maximum of ISSUE_OATH_MAX_OTP_LEN.

[in,out] pbOATHBlob Pointer to a buffer containing the blob whose OTP will be verified. This buffer will be rewritten with the updated buffer.

[in,out] pdwOATHBlobLen Size of the pbOATHBlob buffer. The input contains the size of pbOATHBlob and the output contains the size of the data written to pbOATHBlob.

[in]

dwFlags

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.
1 to MAX_OTP_LOOK_AHEAD_INTERVAL	Defines the value of the authentication look-ahead window.

You can also pass the OATH_UPDATE_BLOB flag in this parameter, to allow the format of the OATH blob to be updated. When the OATH_UPDATE_BLOB flag is used, the current OATH blob in pbOATHBlob must be passed in a buffer large enough to hold the updated blob. pdwOATHBlobLen must contain the value of the buffer size passed in pbOATHBlob. The size of pbOATHBlob required is returned in pdwOATHBlobLen in the call where the D_OATH_BLOB_UPDATE error is returned. The update only needs to be done after receiving the D_OATH_BLOB_UPDATE error. See Notes for more details.

Returns: 0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

Notes: If the D_OATH_BLOB_UPDATE error is returned, the function will return in pdwOATHBlobLen the size of the buffer that should be used to update the OATH blob in a subsequent call. See details in the specification of OATH_UPDATE_BLOB.

Examples: gen_check_oath.c.

◆ DOATHGetNextOTP()

int AAP_API DOATHGetNextOTP	(	HSESSIONCTX	hSession,
		char *	szMasterKeyId,
		BYTE	bOTPLen,
		BYTE *	pbOATHBlob,
		DWORD	dwOATHBlobLen,
		char *	szOTP,
		DWORD	dwFlags )

#include <dinamo.h>

Generates the next OTP from a blob OATH. The OATH blob will not be changed.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szMasterKeyId	The name of the master key, used to protect the blobs, with a maximum length of MAX_OBJ_ID_FQN_LEN.
[in]	bOTPLen	The size of the OTP to be generated, which can be a value between ISSUE_OATH_MIN_OTP_LEN and ISSUE_OATH_MAX_OTP_LEN.
[in]	pbOATHBlob	Pointer to a buffer containing the blob that will be used for OTP generation. This buffer will not be modified.
[in]	dwOATHBlobLen	Buffer size `pbOATHBlob`.
[out]	szOTP	Buffer containing the generated OTP. It must have a minimum size of `bOTPLen` + 1 (null terminator).
[in]	dwFlags	Reserved for future use (must be 0).

Returns: 0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

Examples: gen_check_oath.c.

◆ DOATHOcraGen()

int AAP_API DOATHOcraGen	(	HSESSIONCTX	hSession,
		DWORD	dwSetup,
		BYTE	bOTPLen,
		const char *	szSK,
		const char *	szSuite,
		const BYTE *	pbCounter,
		const BYTE *	pbQuestion,
		BYTE	bQuestionLen,
		const BYTE *	pbPinHash,
		const char *	szSession,
		const BYTE *	pbTimestamp,
		char *	szOTP,
		DWORD	dwFlags )

#include <dinamo.h>

Examples: ocra_gen.c.

◆ DOATHGetBlobInfo()

int AAP_API DOATHGetBlobInfo	(	const HSESSIONCTX	hSession,
		char *	szMasterKey,
		BYTE *	pbInBlob,
		DWORD	dwInBlobLen,
		DWORD	dwOutBlobType,
		BYTE *	pbOutInfo,
		DWORD *	pdwOutInfoLen,
		DWORD	dwParam )

#include <dinamo.h>

Retrieves the internal information of a blob OATH.

Parameters

[in] hSession Context acquired through the DOpenSession() function.

[in] szMasterKey The name of the master key, used to protect the blobs, with a maximum length of MAX_OBJ_ID_FQN_LEN.

[in] pbInBlob Pointer to a buffer containing the blob for information extraction.

[in] dwInBlobLen Size of the pbInBlob buffer.

[in]

dwOutBlobType

Indicates the output data type. The following table is supported.

Value	Meaning
OATH_ISSUE_OATH_BLOB_t	Type of pbOutInfo: ISSUE_OATH_BLOB_t. The pbInBlob buffer must be a V1-type blob with a size of ISSUE_OATH_OUTPUT_BLOB_V1_LEN.
OATH_ISSUE_OATH_INFO_t	Type of pbOutInfo: ISSUE_OATH_INFO_t. This option accepts V1- and V2-type blobs with sizes ISSUE_OATH_OUTPUT_BLOB_V1_LEN and ISSUE_OATH_OUTPUT_BLOB_V2_LEN, respectively.

[out] pbOutInfo Pointer to a buffer that will receive the blob information. It must be as described in dwOutBlobType.

[in,out] pdwOutInfoLen Size of the buffer pointed to by pdwOutInfoLen.

[in] dwParam Reserved for future use (must be 0).

Returns: 0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

◆ DOATHBlobResync()

int AAP_API DOATHBlobResync	(	HSESSIONCTX	hSession,
		char *	szMasterKeyId,
		char *	szOTP1,
		char *	szOTP2,
		BYTE *	pbOATHBlob,
		DWORD *	pdwOATHBlobLen,
		DWORD	dwFlags )

#include <dinamo.h>

Re-synchronizes a blob OATH by displaying two continuous OTP values. Only for HOTP (OTP per event).

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szMasterKeyId	The name of the master key, used to protect the blobs, with a maximum length of MAX_OBJ_ID_FQN_LEN.
[in]	szOTP1	OTP to be verified with a minimum size of ISSUE_OATH_MIN_OTP_LEN and a maximum of ISSUE_OATH_MAX_OTP_LEN.
[in]	szOTP2	Second OTP to be verified, with a minimum length of ISSUE_OATH_MIN_OTP_LEN and a maximum of ISSUE_OATH_MAX_OTP_LEN.
[in,out]	pbOATHBlob	Pointer to a buffer containing the blob to be synchronized. This buffer will be overwritten with the synchronized buffer.
[in,out]	pdwOATHBlobLen	Size of the `pbOATHBlob` buffer. The input contains the size of `pbOATHBlob` and the output contains the size of the data written to `pbOATHBlob`.
[in]	dwFlags	Accepts the flag OATH_UPDATE_BLOB, to allow the format of the OATH blob to be updated. When the OATH_UPDATE_BLOB flag is used, the current OATH blob in `pbOATHBlob` must be passed in a buffer large enough to hold the updated blob. `pdwOATHBlobLen` must contain the value of the buffer size passed in `pbOATHBlob`. The size of `pbOATHBlob` required is returned in `pdwOATHBlobLen` in the call where the D_OATH_BLOB_UPDATE error is returned. The update only needs to be done after receiving the D_OATH_BLOB_UPDATE error. See Notes for more details.

Returns: 0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

Notes: As of firmware version 4.0.2, the window will be extended by up to 200 intervals. 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. If the D_OATH_BLOB_UPDATE error is returned, the function will return in pdwOATHBlobLen the size of the buffer that should be used to update the OATH blob in a subsequent call. See details in the specification of OATH_UPDATE_BLOB.

◆ DOATHPskcTranslate()

int AAP_API DOATHPskcTranslate	(	HSESSIONCTX	hSession,
		char *	szMasterKey,
		BYTE *	pbPSK,
		BYTE	bPSKLen,
		BYTE *	pbPSKC,
		DWORD	dwPSKCLen,
		void **	pvBlobList,
		DWORD *	pdwBlobListQuantity,
		DWORD	dwParam )

#include <dinamo.h>

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

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szMasterKey	Name of the master key, used to protect the blobs, with a maximum output size of MAX_OBJ_ID_FQN_LEN.
[in]	pbPSK	Maximum size buffer OATH_MAX_PSK_LEN containing the transport key that protects the seeds reported in `pbPSKC`.
[in]	bPSKLen	Size of the pbPSK buffer.
[in]	pbPSKC	PSKC buffer containing the seeds that will be transformed into blobs in the HSM format.
[in]	dwPSKCLen	Size of the pbPSKC buffer.
[out]	pvBlobList	Ponteiro para ponteiro que apontará para um buffer alocado internamente contendo um array de estruturas OATH_PSKC_TRANSLATE_OUTPUT. Esta estrutura conterá internamente os blobs das sementes traduzidas para o formato do HSM e o identificador de cada semente como na tag "<pskc:Key Id=>".
[out]	pdwBlobListQuantity	Pointer to the number of blobs returned in the `pvBlobList` buffer.
[in]	dwParam	Reserved for future use (must be 0).

Returns: 0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.