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:

Closeable, 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 final com.yubico.yubikit.core.application.Feature<OathSession>	FEATURE_RENAME	Support for renaming a stored credential.
static final com.yubico.yubikit.core.application.Feature<OathSession>	FEATURE_SCP	Support for secure messaging.
static final com.yubico.yubikit.core.application.Feature<OathSession>	FEATURE_SHA512	Support for credentials using the SHA-512 hash algorithm.
static final 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.
OathSession(com.yubico.yubikit.core.smartcard.SmartCardConnection connection, @Nullable com.yubico.yubikit.core.smartcard.scp.ScpKeyParams scpKeyParams)	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, @Nullable Long timestamp)	Returns a new Code for a stored Credential.
Map<Credential,@Nullable Code>	calculateCodes()	Get a map of all Credentials stored on the YubiKey, together with a Code for each of them.
Map<Credential,@Nullable 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.
List<Credential>	getCredentials()	Get a list of all Credentials stored on the YubiKey.
String	getDeviceId()	Returns a unique ID which can be used to identify a particular YubiKey.
com.yubico.yubikit.core.Version	getVersion()
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, String accountName, @Nullable 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.

FEATURE_SCP

public static final com.yubico.yubikit.core.application.Feature<OathSession> FEATURE_SCP

Support for secure messaging.

Constructor Details

OathSession

public OathSession(com.yubico.yubikit.core.smartcard.SmartCardConnection connection)
            throws IOException,
com.yubico.yubikit.core.application.ApplicationNotAvailableException

Establishes a new session with a YubiKeys OATH application.

Parameters:

connection - to the YubiKey

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.application.ApplicationNotAvailableException - if the application is missing or disabled

OathSession

public OathSession(com.yubico.yubikit.core.smartcard.SmartCardConnection connection,
 @Nullable com.yubico.yubikit.core.smartcard.scp.ScpKeyParams scpKeyParams)
            throws IOException,
com.yubico.yubikit.core.application.ApplicationNotAvailableException

Establishes a new session with a YubiKeys OATH application.

Parameters:

connection - to the YubiKey

scpKeyParams - SCP key parameters to establish a secure connection

Throws:

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 IOException

Throws:

IOException

getVersion

public com.yubico.yubikit.core.Version getVersion()

Specified by:

getVersion in class com.yubico.yubikit.core.application.ApplicationSession<OathSession>

getDeviceId

public 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 IOException,
com.yubico.yubikit.core.smartcard.ApduException

Resets the application, deleting all credentials and removing any lock code.

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of communication error

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 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:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of communication error

unlock

public boolean unlock(AccessKey validator)
               throws 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:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of communication error

setPassword

public void setPassword(char[] password)
                 throws 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:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of communication error

setAccessKey

public void setAccessKey(byte[] key)
                  throws 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:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of communication error

deleteAccessKey

public void deleteAccessKey()
                     throws IOException,
com.yubico.yubikit.core.smartcard.ApduException

Removes the access key, if one is set.

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of communication error

getCredentials

public List<Credential> getCredentials()
                                throws IOException,
com.yubico.yubikit.core.smartcard.ApduException

Get a list of all Credentials stored on the YubiKey.

Returns:

list of credentials on device

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of communication error

calculateCodes

public Map<Credential,@Nullable Code> calculateCodes()
                                              throws 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:

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 Map<Credential,@Nullable Code> calculateCodes(long timestamp)
                                              throws 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:

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 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:

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 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:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of communication error

calculateCode

public Code calculateCode(Credential credential,
 @Nullable Long timestamp)
                   throws 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:

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 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:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of communication error

deleteCredential

public void deleteCredential(byte[] credentialId)
                      throws IOException,
com.yubico.yubikit.core.smartcard.ApduException

Deletes an existing Credential from the YubiKey.

Parameters:

credentialId - the ID of the credential to remove

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of communication error

deleteCredential

public void deleteCredential(Credential credential)
                      throws IOException,
com.yubico.yubikit.core.smartcard.ApduException

Deletes an existing Credential from the YubiKey.

Parameters:

credential - the Credential to remove

Throws:

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 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:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of communication error

renameCredential

public Credential renameCredential(Credential credential,
 String accountName,
 @Nullable String issuer)
                            throws 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:

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