OATH

Detailed description

Standard authentication OATH.

Initiative OATH

The OATH (Open Authentication) initiative is a collaboration supported by various members of the security industry to develop an open and interoperable strong authentication architecture. This goal is achieved by defining open standards available to all.

The OATH ecosystem is made up of device manufacturers (tokens, chips, smart cards, computers, cell phones, PDAs, tablets), platform manufacturers (web services, identity managers, application servers, identification federation systems), application manufacturers (VPN, CRM, ERP, DRM, e-commerce, roaming, Wi-Fi) and system integrators (ISPs, government agencies, credit card brands, etc.).

Module OATH

The HSM can be used as a seed generator OATH and as an OTP (One Time Password) authenticator. The HSM implementation complies with the standards listed below.

By providing a secure cryptographic frontier, a controlled environment and approved algorithms, HSM has advantages when it comes to being adopted as a strong authentication system.

HSM's OATH module has three basic services: issuing, authentication and resynchronization:

1. emission consists of the HSM generating the seed, which causes the emission of a blob, which is returned to the application for storage in a database. With the blob kept in a database external to the HSM, the emission process is very flexible, without generating a load on the HSM, and maintaining the necessary secrecy and confidentiality.
2. the module's authentication service is certainly the most used in day-to-day production. When the application needs to perform an authentication, it must retrieve the blob from the database, send it to the HSM, receive the result together with the updated blob, to be returned to the database.
3. the resynchronization service basically consists of opening the normal tolerance window and asking the user to enter OTPs n and n+1.

Generation and Authentication Scenarios

In the generation and authentication scenarios described below, what changes is the origin of the seed and how it is received by the application to create the blob and sent to the user (as a seed or embedded in a physical token). Once the blob has been created, authentication in any scenario always follows the same format. In the scenarios below, it doesn't matter whether the token is HOTP or TOTP.

Scenario I: Token: the seed is generated by the token manufacturer and sent in PSKC format

a. Generation

1. Application selects or generates a master key;
2. Application receives PSKC file and transport key;
3. Application asks HSM to translate PSKC file into blob;
4. HSM returns blob;
5. Application receives blob, creates relationship between blob and user and stores in database;
6. The application sends the physical token to the user;

b. Authentication

1. See below;

Scenario II: Token: the seed is generated by the token manufacturer and sent in clear text

a. Generation

1. Application selects or generates a master key;
2. Application receives a seed in clear text;
3. Application prepares a blob structure OATH;
4. The application asks the HSM to encrypt the blob OATH with the master key;
5. HSM returns encrypted data, which is the blob;
6. Application receives blob, creates relationship between blob and user and stores in database;
7. The application sends the physical token to the user;

b. Authentication

1. See below;

Scenario III: Soft Token: the seed is generated by the user and received in clear text

a. Generation

1. Application selects or generates a master key;
2. User generates and exports seed in their application OATH (smart phone, desktop, etc.);
3. User sends seed to application;
4. Application receives a seed in clear text;
5. Application prepares a data structure OATH;
6. The application asks the HSM to encrypt the data structure OATH with the master key;
7. HSM returns an encrypted structure, which is the blob;
8. Application receives blob, creates relationship between blob and user and stores in database;

b. Authentication

1. See below;

Scenario IV: Soft Token: HSM generates the seed

a. Generation

1. Application selects or generates a master key;
2. Application requests blob issue OATH;
3. HSM generates seed, prepares blob and returns to application;
4. Application receives blob, creates relationship between blob and user and stores in database;
5. Application sends the blob to HSM and requests the seed in clear text;
6. The application sends the seed to the user, usually using a secure channel;
7. User imports seed into their application OATH (smart phone, desktop, etc.);

b. Authentication

1. See below;

User authentication in any scenario:

1. User submits generated OTP to application;
2. The application retrieves the user's blob from the database and requests verification from the HSM by passing the blob and OTP;
3. HSM processes request and returns result and processed blob;
4. The application receives the blob and updates the database;
5. Application informs user of authentication result;

Glossary

• otp: (one time password), one-time password
• token: physical device that generates otp from a seed, usually identified by a unique serial number and the size of a keychain. It is tamper-resistant.
• soft token: software-based token-generating device, usually installed on a mobile device. It is less secure than the physical token.
• seed: random sequence of bytes used as diversifying cryptographic material for generating otp. It must be kept secret from generation to use, including transportation. Each token or soft token must be associated with a single seed.
• time step: interval used to increment the TOTP calculation for each OTP. The time in seconds between each OTP generation.
• moving factor: interval used as an increment in the HOTP calculation for each OTP. Counted by events.
• T0: UNIX time value (seconds from EPOCH time) to start counting time steps.
• truncation offset: method of truncating the HMAC calculation to extract the OTP.
• HOTP: (HMAC-based One-time Password Algorithm) standard for generating otp per event, usually triggered by the user, such as pressing a button on the token, i.e. each time the user presses the button on the token, a new otp is generated.
• TOTP: (Time-based One-time Password Algorithm) standard for generating otp by time; a new otp is generated at each interval defined by the token, regardless of user action.
• blob: (binary large object), encrypted structure containing information for otp authentication. The blob is completely opaque outside the HSM. The key that encrypts the blob is AES (128, 192 or 256 bits). The information contained in the blob includes the seed, type (HOTP or TOTP), generation interval and start time (in the case of TOTP) and protection mechanisms against replay attacks.
• resync: the process of adjusting a blob's internal counters to the values generated by the physical token or soft token in order to keep authentication working correctly. This process is usually done by temporarily increasing the tolerance window and searching for otp values by the HSM, with the user informing two or more otps generated in sequence by the token.
• master key: AES key in the HSM that encrypts the blob.
• transport key: key that encrypts the seeds corresponding to the tokens according to the PSKC standard, for transport between the token manufacturer and the system integrator. It is usually derived from a password.
• pskc: (Portable Symmetric Key Container), a standard for the secure transport and delivery of seeds, based on symmetric cryptography with password key derivation and XML format.
• pskc translation: process of importing the seeds in PSKC format, decrypting them and generating individual blobs for storage in the database. The process of translating the decryption of the PSKC format and encryption into the blob is carried out within the HSM. Normally a PSKC file contains several seeds encrypted under the same transport key; each seed will correspond to a blob.
• database: structure for storing the blobs generated by the HSM. This could be a file system or a DBMS (Database Management System), for example. There is no need for additional protection for the stored blob, as its contents can only be accessed with the AES master key in the HSM.

References

• Initiative OATH
• OATH Reference Architecture Version 2.0
• HOTP: An HMAC-Based OTP Algorithm RFC 4226
• TOTP - Time-based One-time Password Algorithm RFC 6238
• PSKC - Portable Symmetric Key Container, RFC 6030

Standard authentication OATH. More...

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.