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:` 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 Minimum size buffer 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).

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

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_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.

Return: 0 (ZERO) if the function is successful.
See 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	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 containing 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 Size of the pbInBlob buffer.

[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 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).

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

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 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(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 size buffer 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 `pvBlobList` buffer.
[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.