com.gemalto.idp.mobile.otp.oath

Interface OathDevice

public interface OathDevice

An interface defining a device that generates OATH based OTPs.

Since:

4.0

Method Summary

Modifier and Type	Method and Description
SecureString	getHotp(AuthInput authInput) Gets an event based OTP (HOTP).
int	getLastOtpLifespan() Return lifespan of the last OTP computed by this device.
SecureString	getOcraOtp(AuthInput authInput, SecureByteArray serverChallengeQuestion, SecureByteArray clientChallengeQuestion, SecureByteArray passwordHash, SecureByteArray session) Gets an OCRA OTP.
SecureString	getOcraPasswordHash(SecureString password) Get password hash value according the algorithm defined by settings.
SecureString	getTotp(AuthInput authInput) Gets a time based OTP (TOTP).

Method Detail

getHotp

SecureString getHotp(AuthInput authInput)
              throws IdpException

Gets an event based OTP (HOTP).

Parameters:

authInput - the AuthInput

Returns:

the OTP

Throws:

IllegalStateException - when the associated token has the OathToken.TokenCapability.DUAL_SEED capability because only time based algorithms are supported for this capability.

IdpRuntimeException - when there is a cryptography operation failure.

IdpException - this is generic exception, you can directly catch this exception or catch each specific exception below.

IdpStorageException - when there is a database operation failure.

DeviceFingerprintException - when the token's fingerprint checksum does not match.

PasswordManagerException - when the TOKEN domain is not logged in (using one of the password managers)

IdpAuthException - when the TOKEN is not migrated

Since:

4.0

getTotp

SecureString getTotp(AuthInput authInput)
              throws IdpException

Gets a time based OTP (TOTP).

Parameters:

authInput - the AuthInput

Returns:

the OTP

Throws:

IdpRuntimeException - when there is a cryptography operation failure.

IdpException - this is generic exception, you can directly catch this exception or catch each specific exception below.

IdpStorageException - when there is a database operation failure

DeviceFingerprintException - when the token's fingerprint checksum does not match.

PasswordManagerException - when the TOKEN domain is not logged in (using one of the password managers)

IdpAuthException - when the TOKEN is not migrated

Since:

4.0

getOcraOtp

SecureString getOcraOtp(AuthInput authInput,
                        SecureByteArray serverChallengeQuestion,
                        SecureByteArray clientChallengeQuestion,
                        SecureByteArray passwordHash,
                        SecureByteArray session)
                 throws IdpException

Gets an OCRA OTP.

Parameters:

authInput - the AuthInput

serverChallengeQuestion - the server question. mandatory field, cannot be null

clientChallengeQuestion - the client question, null if not used

passwordHash - the hash value of password, null if not used. if used, length must be compliant with hash algorithm defined in Ocra settings.

session - the session data, null if not used. The SecureString session is expected to be created from a string using the "UTF-8" encoding (see SecureContainerFactory.fromString(java.lang.String) or its variants). This input must not be encoded by the caller in any way. Internally the session will be padded with leading null characters until it reaches the session byte length (e.g. session length of 5 and the string input of "info" results in 00696E666F).

Returns:

the OTP

Throws:

IllegalArgumentException - when the serverChallengeQuestion or the clientChallengeQuestion is longer than the value set by SoftOathSettings.setOcraMaximumChallengeQuestionLength(int) .

IllegalArgumentException - when the passwordHash is null but the value set by SoftOathSettings.setOcraPasswordHashAlgorithm(com.gemalto.idp.mobile.otp.oath.soft.SoftOathSettings.OcraPasswordHashAlgorithm) is not NONE or when the passwordHash length is not compliant with the value returned by SoftOathSettings.setOcraPasswordHashAlgorithm(com.gemalto.idp.mobile.otp.oath.soft.SoftOathSettings.OcraPasswordHashAlgorithm) .

IllegalArgumentException - when the session is not null but the value set by SoftOathSettings.setOcraSessionLength(int) is -1 or vice versa.

IllegalArgumentException - when the session's byte length is longer than the value set by SoftOathSettings.setOcraSessionLength(int) .

IllegalArgumentException - when the session cannot be decoded using UTF-8.

IllegalStateException - when the token's key length is not compatible with the OCRA hash algorithm set by SoftOathSettings.setOcraHashAlgorithm(com.gemalto.idp.mobile.otp.oath.soft.SoftOathSettings.OathHashAlgorithm) .

IllegalStateException - when the associated token has the OathToken.TokenCapability.DUAL_SEED capability and the OCRA suite is event based because only time based algorithms are supported for this capability.

IdpRuntimeException - when there is a cryptography operation failure.

IdpException - this is generic exception, you can directly catch this exception or catch each specific exception below.

IdpStorageException - when there is a database operation failure.

DeviceFingerprintException - when the token's fingerprint checksum does not match.

PasswordManagerException - when the TOKEN domain is not logged in (using one of the password managers).

IdpAuthException - when the TOKEN is not migrated

Since:

4.0

getOcraPasswordHash

SecureString getOcraPasswordHash(SecureString password)

Get password hash value according the algorithm defined by settings.

Parameters:

password - the password, can be null.

Returns:

• the hash value of the password.
• null if password is null or hash algorithm for Ocra password is set to SoftOathSettings.OcraPasswordHashAlgorithm.NONE by the device settings

getLastOtpLifespan

int getLastOtpLifespan()

Return lifespan of the last OTP computed by this device.

The following example illustrates the usage:

   // Create OATH settings (see OathFactory)
   MutableSoftOathSettings oathSettings = ...

   // Create a OATH device (see OathFactory)
   OathDevice device = ...

   // Compute a time-based OTP with device
   device.getTotp(pin);

   // Each time getLastOtpLifespan is called, it returns the
   // remaining lifespan in seconds of the last time-based OTP. Lifespan is
   // computed with respect of device's settings (in this example it returns
   // the lifespan according to Gemalto device fixed settings, i.e. 30-seconds timestep).
   int lifespan = device.getLastOtpLifespan();
 

Returns:

• In case last OTP computed with this device is time-based
  • If positive, the last OTP is still valid according to the current time and device's timestep settings. The returned value indicates the remaining seconds before the OTP becomes obsolete.
  • If negative, the last OTP computed is obsolete. The absolute value indicates the time elasped since the OTP has become obsolete.
• In case last OTP computed with this device is event-based, or no OTP has been computed yet, the function returns Integer.MAX_VALUE.

Since:

4.0