EMOathDevice

Objective-C

@protocol EMOathDevice <NSObject>

Swift

protocol EMOathDevice : NSObjectProtocol

A protocol defining a device that generates OATH based OTPs.

Since

2.2

  • Gets an event based OTP (HOTP).

    Warning

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

    Since

    3.2

    Declaration

    Objective-C

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

    Swift

    func hotp(with authInput: (any EMAuthInput)!) throws -> any EMSecureString

    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. @exception NSInternalInconsistencyException When the associated token has the EMTokenCapabilityDUAL_SEED capability since only time based algorithms are supported for this capability. See EMTokenCapability

    Return Value

    The OTP.

  • Gets a time based OTP (TOTP).

    Warning

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

    Since

    3.2

    Declaration

    Objective-C

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

    Swift

    func totp(with authInput: (any EMAuthInput)!) throws -> any EMSecureString

    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.

  • Gets an OCRA OTP.

    @exception NSInvalidArgumentException When the serverChallengeQuestion or the clientChallengeQuestion is longer than the value returned by [EMSoftOathSettings ocraMaximumChallengeQuestionLength]. @exception 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]. @exception NSInvalidArgumentException When the session is not nil but the value returned by [EMSoftOathSettings ocraSessionLength] is -1 or vice versa. @exception NSInvalidArgumentException When the session’s byte length is longer than the value returned by [EMSoftOathSettings ocraSessionLength]. @exception NSInvalidArgumentException When the session cannot be decoded using UTF-8. @exception NSInvalidArgumentException When the token’s key length is not compatible with the OCRA hash algorithm (see [EMSoftOathSettings ocraHashAlgorithm]). @exception 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.

    Warning

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

    Since

    3.2

    Declaration

    Objective-C

    - (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;

    Swift

    func ocraOtp(with authInput: (any EMAuthInput)!, serverChallengeQuestion: (any EMSecureByteArray)!, clientChallengeQuestion: (any EMSecureByteArray)!, passwordHash: (any EMSecureByteArray)!, session: (any EMSecureByteArray)!) throws -> any EMSecureString

    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.

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

    • 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

    Declaration

    Objective-C

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

    Swift

    func ocraPasswordHash(_ password: (any EMSecureString)!) throws -> any EMSecureString

    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

  • Returns lifespan of the last OTP computed by this device.

    The following example illustrates the usage.

     // Create OATH settings
 id<EMMutableSoftOathSettings> oathSettings = ...

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

 // Create a OATH device
 id<EMOathDevice> 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];

    • 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’

    Since

    2.3

    Declaration

    Objective-C

    - (NSInteger)lastOtpLifespan;

    Swift

    func lastOtpLifespan() -> Int

    Return Value

    lifespan