com.gemalto.idp.mobile.otp.oath

Interface GemaltoOathDevice

public interface GemaltoOathDevice

An OATH device complying with the Standard Gemalto OATH options.

Since:

4.0

Method Summary

Modifier and Type	Method and Description
SecureString	getHotp(AuthInput authInput) Gets an event based OTP (HOTP) as defined by the Standard Gemalto OATH options.
int	getLastOtpLifespan() Return lifespan of the last OTP computed by this device.
SecureString	getOcraEventChallengeResponse(AuthInput authInput, SecureString challenge) Creates an event based OCRA C/R as defined by the Standard Gemalto OATH options.
SecureString	getOcraEventSignature(AuthInput authInput, java.util.List<SecureString> dataToSign) Creates an event based OCRA signature as defined by the Standard Gemalto OATH options.
SecureString	getOcraTimeChallengeResponse(AuthInput authInput, SecureString challenge) Creates a time based OCRA C/R as defined by the Standard Gemalto OATH options.
SecureString	getOcraTimeSignature(AuthInput authInput, java.util.List<SecureString> dataToSign) Creates a time based OCRA signature as defined by the Standard Gemalto OATH options.
SecureString	getTotp(AuthInput authInput) Gets a time based OTP (TOTP) as defined by the Standard Gemalto OATH options.

Method Detail

getHotp

SecureString getHotp(AuthInput authInput)
              throws IdpException

Gets an event based OTP (HOTP) as defined by the Standard Gemalto OATH options.

Parameters:

authInput - the AuthInput

Returns:

the OTP

Throws:

java.lang.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).

getTotp

SecureString getTotp(AuthInput authInput)
              throws IdpException

Gets a time based OTP (TOTP) as defined by the Standard Gemalto OATH options.

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

getOcraEventChallengeResponse

SecureString getOcraEventChallengeResponse(AuthInput authInput,
                                           SecureString challenge)
                                    throws IdpException

Creates an event based OCRA C/R as defined by the Standard Gemalto OATH options.

Parameters:

authInput - the AuthInput

challenge - the challenge. Must be numeric up to the maximum challenge length set in SoftOathSettings.setOcraMaximumChallengeQuestionLength(int) .

Returns:

the OTP

Throws:

java.lang.IllegalArgumentException - when the challenge length is out of

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

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

getOcraTimeChallengeResponse

SecureString getOcraTimeChallengeResponse(AuthInput authInput,
                                          SecureString challenge)
                                   throws IdpException

Creates a time based OCRA C/R as defined by the Standard Gemalto OATH options.

Parameters:

authInput - the AuthInput

challenge - the challenge. Must be numeric up to the maximum challenge length set in SoftOathSettings.setOcraMaximumChallengeQuestionLength(int) .

Returns:

the OTP

Throws:

java.lang.IllegalArgumentException - when the challenge length is out of range.

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

getOcraEventSignature

SecureString getOcraEventSignature(AuthInput authInput,
                                   java.util.List<SecureString> dataToSign)
                            throws IdpException

Creates an event based OCRA signature as defined by the Standard Gemalto OATH options.

Parameters:

authInput - the AuthInput

dataToSign - the list of data to be signed

Returns:

the signature

Throws:

java.lang.IllegalArgumentException - when dataToSign contains a '~' (0x7E) byte value.

java.lang.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).

getOcraTimeSignature

SecureString getOcraTimeSignature(AuthInput authInput,
                                  java.util.List<SecureString> dataToSign)
                           throws IdpException

Creates a time based OCRA signature as defined by the Standard Gemalto OATH options.

Parameters:

authInput - the AuthInput

dataToSign - the list of data to be signed

Returns:

the signature

Throws:

java.lang.IllegalArgumentException - when dataToSign contains a '~' (0x7E) byte value.

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)

getLastOtpLifespan

int getLastOtpLifespan()

Return lifespan of the last OTP computed by this device.

The following example illustrates the usage:

   // Create OATH settings (see OathFactory)
   SoftGemaltoOathSettings oathSettings = ...
 
   // Create a OATH device (see OathFactory)
   GemaltoOathDevice device = ...
 
   // Compute a time-based OTP with device
   device.getOcraTimeChallengeResponse(pin, challengeQuestion);
 
   // 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 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.