Package com.yubico.yubikit.oath

Class OathSession

java.lang.Object
com.yubico.yubikit.core.application.ApplicationSession<OathSession>
com.yubico.yubikit.oath.OathSession
All Implemented Interfaces:
java.io.Closeable, java.lang.AutoCloseable
public class OathSession
extends com.yubico.yubikit.core.application.ApplicationSession<OathSession>
Communicates with the OATH application on a YubiKey. Protocol specification. This application may optionally have an Access Key set, in which case most commands will be locked until unlock(char[]) has been invoked. Note that reset() can always be called, regardless of if an Access Key is set or not.

  • Field Summary

    Fields 
    Modifier and Type Field Description
    static com.yubico.yubikit.core.application.Feature<OathSession> FEATURE_RENAME
    Support for renaming a stored credential.
    static com.yubico.yubikit.core.application.Feature<OathSession> FEATURE_SHA512
    Support for credentials using the SHA-512 hash algorithm.
    static com.yubico.yubikit.core.application.Feature<OathSession> FEATURE_TOUCH
    Support for credentials that require touch to use.

  • Constructor Summary

    Constructors 
    Constructor Description
    OathSession​(com.yubico.yubikit.core.smartcard.SmartCardConnection connection)
    Establishes a new session with a YubiKeys OATH application.

  • Method Summary

    Modifier and Type Method Description
    Code calculateCode​(Credential credential)
    Returns a new Code for a stored Credential.
    Code calculateCode​(Credential credential, java.lang.Long timestamp)
    Returns a new Code for a stored Credential.
    java.util.Map<Credential,​Code> calculateCodes()
    Get a map of all Credentials stored on the YubiKey, together with a Code for each of them.
    java.util.Map<Credential,​Code> calculateCodes​(long timestamp)
    Get a map of all Credentials stored on the YubiKey, together with a Code for each of them.
    byte[] calculateResponse​(byte[] credentialId, byte[] challenge)
    Calculate a full (non-truncated) HMAC signature using a Credential.
    void close()  
    void deleteAccessKey()
    Removes the access key, if one is set.
    void deleteCredential​(byte[] credentialId)
    Deletes an existing Credential from the YubiKey.
    void deleteCredential​(Credential credential)
    Deletes an existing Credential from the YubiKey.
    byte[] deriveAccessKey​(char[] password)
    Derives an access key from a password and the device-specific salt.
    java.util.List<Credential> getCredentials()
    Get a list of all Credentials stored on the YubiKey.
    java.lang.String getDeviceId()
    Returns a unique ID which can be used to identify a particular YubiKey.
    com.yubico.yubikit.core.Version getVersion()  
    boolean hasAccessKey()
    Returns true if an Access Key is currently set.
    Credential putCredential​(CredentialData credentialData, boolean requireTouch)
    Adds a new Credential to the YubiKey.
    void renameCredential​(byte[] credentialId, byte[] newCredentialId)
    Change the issuer and name of a Credential already stored on the YubiKey.
    Credential renameCredential​(Credential credential, java.lang.String accountName, java.lang.String issuer)
    Change the issuer and name of a Credential already stored on the YubiKey.
    void reset()
    Resets the application, deleting all credentials and removing any lock code.
    void setAccessKey​(byte[] key)
    Sets an access key.
    void setPassword​(char[] password)
    Sets an Access Key derived from a password.
    boolean unlock​(char[] password)
    Unlocks other commands when an Access Key is set, using a password to derive the Access Key.
    boolean unlock​(AccessKey validator)
    Unlocks other commands when an Access Key is set.

    Methods inherited from class com.yubico.yubikit.core.application.ApplicationSession

    require, supports

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • FEATURE_TOUCH

      public static final com.yubico.yubikit.core.application.Feature<OathSession> FEATURE_TOUCH
      Support for credentials that require touch to use.

    • FEATURE_SHA512

      public static final com.yubico.yubikit.core.application.Feature<OathSession> FEATURE_SHA512
      Support for credentials using the SHA-512 hash algorithm.

    • FEATURE_RENAME

      public static final com.yubico.yubikit.core.application.Feature<OathSession> FEATURE_RENAME
      Support for renaming a stored credential.

  • Constructor Details

    • OathSession

      public OathSession​(com.yubico.yubikit.core.smartcard.SmartCardConnection connection) throws java.io.IOException, com.yubico.yubikit.core.application.ApplicationNotAvailableException
      Establishes a new session with a YubiKeys OATH application.
      Parameters:
      connection - to the YubiKey
      Throws:
      java.io.IOException - in case of connection error
      com.yubico.yubikit.core.application.ApplicationNotAvailableException - if the application is missing or disabled

  • Method Details

    • close

      public void close() throws java.io.IOException
      Throws:
      java.io.IOException

    • getVersion

      public com.yubico.yubikit.core.Version getVersion()
      Specified by:
      getVersion in class com.yubico.yubikit.core.application.ApplicationSession<OathSession>

    • getDeviceId

      public java.lang.String getDeviceId()
      Returns a unique ID which can be used to identify a particular YubiKey.

      This ID is randomly generated upon invocation of reset().

    • reset

      public void reset() throws java.io.IOException, com.yubico.yubikit.core.smartcard.ApduException
      Resets the application, deleting all credentials and removing any lock code.
      Throws:
      java.io.IOException - in case of connection error
      com.yubico.yubikit.core.smartcard.ApduException - in case of communication error

    • hasAccessKey

      public boolean hasAccessKey()
      Returns true if an Access Key is currently set.

    • unlock

      public boolean unlock​(char[] password) throws java.io.IOException, com.yubico.yubikit.core.smartcard.ApduException
      Unlocks other commands when an Access Key is set, using a password to derive the Access Key.

      Once unlocked, the application will remain unlocked for the duration of the session. See the YKOATH protocol specification for further details.

      Parameters:
      password - user-supplied password
      Returns:
      true if password valid
      Throws:
      java.io.IOException - in case of connection error
      com.yubico.yubikit.core.smartcard.ApduException - in case of communication error

    • unlock

      public boolean unlock​(AccessKey validator) throws java.io.IOException, com.yubico.yubikit.core.smartcard.ApduException
      Unlocks other commands when an Access Key is set.

      Once unlocked, the application will remain unlocked for the duration of the session. See the YKOATH protocol specification for further details.

      Parameters:
      validator - to provide a correct response to a challenge, using the Access Key.
      Returns:
      if the command was successful or not
      Throws:
      java.io.IOException - in case of connection error
      com.yubico.yubikit.core.smartcard.ApduException - in case of communication error

    • setPassword

      public void setPassword​(char[] password) throws java.io.IOException, com.yubico.yubikit.core.smartcard.ApduException
      Sets an Access Key derived from a password. Once a key is set, any usage of the credentials stored will require the application to be unlocked via one of the validate methods. Also see setAccessKey(byte[]).
      Parameters:
      password - user-supplied password to set, encoded as UTF-8 bytes
      Throws:
      java.io.IOException - in case of connection error
      com.yubico.yubikit.core.smartcard.ApduException - in case of communication error

    • setAccessKey

      public void setAccessKey​(byte[] key) throws java.io.IOException, com.yubico.yubikit.core.smartcard.ApduException
      Sets an access key. Once an access key is set, any usage of the credentials stored will require the application to be unlocked via one of the validate methods, which requires knowledge of the access key. Typically this key is derived from a password (see deriveAccessKey(char[])) and is set by instead using the setPassword(char[]) method. This method sets the raw 16 byte key.
      Parameters:
      key - the shared secret key used to unlock access to the application
      Throws:
      java.io.IOException - in case of connection error
      com.yubico.yubikit.core.smartcard.ApduException - in case of communication error

    • deleteAccessKey

      public void deleteAccessKey() throws java.io.IOException, com.yubico.yubikit.core.smartcard.ApduException
      Removes the access key, if one is set.
      Throws:
      java.io.IOException - in case of connection error
      com.yubico.yubikit.core.smartcard.ApduException - in case of communication error

    • getCredentials

      public java.util.List<Credential> getCredentials() throws java.io.IOException, com.yubico.yubikit.core.smartcard.ApduException
      Get a list of all Credentials stored on the YubiKey.
      Returns:
      list of credentials on device
      Throws:
      java.io.IOException - in case of connection error
      com.yubico.yubikit.core.smartcard.ApduException - in case of communication error

    • calculateCodes

      public java.util.Map<Credential,​Code> calculateCodes() throws java.io.IOException, com.yubico.yubikit.core.smartcard.ApduException, com.yubico.yubikit.core.application.BadResponseException
      Get a map of all Credentials stored on the YubiKey, together with a Code for each of them.

      Credentials which use HOTP, or which require touch, will not be calculated. They will still be present in the result, but with a null value. The current system time will be used for TOTP calculation.

      Returns:
      a Map mapping Credentials to Code
      Throws:
      java.io.IOException - in case of connection error
      com.yubico.yubikit.core.smartcard.ApduException - in case of communication error
      com.yubico.yubikit.core.application.BadResponseException - in case of incorrect YubiKey response

    • calculateCodes

      public java.util.Map<Credential,​Code> calculateCodes​(long timestamp) throws java.io.IOException, com.yubico.yubikit.core.smartcard.ApduException, com.yubico.yubikit.core.application.BadResponseException
      Get a map of all Credentials stored on the YubiKey, together with a Code for each of them.

      Credentials which use HOTP, or which require touch, will not be calculated. They will still be present in the result, but with a null value.

      Parameters:
      timestamp - the timestamp which is used as start point for TOTP
      Returns:
      a Map mapping Credentials to Code
      Throws:
      java.io.IOException - in case of connection error
      com.yubico.yubikit.core.smartcard.ApduException - in case of communication error
      com.yubico.yubikit.core.application.BadResponseException - in case of incorrect YubiKey response

    • calculateResponse

      public byte[] calculateResponse​(byte[] credentialId, byte[] challenge) throws java.io.IOException, com.yubico.yubikit.core.smartcard.ApduException, com.yubico.yubikit.core.application.BadResponseException
      Calculate a full (non-truncated) HMAC signature using a Credential.

      Using this command a Credential can be used as an HMAC key to calculate a result for an arbitrary challenge. The hash algorithm specified for the Credential is used.

      Parameters:
      credentialId - the ID of a stored Credential
      challenge - the input to the HMAC operation
      Returns:
      the calculated response
      Throws:
      java.io.IOException - in case of connection error
      com.yubico.yubikit.core.smartcard.ApduException - in case of communication error
      com.yubico.yubikit.core.application.BadResponseException - in case an unexpected response was sent from the YubiKey

    • calculateCode

      public Code calculateCode​(Credential credential) throws java.io.IOException, com.yubico.yubikit.core.smartcard.ApduException
      Returns a new Code for a stored Credential. The current system time will be used for TOTP calculation.
      Parameters:
      credential - credential that will get new code
      Returns:
      calculated code
      Throws:
      java.io.IOException - in case of connection error
      com.yubico.yubikit.core.smartcard.ApduException - in case of communication error

    • calculateCode

      public Code calculateCode​(Credential credential, @Nullable java.lang.Long timestamp) throws java.io.IOException, com.yubico.yubikit.core.smartcard.ApduException
      Returns a new Code for a stored Credential.
      Parameters:
      credential - credential that will get new code
      timestamp - the timestamp which is used as start point for TOTP, this is ignored for HOTP
      Returns:
      a new code
      Throws:
      java.io.IOException - in case of connection error
      com.yubico.yubikit.core.smartcard.ApduException - in case of communication error

    • putCredential

      public Credential putCredential​(CredentialData credentialData, boolean requireTouch) throws java.io.IOException, com.yubico.yubikit.core.smartcard.ApduException
      Adds a new Credential to the YubiKey.

      The Credential ID (see CredentialData.getId()) must be unique to the YubiKey, or the existing Credential with the same ID will be overwritten.

      Setting requireTouch requires support for FEATURE_TOUCH, available on YubiKey 4.2 or later. Using SHA-512 requires support for FEATURE_SHA512, available on YubiKey 4.3.1 or later.

      Parameters:
      credentialData - credential data to add
      requireTouch - true if the credential should require touch to be used
      Returns:
      the newly added Credential
      Throws:
      java.io.IOException - in case of connection error
      com.yubico.yubikit.core.smartcard.ApduException - in case of communication error

    • deleteCredential

      public void deleteCredential​(byte[] credentialId) throws java.io.IOException, com.yubico.yubikit.core.smartcard.ApduException
      Deletes an existing Credential from the YubiKey.
      Parameters:
      credentialId - the ID of the credential to remove
      Throws:
      java.io.IOException - in case of connection error
      com.yubico.yubikit.core.smartcard.ApduException - in case of communication error

    • deleteCredential

      public void deleteCredential​(Credential credential) throws java.io.IOException, com.yubico.yubikit.core.smartcard.ApduException
      Deletes an existing Credential from the YubiKey.
      Parameters:
      credential - the Credential to remove
      Throws:
      java.io.IOException - in case of connection error
      com.yubico.yubikit.core.smartcard.ApduException - in case of communication error

    • renameCredential

      public void renameCredential​(byte[] credentialId, byte[] newCredentialId) throws java.io.IOException, com.yubico.yubikit.core.smartcard.ApduException
      Change the issuer and name of a Credential already stored on the YubiKey.

      This functionality requires support for FEATURE_RENAME, available on YubiKey 5.3 or later.

      Parameters:
      credentialId - the ID of the credential to rename
      newCredentialId - the new ID to use
      Throws:
      java.io.IOException - in case of connection error
      com.yubico.yubikit.core.smartcard.ApduException - in case of communication error

    • renameCredential

      public Credential renameCredential​(Credential credential, java.lang.String accountName, @Nullable java.lang.String issuer) throws java.io.IOException, com.yubico.yubikit.core.smartcard.ApduException
      Change the issuer and name of a Credential already stored on the YubiKey.

      This functionality requires support for FEATURE_RENAME, available on YubiKey 5.3 or later.

      Parameters:
      credential - the Credential to rename
      accountName - the new name of the credential
      issuer - the new issuer of the credential
      Returns:
      the updated Credential
      Throws:
      java.io.IOException - in case of connection error
      com.yubico.yubikit.core.smartcard.ApduException - in case of communication error

    • deriveAccessKey

      public byte[] deriveAccessKey​(char[] password)
      Derives an access key from a password and the device-specific salt. The key is derived by running 1000 rounds of PBKDF2 using the password and salt as inputs, with a 16 byte output.
      Parameters:
      password - a user-supplied password, encoded as UTF-8 bytes.
      Returns:
      an access key for unlocking the session