Detailed description

Standard authentication OATH.

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	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 Name of the master key, used to protect the blobs, of maximum size MAX_OBJ_ID_FQN_LEN.

[in]

dwParamBlobType

The following table is accepted.

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

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

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

[out] pbOTPBlob Minimum size buffer of ISSUE_OATH_OUTPUT_MAX_BLOB_LEN that will contain the generated blob.

[in,out] pdwOTPBlobLen Buffer size pointed to by pbOTPBlob. The entry must contain the buffer size pbOTPBlob in the output will contain the size of the blob written to the allocated buffer.

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

Return: 0 (ZERO) if the function is successful.
See 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 Name of the master key, used to protect the blobs, of maximum size MAX_OBJ_ID_FQN_LEN.

[in] szOTP OTP to be checked for minimum size ISSUE_OATH_MIN_OTP_LEN and maximum ISSUE_OATH_MAX_OTP_LEN.

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

[in,out] pdwOATHBlobLen Buffer size pbOATHBlob. The entry will contain the size of pbOATHBlob and output the size of data written in pbOATHBlob.

[in]

dwFlags

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

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

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

Notes: If the error is returned D_OATH_BLOB_UPDATE the function will return in pdwOATHBlobLen the size of the buffer that should be used to update the OATH blob in a later call. See details in the 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	Name of the master key, used to protect the blobs, of maximum size MAX_OBJ_ID_FQN_LEN.
[in]	bOTPLen	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 to generate the OTP. This buffer will not be changed.
[in]	dwOATHBlobLen	Buffer size `pbOATHBlob`.
[out]	szOTP	Buffer that will contain the generated OTP. It must have a minimum size of `bOTPLen` + 1 (null terminator).
[in]	dwFlags	Reserved for future use (must be 0).

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

Examples: gen_check_oath.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 Name of the master key, used to protect the blobs, of maximum size MAX_OBJ_ID_FQN_LEN.

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

[in] dwInBlobLen Buffer size pbInBlob.

[in]

dwOutBlobType

Indicates the type of output data. The following table is accepted.

Value	Meaning
OATH_ISSUE_OATH_BLOB_t	Type of pbOutInfo: ISSUE_OATH_BLOB_t. The pbInBlob Buffer must be a V1 type blob with size ISSUE_OATH_OUTPUT_BLOB_V1_LEN.
OATH_ISSUE_OATH_INFO_t	Type of pbOutInfo: ISSUE_OATH_INFO_t. This option accepts blobs of type V1 and V2 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 information from the blob. It should be as described in dwOutBlobType.

[in,out] pdwOutInfoLen Buffer size pointed to by pdwOutInfoLen.

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

Return: 0 (ZERO) if the function is successful.
See 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	Name of the master key, used to protect the blobs, of maximum size MAX_OBJ_ID_FQN_LEN.
[in]	szOTP1	OTP to be checked for minimum size ISSUE_OATH_MIN_OTP_LEN and maximum ISSUE_OATH_MAX_OTP_LEN.
[in]	szOTP2	Second OTP to be checked for minimum size ISSUE_OATH_MIN_OTP_LEN and maximum ISSUE_OATH_MAX_OTP_LEN.
[in,out]	pbOATHBlob	Pointer to a buffer containing the blob to be synchronized. This buffer will be rewritten with the synchronized buffer.
[in,out]	pdwOATHBlobLen	Buffer size `pbOATHBlob`. The entry will contain the size of `pbOATHBlob` and output the size of data written in `pbOATHBlob`.
[in]	dwFlags	Accept the flag OATH_UPDATE_BLOBto allow the format of the OATH blob to be updated. When the OATH_UPDATE_BLOB is used, you must pass the current OATH blob in `pbOATHBlob` in a buffer large enough to hold the updated blob. `pdwOATHBlobLen` should contain the value of the buffer size passed in `pbOATHBlob`. The size of `pbOATHBlob` required, is returned in `pdwOATHBlobLen` in the call where the error D_OATH_BLOB_UPDATE is returned. The update only needs to be done after receiving the error D_OATH_BLOB_UPDATE. See Notes for more details.

Return: 0 (ZERO) if the function is successful.
See 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 error D_OATH_BLOB_UPDATE the function will return in pdwOATHBlobLen the size of the buffer that should be used to update the OATH blob in a later call. See details in the 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(Portable Symmetric Key Container) standard, RFC 6030.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szMasterKey	Name of the master key, used to protect the blobs, of maximum size MAX_OBJ_ID_FQN_LEN output.
[in]	pbPSK	Maximum buffer size OATH_MAX_PSK_LEN containing the transport key that protects the seeds reported in `pbPSKC`.
[in]	bPSKLen	Buffer size pbPSK.
[in]	pbPSKC	PSKC buffer containing the seeds that will be transformed into blobs in the HSM format.
[in]	dwPSKCLen	Buffer size pbPSKC.
[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 buffer `pvBlobList`.
[in]	dwParam	Reserved for future use (must be 0).

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