com.yubico.yubikit.oath

Class OathApplication

java.lang.Object

Iso7816Application

com.yubico.yubikit.oath.OathApplication

public class OathApplication
extends Iso7816Application

Communicates with a YubiKey's OATH application. https://developers.yubico.com/OATH/YKOATH_Protocol.html

Field Summary

Fields

Modifier and Type	Field and Description
static short	APPLICATION_NOT_FOUND_ERROR
static short	AUTHENTICATION_REQUIRED_ERROR
static short	GENERIC_ERROR
static short	NO_SUCH_OBJECT
static short	WRONG_SYNTAX

Constructor Summary

Constructors

Constructor and Description
OathApplication(YubiKeySession session) Create new instance of OathApplication and selects the application for use

Method Summary

Modifier and Type	Method and Description
byte[]	calculate(byte[] credentialId, byte[] challenge) Perform a raw non-truncated CALCULATE (HMAC) for a credential using the given challenge.
Code	calculate(Credential credential) Performs CALCULATE for one named credential.
Code	calculate(Credential credential, java.lang.Long timestamp) Performs CALCULATE for one named credential.
java.util.Map<Credential,Code>	calculateAll() Performs CALCULATE for all available credentials,
java.util.Map<Credential,Code>	calculateAll(long timestamp) Performs CALCULATE for all available credentials,
static byte[]	calculateSecret(java.lang.String password, byte[] salt) Passes a user-supplied UTF-8 encoded password through 1000 rounds of PBKDF2 with the device ID from select used as salt.
void	deleteCredential(byte[] credentialId) Deletes an existing credential.
OathApplicationInfo	getApplicationInfo()
java.util.List<Credential>	listCredentials() Lists configured credentials.
Credential	putCredential(CredentialData credential) Adds a new (or overwrites) OATH credential.
void	reset() Resets the application, deleting all credentials and removing any lock code.
byte[]	sendAndReceive(Apdu command) Uses ApduUtils.sendAndReceive method with specific ins byte for "send remaining data" command
void	setPassword(java.lang.String password) Configures Authentication.
void	setSecret(byte[] secret) Configures Authentication.
void	unsetSecret() Removes authentication.
boolean	validate(ChallengeSigner signer) Validates authentication (mutually).
boolean	validate(java.lang.String password) Validates authentication (mutually).

Methods inherited from class java.lang.Object

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

Field Detail

AUTHENTICATION_REQUIRED_ERROR

public static final short AUTHENTICATION_REQUIRED_ERROR

See Also:

Constant Field Values

WRONG_SYNTAX

public static final short WRONG_SYNTAX

See Also:

Constant Field Values

GENERIC_ERROR

public static final short GENERIC_ERROR

See Also:

Constant Field Values

NO_SUCH_OBJECT

public static final short NO_SUCH_OBJECT

See Also:

Constant Field Values

APPLICATION_NOT_FOUND_ERROR

public static final short APPLICATION_NOT_FOUND_ERROR

See Also:

Constant Field Values

Constructor Detail

OathApplication

public OathApplication(YubiKeySession session)
                throws java.io.IOException,
                       ApduException,
                       ApplicationNotFound

Create new instance of OathApplication and selects the application for use

Parameters:

session - session with YubiKey

Throws:

java.io.IOException - in case of connection error

ApduException - in case of communication error

ApplicationNotFound

Method Detail

getApplicationInfo

public OathApplicationInfo getApplicationInfo()

Returns:

version, ID and a challenge if authentication is configured

reset

public void reset()
           throws java.io.IOException,
                  ApduException

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

Throws:

java.io.IOException - in case of connection error

ApduException - in case of communication error

validate

public boolean validate(java.lang.String password)
                 throws java.io.IOException,
                        ApduException

Validates authentication (mutually). The challenge for this comes from the SELECT command. The response if computed by performing the correct HMAC function of that challenge with the correct key. A new challenge is then sent to the application, together with the response. The application will then respond with a similar calculation that the host software can verify.

Parameters:

password - user-supplied password

Returns:

true if password valid

Throws:

java.io.IOException - in case of connection error

ApduException - in case of communication error

validate

public boolean validate(ChallengeSigner signer)
                 throws java.io.IOException,
                        ApduException

Validates authentication (mutually). The challenge for this comes from the SELECT command. The response if computed by performing the correct HMAC function of that challenge with the correct key. A new challenge is then sent to the application, together with the response. The application will then respond with a similar calculation that the host software can verify.

Parameters:

signer - the provide of HMAC calculation

Throws:

java.io.IOException - in case of connection error

ApduException - in case of communication error

setPassword

public void setPassword(java.lang.String password)
                 throws java.io.IOException,
                        ApduException

Configures Authentication.

Parameters:

password - user-supplied password. If null or empty, authentication is removed.

Throws:

java.io.IOException - in case of connection error

ApduException - in case of communication error

setSecret

public void setSecret(byte[] secret)
               throws java.io.IOException,
                      ApduException,
                      BadRequestException

Configures Authentication. The key to be set is expected to be a user-supplied UTF-8 encoded password passed through 1000 rounds of PBKDF2 with the ID from select used as salt. 16 bytes of that are used. When configuring authentication you are required to send an 8 byte challenge and one authentication-response with that key, in order to confirm that the application and the host software can calculate the same response for that key.

Parameters:

secret - 16 bytes of user-supplied UTF-8 encoded password passed through 1000 rounds of PBKDF2 with the ID from select used as salt

Throws:

java.io.IOException - in case of connection error

ApduException - in case of communication error

BadRequestException

unsetSecret

public void unsetSecret()
                 throws java.io.IOException,
                        ApduException

Removes authentication. If the application is protected with a password, this password is removed.

Throws:

java.io.IOException

ApduException

listCredentials

public java.util.List<Credential> listCredentials()
                                           throws java.io.IOException,
                                                  ApduException

Lists configured credentials.

Returns:

list of credentials on device

Throws:

java.io.IOException - in case of connection error

ApduException - in case of communication error

calculateAll

public java.util.Map<Credential,Code> calculateAll()
                                            throws java.io.IOException,
                                                   ApduException

Performs CALCULATE for all available credentials,

Returns:

returns credential + response for TOTP and just credential with null code for HOTP and credentials requiring touch.

Throws:

java.io.IOException - in case of connection error

ApduException - in case of communication error

calculateAll

public java.util.Map<Credential,Code> calculateAll(long timestamp)
                                            throws java.io.IOException,
                                                   ApduException

Performs CALCULATE for all available credentials,

Parameters:

timestamp - the timestamp which is used as start point for TOTP

Returns:

returns credential + response for TOTP and just credential for HOTP and credentials requiring touch.

Throws:

java.io.IOException - in case of connection error

ApduException - in case of communication error

calculate

public byte[] calculate(byte[] credentialId,
                        byte[] challenge)
                 throws java.io.IOException,
                        ApduException

Perform a raw non-truncated CALCULATE (HMAC) for a credential using the given challenge.

Parameters:

credentialId - credential ID to identify the credential

challenge - challenge bytes

Returns:

calculated HMAC response

Throws:

java.io.IOException - in case of connection error

ApduException - in case of communication error

calculate

public Code calculate(Credential credential)
               throws java.io.IOException,
                      ApduException

Performs CALCULATE for one named credential.

Parameters:

credential - credential that will get new code

Returns:

calculated code

Throws:

java.io.IOException - in case of connection error

ApduException - in case of communication error

calculate

public Code calculate(Credential credential,
                      java.lang.Long timestamp)
               throws java.io.IOException,
                      ApduException

Performs CALCULATE for one named credential.

Parameters:

credential - credential that will get new code

timestamp - the timestamp which is used as start point for TOTP, can be null for HOTP

Returns:

calculated code

Throws:

java.io.IOException - in case of connection error

ApduException - in case of communication error

putCredential

public Credential putCredential(CredentialData credential)
                         throws java.io.IOException,
                                ApduException,
                                NotSupportedOperation

Adds a new (or overwrites) OATH credential.

Parameters:

credential - credential data to add

Throws:

java.io.IOException - in case of connection error

ApduException - in case of communication error

NotSupportedOperation

deleteCredential

public void deleteCredential(byte[] credentialId)
                      throws java.io.IOException,
                             ApduException

Deletes an existing credential.

Parameters:

credentialId - ID of credential data to remove

Throws:

java.io.IOException - in case of connection error

ApduException - in case of communication error

calculateSecret

public static byte[] calculateSecret(java.lang.String password,
                                     byte[] salt)
                              throws java.security.NoSuchAlgorithmException,
                                     java.security.spec.InvalidKeySpecException

Passes a user-supplied UTF-8 encoded password through 1000 rounds of PBKDF2 with the device ID from select used as salt. 16 bytes of that are used.

Parameters:

password - a user-supplied password

salt - the salt value (the deviceId returned by select command)

Returns:

a secret/key for authentication

Throws:

java.security.spec.InvalidKeySpecException - in case of crypto operation error

java.security.NoSuchAlgorithmException - in case of crypto operation error

sendAndReceive

public byte[] sendAndReceive(Apdu command)
                      throws java.io.IOException,
                             ApduException

Uses ApduUtils.sendAndReceive method with specific ins byte for "send remaining data" command

Parameters:

command - apdu command that will be sent

Returns:

data that received from command execution

Throws:

java.io.IOException - in case of connection error

ApduException - in case of communication error