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:

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

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

b. Authentication

See below;

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

a. Generation

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

b. Authentication

See below;

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

a. Generation

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

b. Authentication

See below;

Scenario IV: Soft Token: HSM generates the seed

a. Generation

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

b. Authentication

See below;

User authentication in any scenario:

User submits generated OTP to application;
The application retrieves the user's blob from the database and requests verification from the HSM by passing the blob and OTP;
HSM processes request and returns result and processed blob;
The application receives the blob and updates the database;
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

Functions
bool	OATHCheck (string masterKeyId, string otp, byte[] bBlob)
	Check OTP value.

bool	OATHCheck (string masterKeyId, string otp, byte[] bBlob, int dwFlag)
	Check OTP value.

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/2]

bool OATHCheck	(	string	masterKeyId,
		string	otp,
		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.

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/2]

bool OATHCheck	(	string	masterKeyId,
		string	otp,
		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.

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

◆ 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[] date )

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

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