Package com.yubico.yubikit.oath

Class 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

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      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()
      Deprecated.
      Use isAccessKeySet() instead.
      boolean isAccessKeySet()
      Returns true if an Access Key is currently set.
      boolean isLocked()
      Returns true if the session is locked.
      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 Detail

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

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

      • 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

        @Deprecated
public boolean hasAccessKey()
        Deprecated.
        Use isAccessKeySet() instead.
        Returns true if an Access Key is currently set.

      • isAccessKeySet

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

      • isLocked

        public boolean isLocked()
        Returns true if the session is locked.

      • 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