EMOathDevice Protocol Reference

Conforms to NSObject
Declared in EMOathDevice.h

Overview

A protocol defining a device that generates OATH based OTPs.

– hotpWithAuthInput:error: required method

Gets an event based OTP (HOTP).

- (id<EMSecureString>)hotpWithAuthInput:(id<EMAuthInput>)authInput error:(NSError **)error

Parameters

authInput

The authInput.
error

If an error occurs, upon return contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.

Return Value

The OTP.

Availability

3.2

Discussion

Warning: Depending of the EMAuthInput type you are using, you may have to use this function asynchronously, please @see EMAuthInput for more details

Exceptions

NSInternalInconsistencyException

When the associated token has the EMTokenCapabilityDUAL_SEED capability since only time based algorithms are supported for this capability. See EMTokenCapability

Declared In

EMOathDevice.h

– totpWithAuthInput:error: required method

Gets a time based OTP (TOTP).

- (id<EMSecureString>)totpWithAuthInput:(id<EMAuthInput>)authInput error:(NSError **)error

Parameters

authInput

The authInput.
error

If an error occurs, upon return contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.

Return Value

The OTP.

Availability

3.2

Discussion

Warning: Depending of the EMAuthInput type you are using, you may have to use this function asynchronously, please @see EMAuthInput for more details

Declared In

EMOathDevice.h

– ocraOtpWithAuthInput:serverChallengeQuestion:clientChallengeQuestion:passwordHash:session:error: required method

Gets an OCRA OTP.

- (id<EMSecureString>)ocraOtpWithAuthInput:(id<EMAuthInput>)authInput serverChallengeQuestion:(id<EMSecureByteArray>)serverChallengeQuestion clientChallengeQuestion:(id<EMSecureByteArray>)clientChallengeQuestion passwordHash:(id<EMSecureByteArray>)passwordHash session:(id<EMSecureByteArray>)session error:(NSError **)error

Parameters

authInput

The authInput.
serverChallengeQuestion

The server question. mandatory field, cannot be nil.
clientChallengeQuestion

The client question, nil if not used.
passwordHash

The hash value of password, nil if not used. If used, length must be compliant with hash algorithm defined in OCRA device settings.
session

The session data, nil if not used.
error

If an error occurs, upon return contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.

Return Value

The OTP.

Availability

3.2

Discussion

Warning: Depending of the EMAuthInput type you are using, you may have to use this function asynchronously, please @see EMAuthInput for more details

Exceptions

NSInvalidArgumentException

When the serverChallengeQuestion or the clientChallengeQuestion is longer than the value returned by [EMSoftOathSettings ocraMaximumChallengeQuestionLength].
NSInvalidArgumentException

When the passwordHash is nil but the value returned by [EMSoftOathSettings ocraPasswordHashAlgorithm] is not NONE or when the passwordHash length is not compliant with the value returned by [EMSoftOathSettings ocraPasswordHashAlgorithm].
NSInvalidArgumentException

When the session is not nil but the value returned by [EMSoftOathSettings ocraSessionLength] is -1 or vice versa.
NSInvalidArgumentException

When the session’s byte length is longer than the value returned by [EMSoftOathSettings ocraSessionLength].
NSInvalidArgumentException

When the session cannot be decoded using UTF-8.
NSInvalidArgumentException

When the token’s key length is not compatible with the OCRA hash algorithm (see [EMSoftOathSettings ocraHashAlgorithm]).
NSInternalInconsistencyException

When the associated token has the EMTokenCapabilityDUAL_SEED capability and the OCRA suite is event based since only time based algorithms are supported for this capability. See EMTokenCapability.

Declared In

EMOathDevice.h

– ocraPasswordHash:error: required method

Gets password hash value according the algorithm defined by device settings.

- (id<EMSecureString>)ocraPasswordHash:(id<EMSecureString>)password error:(NSError **)error

Parameters

password

The password, can be nil.
error

If an error occurs, upon return contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.

Return Value

passwordHash

  • The hash value of the password.
  • 'nil' if password is 'nil' or hash algorithm for OCRA password is set to 'EMOcraPasswordNone' by the device settings

Declared In

EMOathDevice.h

– lastOtpLifespan required method

Returns lifespan of the last OTP computed by this device.

- (NSInteger)lastOtpLifespan

Return Value

lifespan

  • 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 elapsed 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 'NSIntegerMax'

Availability

2.3

Discussion

The following example illustrates the usage.

// Create OATH settings id oathSettings = …

// Set up OATH time-based settings (for example a 30 seconds timestep) [oathSettings setTotpTimestepSize:30];

// Create a OATH device id device = …

// Compute a time-based OTP with device (with pin EMSecureString) [device getTotpWithPin:pin];

// Each time selector [… lastOtpLifespan] 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 the 30-seconds timestep). NSInteger lifespan = [device lastOtpLifespan];

Declared In

EMOathDevice.h