Detailed description

Standard authentication OATH.

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

Standard authentication OATH. More...

Functions
byte[]	generateOATHHotpBlob (String masterKey) throws TacException
	Generates a blob OATH HOTP(HMAC-based One-Time Password).

byte[]	generateOATHHotpBlob (String masterKey, byte seedLen) throws TacException
	Generates a blob OATH HOTP(HMAC-based One-Time Password).

byte[]	generateOATHHotpBlob (String masterKey, byte seedLen, byte truncationOffset) throws TacException
	Generates a blob OATH HOTP(HMAC-based One-Time Password).

byte[]	importOATHHotpBlob (String masterKey, byte[] seed) throws TacException
	Generates a blob OATH HOTP(HMAC-based One-Time Password).

byte[]	generateOATHTotpBlob (String masterKey) throws TacException
	Generates a blob OATH TOTP(Time-based One-Time Password).

byte[]	generateOATHTotpBlob (String masterKey, byte seedLen, byte truncationOffset, int timeStep, long t0) throws TacException
	Generates a blob OATH TOTP(Time-based One-Time Password).

byte[]	importOATHTotpBlob (String masterKey, byte[] seed, byte truncationOffset, int timeStep, long t0, boolean useDefaultMovingFactor, long movingFactor) throws TacException
	Generates a blob OATH TOTP(Time-based One-Time Password).

byte[]	importOATHTotpBlob (String masterKey, byte[] seed) throws TacException
	Generates a blob OATH TOTP(Time-based One-Time Password).

byte[]	getOATHSeed (String masterKey, byte[] blob) throws TacException
	Retrieves the seed from the blob OATH.

String	getNextOATHOTP (String masterKey, int otpLen, byte[] oathBlob) throws TacException
	Generates the next OTP from the OATH informed blob.

byte[]	checkOATHBlobOTP (String masterKey, String otp, byte[] oathBlob) throws TacException
	Checks an OTP value for a given blob OATH.

byte[]	resyncOATHBlobOTP (String masterKey, String otp1, String otp2, byte[] oathBlob) throws TacException
	Re-synchronizes a blob OATH by displaying two continuous OTP values.

String	oathOcraGen (int setup, int otpLen, String skId, String suite, byte[] counter, byte[] question, byte[] pinHash, String session, byte[] timestamp) throws TacException
	Generates an OCRA (OATH Algorithm) value in accordance with RFC 6287.

Functions

◆ generateOATHHotpBlob() [1/3]

byte[] generateOATHHotpBlob ( String masterKey ) throws TacException

Generates a blob OATH HOTP(HMAC-based One-Time Password).

Also known as OTP per event. The seed is generated inside the HSM. Seed size TacNDJavaLib.ISSUE_OATH_SHA1_LEN.

Parameters

masterKey Name of the master key used to protect the blobs.

Return: Returns the blob OATH.

Exceptions

TacException

◆ generateOATHHotpBlob() [2/3]

byte[] generateOATHHotpBlob	(	String	masterKey,
		byte	seedLen ) throws TacException

Generates a blob OATH HOTP(HMAC-based One-Time Password).

Also known as OTP per event. The seed is generated within the HSM.

Parameters

masterKey Name of the master key used to protect the blobs.

seedLen

Sets the seed size OATH. The following values are accepted.

Value	Size in bytes
TacNDJavaLib.ISSUE_OATH_SHA1_LEN	20
TacNDJavaLib.ISSUE_OATH_SHA256_LEN	32
TacNDJavaLib.ISSUE_OATH_SHA512_LEN	64

Return: Returns the blob OATH.

Exceptions

TacException

◆ generateOATHHotpBlob() [3/3]

byte[] generateOATHHotpBlob	(	String	masterKey,
		byte	seedLen,
		byte	truncationOffset ) throws TacException

Generates a blob OATH HOTP(HMAC-based One-Time Password).

Also known as OTP per event. The seed is generated within the HSM.

Parameters

masterKey Name of the master key used to protect the blobs.

seedLen

Sets the seed size OATH. The following values are accepted.

Value	Size in bytes
TacNDJavaLib.ISSUE_OATH_SHA1_LEN	20
TacNDJavaLib.ISSUE_OATH_SHA256_LEN	32
TacNDJavaLib.ISSUE_OATH_SHA512_LEN	64

truncationOffset

The following amount is supported:

Value	Meaning
TacNDJavaLib.ISSUE_OATH_DYN_TRUNC	Defines the "truncation" algorithm as dynamic.

Return: Returns the blob OATH.

Exceptions

TacException

◆ importOATHHotpBlob()

byte[] importOATHHotpBlob	(	String	masterKey,
		byte[]	seed ) throws TacException

Generates a blob OATH HOTP(HMAC-based One-Time Password).

Also known as event-based OTP. The seed is imported by the caller.

Parameters

masterKey Name of the master key used to protect the blobs.

seed

Define a seed OATH. The following sizes are accepted.

Value	Size in bytes
TacNDJavaLib.ISSUE_OATH_SHA1_LEN	20
TacNDJavaLib.ISSUE_OATH_SHA256_LEN	32
TacNDJavaLib.ISSUE_OATH_SHA512_LEN	64

Return: Returns the blob OATH.

Exceptions

TacException

◆ generateOATHTotpBlob() [1/2]

byte[] generateOATHTotpBlob ( String masterKey ) throws TacException

Generates a blob OATH TOTP(Time-based One-Time Password).

Also known as OTP by time. The seed is generated inside the HSM. Seed of size TacNDJavaLib.ISSUE_OATH_SHA1_LEN.

Parameters

masterKey Name of the master key used to protect the blobs.

Return: Returns the blob OATH.

Exceptions

TacException

◆ generateOATHTotpBlob() [2/2]

byte[] generateOATHTotpBlob	(	String	masterKey,
		byte	seedLen,
		byte	truncationOffset,
		int	timeStep,
		long	t0 ) throws TacException

Generates a blob OATH TOTP(Time-based One-Time Password).

Also known as OTP by time. The seed is generated inside the HSM.

Parameters

masterKey Name of the master key used to protect the blobs.

seedLen

Sets the seed size OATH. The following values are accepted.

Value	Size in bytes
TacNDJavaLib.ISSUE_OATH_SHA1_LEN	20
TacNDJavaLib.ISSUE_OATH_SHA256_LEN	32
TacNDJavaLib.ISSUE_OATH_SHA512_LEN	64

truncationOffset

The following amount is supported:

Value	Meaning
TacNDJavaLib.ISSUE_OATH_DYN_TRUNC	Defines the "truncation" algorithm as dynamic.

timeStep

Time step value in seconds. In addition to setting the time step in seconds for TOTP blobs, the following values are also supported.

Value	Meaning
TacNDJavaLib.ISSUE_OATH_DEFAULT_TIME_STEP	Use the default HSM time step value, currently 30 secs.
TacNDJavaLib.ISSUE_OATH_HOTP_TS	Use this value when dealing with HOTP.

t0

Initial time value.

Value	Meaning
TacNDJavaLib.ISSUE_OATH_HOTP_T0	Use HSM's default value.

Return: Returns the blob OATH.

Exceptions

TacException

◆ importOATHTotpBlob() [1/2]

byte[] importOATHTotpBlob	(	String	masterKey,
		byte[]	seed,
		byte	truncationOffset,
		int	timeStep,
		long	t0,
		boolean	useDefaultMovingFactor,
		long	movingFactor ) throws TacException

Generates a blob OATH TOTP(Time-based One-Time Password).

Also known as OTP by time. The seed is imported by the caller.

Parameters

masterKey Name of the master key used to protect the blobs.

seed

Define a seed OATH. The following sizes are accepted.

Value	Size in bytes
TacNDJavaLib.ISSUE_OATH_SHA1_LEN	20
TacNDJavaLib.ISSUE_OATH_SHA256_LEN	32
TacNDJavaLib.ISSUE_OATH_SHA512_LEN	64

truncationOffset

The following amount is supported:

Value	Meaning
TacNDJavaLib.ISSUE_OATH_DYN_TRUNC	Defines the "truncation" algorithm as dynamic.

timeStep

Time step value in seconds. In addition to setting the time step in seconds for TOTP blobs, the following values are also supported.

Value	Meaning
TacNDJavaLib.ISSUE_OATH_DEFAULT_TIME_STEP	Use the default HSM time step value, currently 30 secs.
TacNDJavaLib.ISSUE_OATH_HOTP_TS	Use this value when dealing with HOTP.

t0

Initial time value.

Value	Meaning
TacNDJavaLib.ISSUE_OATH_HOTP_T0	Use HSM's default value.

useDefaultMovingFactor Set to true to use the default moving factor or to false to specify a moving factor in movingFactor.

movingFactor

Sets the customer's initial increment before use. In addition to setting the increment manually, you can use the values in the following table.

Value	Meaning
TacNDJavaLib.ISSUE_OATH_INIT_MF	Uses standard moving factor value.

Return: Returns the blob OATH.

Exceptions

TacException

◆ importOATHTotpBlob() [2/2]

byte[] importOATHTotpBlob	(	String	masterKey,
		byte[]	seed ) throws TacException

Generates a blob OATH TOTP(Time-based One-Time Password).

Also known as OTP by time. The seed is imported by the caller.

Parameters

masterKey Name of the master key used to protect the blobs.

seed

Define a seed OATH. The following sizes are accepted.

Value	Size in bytes
TacNDJavaLib.ISSUE_OATH_SHA1_LEN	20
TacNDJavaLib.ISSUE_OATH_SHA256_LEN	32
TacNDJavaLib.ISSUE_OATH_SHA512_LEN	64

Return: Returns the blob OATH.

Exceptions

TacException

◆ getOATHSeed()

byte[] getOATHSeed	(	String	masterKey,
		byte[]	blob ) throws TacException

Retrieves the seed from the blob OATH.

Parameters

masterKey	Name of the master key used to protect the blobs.
blob	blob OATH.

Return: Seed associated with the blob OATH.

Exceptions

TacException

◆ getNextOATHOTP()

String getNextOATHOTP	(	String	masterKey,
		int	otpLen,
		byte[]	oathBlob ) throws TacException

Generates the next OTP from the OATH informed blob.

Parameters

masterKey	name of the master key used to protect the blobs.
otpLen	size of the OTP to be generated. Minimum size TacNDJavaLib.ISSUE_OATH_MIN_OTP_LEN and maximum TacNDJavaLib.ISSUE_OATH_MAX_OTP_LEN.
oathBlob	blob that will be used to generate the OTP. This buffer will not be altered.

Return: Returns the generated OTP.

Exceptions

TacException

◆ checkOATHBlobOTP()

byte[] checkOATHBlobOTP	(	String	masterKey,
		String	otp,
		byte[]	oathBlob ) throws TacException

Checks an OTP value for a given blob OATH.

Parameters

masterKey	Name of the master key used to protect the blobs.
otp	OTP to be checked. Minimum size TacNDJavaLib.ISSUE_OATH_MIN_OTP_LEN and maximum TacNDJavaLib.ISSUE_OATH_MAX_OTP_LEN.
oathBlob	blob that will have the OTP checked. This buffer will be rewritten with the updated buffer.

Return: blob OATH updated.

Exceptions

TacException

Notes: If the D_OATH_BLOB_UPDATE error is thrown, this call must be redone by passing the oathBlob with a size of ISSUE_OATH_OUTPUT_MAX_BLOB_LEN containing the current blob, so that the blob is updated. See details in the specification of OATH_UPDATE_BLOB.

◆ resyncOATHBlobOTP()

byte[] resyncOATHBlobOTP	(	String	masterKey,
		String	otp1,
		String	otp2,
		byte[]	oathBlob ) throws TacException

Re-synchronizes a blob OATH by displaying two continuous OTP values.

Only for HOTP (OTP per event).

Parameters

masterKey	Name of the master key used to protect the blobs.
otp1	First OTP. Minimum size TacNDJavaLib.ISSUE_OATH_MIN_OTP_LEN and maximum TacNDJavaLib.ISSUE_OATH_MAX_OTP_LEN.
otp2	Second OTP. Minimum size TacNDJavaLib.ISSUE_OATH_MIN_OTP_LEN and maximum TacNDJavaLib.ISSUE_OATH_MAX_OTP_LEN.
oathBlob	blob that will have the OTP checked. This buffer will be rewritten with the updated buffer.

Return: blob OATH updated.

Exceptions

TacException

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 thrown, this call must be redone by passing the oathBlob with a size of ISSUE_OATH_OUTPUT_MAX_BLOB_LEN containing the current blob, so that the blob is updated. See details in the specification of OATH_UPDATE_BLOB.

◆ oathOcraGen()

String oathOcraGen	(	int	setup,
		int	otpLen,
		String	skId,
		String	suite,
		byte[]	counter,
		byte[]	question,
		byte[]	pinHash,
		String	session,
		byte[]	timestamp ) throws TacException

Generates an OCRA (OATH Algorithm) value in accordance with RFC 6287.

Parameters

setup	Flags that enable optional fields in the OCRA calculation. The following table is supported. Value \| Meaning :-—\|:-------— `TacNDJavaLib#DN_OATH_OCRA_USE_CTR` \| Includes the counter field in the calculation. `TacNDJavaLib#DN_OATH_OCRA_USE_PH20` \| Includes the SHA-1 hash of the password in pinHash (20 bytes). `TacNDJavaLib#DN_OATH_OCRA_USE_PH32` \| Includes the SHA-256 hash of the password in pinHash (32 bytes). `TacNDJavaLib#DN_OATH_OCRA_USE_PH64` \| Includes the SHA-512 hash of the password in pinHash (64 bytes). `TacNDJavaLib#DN_OATH_OCRA_USE_TS` \| Includes the timestamp in the calculation.
otpLen	Length of the generated OTP in digits, between `TacNDJavaLib#ISSUE_OATH_MIN_OTP_LEN` and `TacNDJavaLib#ISSUE_OATH_MAX_OTP_LEN`.
skId	Name of the HMAC key (SHA-1, SHA-256, or SHA-512) in the HSM used in the calculation. Maximum size `TacNDJavaLib#MAX_OBJ_ID_FQN_LEN`.
suite	OCRA suite string as per RFC 6287. Maximum size `TacNDJavaLib#DN_OATH_OCRA_MAX_SUITE_LEN`.
counter	Counter for `TacNDJavaLib#DN_OATH_OCRA_CTR_LEN` bytes. Required when `TacNDJavaLib#DN_OATH_OCRA_USE_CTR` is set in setup; otherwise ignored. May be null.
question	Challenge. Required. Maximum length `TacNDJavaLib#DN_OATH_OCRA_MAX_Q_LEN`.
pinHash	User password hash. The size must be compatible with the hash flag defined in setup (`TacNDJavaLib#DN_OATH_OCRA_USE_PH20`, `TacNDJavaLib#DN_OATH_OCRA_USE_PH32` or `TacNDJavaLib#DN_OATH_OCRA_USE_PH64`). It may be null if no hash flags are active.
session	Client session information. Maximum size `TacNDJavaLib#DN_OATH_OCRA_CSESS_MAX_LEN`. May be null.
timestamp	Timestamp of `TacNDJavaLib#DN_OATH_OCRA_TIME_STEPS_LEN` bytes. Required when `TacNDJavaLib#DN_OATH_OCRA_USE_TS` is set in setup; otherwise ignored. May be null.

Return: OTP generated as a string with a length equal to otpLen digits.

Exceptions

TacException