OATH

An application uses this service to create OTPs based on the Open AutTHentication algorithms from RFC 4226 (HOTP RFC, 6238 TOTP RFC and 6287 OCRA RFC). An OATH Token contains the secret key and state while an OATH device generates OTPs using a token. The OATH modes and their basic usage are provided as follows:

  • HOTP – Produces an OTP from a shared secret and counter. This is commonly used for simple login OTPs. This services extends the RFC by supporting HMAC-SHA-256.
Note

Ezio Mobile SDK also supports the unofficial HOTP with SHA-256 digest algorithm.

  • TOTP – Produces an OTP from a shared secret and time. This is commonly used for simple login OTPs (for example, Facebook or Google’s 2FA).
  • OCRA – OATH Challenge-Response Algorithm. This is commonly used for complex OTPs such as challenge/response or transaction signing.
Note

Since TOTP is a time-based passcode, it is sometimes possible for the server and client to drift (by having their clocks de-synchronized). This can lead to errors during the generation of OTPs, especially if the drift is significant. If the mobile device is set to automatically synchronize with a time server (which is usually the case), this time drift is not an issue since the device is not allowed to drift much. However, if the mobile device is not automatically synchronized with a time server then this may lead to an invalid generation of TOTP (for example, a user may have manually set his device time and let it drift away or set the device to a completely incorrect time).

OATH vs Gemalto OATH

The OATH specifications, in particular OCRA, are open-ended regarding their configuration and intended use cases. This allows many possible configurations and use cases but it also makes it harder to understand and implement. Gemalto helps to alleviate this problem by providing the standard OATH implementation and a Gemalto OATH specification that simplifies the configuration and specific use cases of OATH.

Unconfigurable OATH values

These are the OATH values which are not configurable:

  • The OATH counter for a new OATH token always starts from 0.
  • The T0 value is always 0.

OATH tokens and token management

OATH has its own token and Token Manager types to enable static type of checking for OATH-specific operations, adding APIs for additional features, and specifying limitations. Refer to the following sections for the details.

Getting OATH token manager

An application retrieves an instance of OathTokenManager from OathService. This token manager only operates on OATH tokens and cannot be used to access any other token type.

// create OATH service 
OathService oathService = OathService.create(otpModule);

// Retrieve the token manager 
OathTokenManager oathTokenManager = oathService.getTokenManager();

Creating token

The token is created by a service-specific component TokenManager. The following example shows the usage of TokenManager with OATH service.

PROVISIONING_PROTOCOL_V1 through PROVISIONING_PROTOCOL_V3

// Configure the device fingerprint to use service and soft data
// along with some custom data provided by the application as fingerprint data 
DeviceFingerprintSource fingerprintSource =
         new DeviceFingerprintSource(customData, Type.SERVICE, Type.SOFT);
// Set the policy to generate an error when fingerprint is incorrect 
DeviceFingerprintTokenPolicy fingerprintTokenPolicy =
         new DeviceFingerprintTokenPolicy(true, fingerprintSource);

// Sample token creation using CAP token  
OathTokenManager oathTokenManager = capService.getTokenManager();
try {
     OathToken token = oathTokenManager.createToken(tokenName, 
                          provisioningConfig, 
                          fingerprintTokenPolicy); 
} catch (PasswordManagerException e) {  
		// Need to login first, handle error 
} catch (IdpException e) { 
	// handle error 
}

Note

If MobileProvisioningProtocol.PROVISIONING_PROTOCOL_V5 is used, a Runtime exception is raised.

PROVISIONING_PROTOCOL_V1 through PROVISIONING_PROTOCOL_V5

// Configure the device fingerprint to use service and soft data
// along with some custom data provided by the application as fingerprint data 
DeviceFingerprintSource fingerprintSource =
         new DeviceFingerprintSource(customData, Type.SERVICE, Type.SOFT);
// Set the policy to generate an error when fingerprint is incorrect 
DeviceFingerprintTokenPolicy fingerprintTokenPolicy =
         new DeviceFingerprintTokenPolicy(true, fingerprintSource);

// Starting Ezio SDK 5.0, provisioning with PROVISIONING_PROTOCOL_V5 on EPS3.x
// requires new API on EpsConfigurationBuilder
// Please refer to chapter EPS Configuration Builder
// PROVISIONING_PROTOCOL_V5 allows extensions to provides for additional information
// set by the server, if any. 
// This optional token information is returned in the 
// token creation callback as follows:

// Sample token creation with New API using Oath token  
OathTokenManager oathTokenManager = oathService.getTokenManager();
OathTokenManager.createToken(tokenName, 
              provisioningConfig, 
              fingerprintTokenPolicy, 
              new TokenManager.TokenCreationCallback() {
	@Override
	public void onSuccess(Token token, Map<String, String> tokenExtensions) {
		// Do some logic with token
	}

	@Override
	public void onError(IdpException e) {
		// Do some logic with error handling
	}
});
Note

The provisioning process is not thread-safe as the SDK does not support concurrent provisioning, and this may lead to database error. To provision more than one token, ensure that the provisioning invocations are performed in sequential order.

The token name is unique. Before calling ‘createToken’, check that the name of the token to be created does not exist.

Getting OATH tokens

Using the OATH Token Manager, an application retrieves an OATH token using its name and optionally its custom fingerprint data. Refer to Device Fingerprint for more information.

//get the token with the specified name
OathToken token1 = oathTokenManager.getToken(name);

//get the token with the specified name and custom fingerprint data
OathToken token2 = oathTokenManager.getToken(name, customData);

Removing token

Use the respective TokenManager to remove a token. Removing the token also removes all of the token’s persistent data.

// remove a token 
// If a token identified by the name is not of the same type as the token manager 
//    the token is not removed and returns false.  
oathTokenManager.removeToken(name);

Creating and using multi-seed OATH tokens

By default, tokens are used to generate OTPs from a single shared secret key. However, it is possible to create a token that generates OTPs from one of two selectable keys. OTPs are sent to an authentication server to authenticate the user’s action. The key to use is selected by an application from the token’s instance and the key to use is defined by the application (for example, use key 0 for low risk operations such as logins and key 1 for high risk operations such as signing transactions).

Note

The OATH service does not impose any restrictions on the usage of the keys.

Do not use this capability on arbitrary provisioning requests. When creating a token with this capability, the provisioning response must be associated with a dual seed enrollment request.

This capability limits the provisioning response to the following settings:

Field Limitation Reason
Token Type OATH only Due to technical constraints, only OATH tokens are supported.
Provisioning Protocol v3 only The first version supporting OATH.
Key Size 32 bytes only Dual seed tokens by design have two keys per provisioning response and provisioning protocol v3 supports a maximum size of 64 bytes for all keys. Therefore, individual key sizes are 32 bytes or smaller. Note: 20-byte keys are currently not supported.

This capability limits the usage of the token in the following ways:

Limitation Reason
No event based algorithms Due to the technical constraints, Ezio Mobile SDK only supports one counter per token but dual seed tokens require two counters per token (one for each key). Therefore no event based algorithms are permitted.
Single PIN A single PIN is used to protect the two keys and a PIN change operation applies to both keys.

The following example shows how to create a multi-seed OATH token and how to select a key to be used for generating an OTP.

// Specify TokenCapability to be DUAL_SEED, also make sure that corresponding   
// DUAL_SEED token was actually enrolled through EPS  
oathTokenManager.createToken(name, epsConfiguration, TokenCapability.DUAL_SEED); 

DualSeedSoftOathToken token = (DualSeedSoftOathToken)oathTokenManager.getToken(name);  
// Required step before using 'token': select a key (e.g. the second key)  
token.selectKey(1);

Limitations of OATH tokens

These are the limitations of the OATH tokens:

  • Mobile Provisioning Protocol (MPP) versions 1 and 2 are not supported. These versions of the protocol do not support the OATH token type.

  • Token key length must be greater than or equal to the hash algorithm when creating an OATH device. An exception is thrown when the key length fails to comply with the following algorithms:

    Key Length Accepted Hash Algorithm(s)
    20 HMAC-SHA1
    32 HMAC-SHA1, HMAC-SHA256
    64 HMAC-SHA1, HMAC-SHA256, HMAC-SHA512