org.unitedid.yhsm

Class YubiHSM

java.lang.Object

org.unitedid.yhsm.YubiHSM

public class YubiHSM
extends Object

YubiHSM the main class to use for YubiHSM commands

Field Summary

Fields

Modifier and Type	Field and Description
static int	minHashLength The hash length used when generating or validating an AEAD, default length is 20

Constructor Summary

Constructors

Constructor and Description
YubiHSM() Constructor that opens /dev/ttyACM0
YubiHSM(String device) Constructor
YubiHSM(String device, float timeout) Constructor

Method Summary

Methods

Modifier and Type	Method and Description
boolean	compareAES_ECB(int keyHandle, String cipherText, String plaintext) AES ECB decrypt a cipher text using a specific key handle, and then compare it with the supplied plaintext.
Map<String,Integer>	decodeYubikeyOtp(String publicId, int keyHandle, String aead, String otp) Decrypt a YubiKey OTP using an AEAD.
String	decryptAES_ECB(String cipherText, int keyHandle) AES ECB decrypt a cipher text using a specific key handle.
boolean	drainData() Drain all remaining output from the YubiHSM, used for debugging.
String	echo(String str) Test the YubiHSM by sending a string that the YubiHSM will echo back.
String	encryptAES_ECB(String plaintext, int keyHandle) AES ECB encrypt a plaintext string using a specific key handle.
void	exitMonitorDebugMode() Tell the YubiHSM to exit to configuration mode (requires 'debug' mode enabled).
Map<String,String>	generateAEAD(String nonce, int keyHandle, byte[] data) Generate AEAD block from the data for a specific key handle and nonce.
Map<String,String>	generateAEAD(String nonce, int keyHandle, String data) Generate AEAD block from the data for a specific key handle and nonce.
Map<String,String>	generateBufferAEAD(String nonce, int keyHandle) Generate AEAD block of data buffer for a specific key.
byte[]	generateHMACSHA1(byte[] bytes, int keyHandle, boolean toBuffer) Generate HMAC SHA1 using a key handle in the YubiHSM.
Map<String,String>	generateHMACSHA1(byte[] data, int keyHandle, boolean last, boolean toBuffer) Generate HMAC SHA1 using a key handle in the YubiHSM.
Map<String,String>	generateHMACSHA1(byte[] data, int keyHandle, byte flags, boolean last, boolean toBuffer) Generate HMAC SHA1 using a key handle in the YubiHSM.
Map<String,String>	generateHMACSHA1(String data, int keyHandle, boolean last, boolean toBuffer) Generate HMAC SHA1 using a key handle in the YubiHSM.
Map<String,String>	generateHMACSHA1(String data, int keyHandle, byte flags, boolean last, boolean toBuffer) Generate HMAC SHA1 using a key handle in the YubiHSM.
Map<String,String>	generateHMACSHA1Next(byte[] data, int keyHandle, boolean last, boolean toBuffer) Add more input to the HMAC SHA1, used after calling generateHMACSHA1(byte[], int, boolean) with last set to false.
Map<String,String>	generateHMACSHA1Next(String data, int keyHandle, boolean last, boolean toBuffer) Add more input to the HMAC SHA1, used after calling generateHMACSHA1(byte[], int, boolean) with last set to false.
String	generateOathAEAD(String nonce, int keyHandle, String tokenSeed) Generate AEAD block which can be used for OATH OTP validation, see validateOathHOTP and validateOathTOTP.
Map<String,String>	generateRandomAEAD(String nonce, int keyHandle, int length) Generate a random AEAD block using the YubiHSM internal TRNG.
SystemInfoCmd	getInfo() Get the firmware version and unique ID from the YubiHSM.
int	getMinHashLength() Get the minimum hash length used when generating or validating an AEAD.
Nonce	getNonce(short increment) Get a nonce from the YubiHSM.
byte[]	getRandom(int bytes) Tell the YubiHSM to generate a number of random bytes.
DeviceHandler	getRawDevice() Get the raw device, used for debugging.
boolean	keyStorageUnlock(String password) Unlock the YubiHSM key storage using the HSM password.
boolean	keyStoreDecrypt(String key) Decrypt the YubiHSM key storage using the Master key.
int	loadBufferData(byte[] data, int offset) Load data into the YubiHSMs internal buffer.
int	loadBufferData(String data, int offset) Load data into the YubiHSMs internal buffer.
int	loadRandomBufferData(int length, int offset) Load random data into the YubiHSMs internal buffer.
boolean	loadTemporaryKey(String nonce, int keyHandle, String aead) Load the content of an AEAD into the phantom key handle 0xffffffff.
boolean	randomReseed(String seed) Provide YubiHSM DRBG_CTR with a new seed.
void	setMinHashLength(int value) Set the minimum hash length generating or validating an AEAD.
boolean	unlock(String password) Generic key store unlock method that calls the appropriate unlock function for this YubiHSM.
boolean	unlockOtp(String publicId, String otp) Have the YubiHSM unlock the HSM operations (those involving the keystore) with a YubiKey OTP.
boolean	validateAEAD(String nonce, int keyHandle, String aead, byte[] plaintext) Validate an AEAD using the YubiHSM, matching it against some known plain text.
boolean	validateAEAD(String nonce, int keyHandle, String aead, String plaintext) Validate an AEAD using the YubiHSM, matching it against some known plain text.
int	validateOathHOTP(int keyHandle, String nonce, String aead, int counter, String otp, int lookAhead) Validate OATH-HOTP by a token whose seed is available to the YubiHSM through an AEAD.
boolean	validateOathTOTP(int keyHandle, String nonce, String aead, String otp) Validate OATH-TOTP by a token whose seed is available to the YubiHSM through an AEAD.
boolean	validateOathTOTP(int keyHandle, String nonce, String aead, String otp, int period, int drift, int backwardDrift, int forwardDrift) Validate OATH-TOTP by a token whose seed is available to the YubiHSM through an AEAD.

Methods inherited from class java.lang.Object

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

Field Detail

minHashLength

public static int minHashLength

The hash length used when generating or validating an AEAD, default length is 20

Constructor Detail

YubiHSM

public YubiHSM(String device,
       float timeout)
        throws YubiHSMErrorException

Constructor

Parameters:

device - the YubiHSM device name ie /dev/ttyACM0

timeout - the command read timeout (default is 0.5 sec)

Throws:

YubiHSMErrorException - if the YubiHSM reset command fail

YubiHSM

public YubiHSM(String device)
        throws YubiHSMErrorException

Constructor

Parameters:

device - the YubiHSM device name ie /dev/ttyACM0

Throws:

YubiHSMErrorException - if the YubiHSM reset command fail

YubiHSM

public YubiHSM()
        throws YubiHSMErrorException

Constructor that opens /dev/ttyACM0

Throws:

YubiHSMErrorException - if the YubiHSM reset command fail

Method Detail

echo

public String echo(String str)
            throws YubiHSMErrorException

Test the YubiHSM by sending a string that the YubiHSM will echo back.

Parameters:

str - the string that the YubiHSM should return

Returns:

the the same string sent to the YubiHSM

Throws:

YubiHSMErrorException - if the YubiHSM echo command fail

getInfo

public SystemInfoCmd getInfo()

Get the firmware version and unique ID from the YubiHSM.

Returns:

a SystemInfoCmd class with version, protocol and unique ID

generateAEAD

public Map<String,String> generateAEAD(String nonce,
                              int keyHandle,
                              byte[] data)
                                throws YubiHSMCommandFailedException,
                                       YubiHSMErrorException,
                                       YubiHSMInputException

Generate AEAD block from the data for a specific key handle and nonce.

Parameters:

nonce - the nonce

keyHandle - the key to use

data - is the data to turn into an AEAD

Returns:

a hash map with the AEAD and nonce

Throws:

YubiHSMCommandFailedException - if the YubiHSM fail to execute the command

YubiHSMErrorException - if validation fail for some values returned by the YubiHSM

YubiHSMInputException - if an argument does not validate

generateAEAD

public Map<String,String> generateAEAD(String nonce,
                              int keyHandle,
                              String data)
                                throws YubiHSMCommandFailedException,
                                       YubiHSMErrorException,
                                       YubiHSMInputException

Generate AEAD block from the data for a specific key handle and nonce.

Parameters:

nonce - the nonce

keyHandle - the key to use

data - is the data to turn into an AEAD

Returns:

a hash map with the AEAD and nonce

Throws:

YubiHSMCommandFailedException - if the YubiHSM fail to execute the command

YubiHSMErrorException - if validation fail for some values returned by the YubiHSM

YubiHSMInputException - if an argument does not validate

generateRandomAEAD

public Map<String,String> generateRandomAEAD(String nonce,
                                    int keyHandle,
                                    int length)
                                      throws YubiHSMCommandFailedException,
                                             YubiHSMErrorException,
                                             YubiHSMInputException

Generate a random AEAD block using the YubiHSM internal TRNG. To generate a secret for a YubiKey use public_id as nonce.

Parameters:

nonce - the nonce or public_id

keyHandle - the key to use

length - the resulting byte length of the AEAD

Returns:

a hash map with the AEAD and nonce

Throws:

YubiHSMCommandFailedException - if the YubiHSM fail to execute the command

YubiHSMErrorException - if validation fail for some values returned by the YubiHSM

YubiHSMInputException - if an argument does not validate

generateBufferAEAD

public Map<String,String> generateBufferAEAD(String nonce,
                                    int keyHandle)
                                      throws YubiHSMCommandFailedException,
                                             YubiHSMErrorException,
                                             YubiHSMInputException

Generate AEAD block of data buffer for a specific key. After a key has been loaded into the internal data buffer, this command can be used a number of times to get AEADs of the data buffer for different key handles. For example, to encrypt a YubiKey secrets to one or more Yubico KSM's that all have a YubiHSM attached to them.

Parameters:

nonce - the nonce

keyHandle - the key to use

Returns:

a hash map with the AEAD and nonce

Throws:

YubiHSMCommandFailedException - if the YubiHSM fail to execute the command

YubiHSMErrorException - if validation fail for some values returned by the YubiHSM

YubiHSMInputException - if an argument does not validate

generateOathAEAD

public String generateOathAEAD(String nonce,
                      int keyHandle,
                      String tokenSeed)
                        throws YubiHSMInputException,
                               YubiHSMErrorException,
                               YubiHSMCommandFailedException

Generate AEAD block which can be used for OATH OTP validation, see validateOathHOTP and validateOathTOTP.

Parameters:

nonce - the nonce

keyHandle - the key handle with permission to generateBufferAEAD

tokenSeed - the OATH token seed

Returns:

returns an AEAD

Throws:

YubiHSMInputException - thrown if an argument fail to validate

YubiHSMErrorException - thrown if an error have occurred

YubiHSMCommandFailedException - thrown if the YubiHSM fail to execute a command

validateAEAD

public boolean validateAEAD(String nonce,
                   int keyHandle,
                   String aead,
                   byte[] plaintext)
                     throws YubiHSMInputException,
                            YubiHSMCommandFailedException,
                            YubiHSMErrorException

Validate an AEAD using the YubiHSM, matching it against some known plain text. Matching is done inside the YubiHSM so the decrypted AEAD is never exposed.

Parameters:

nonce - the nonce or public_id

keyHandle - the key to use

aead - the AEAD (hex string)

plaintext - the plain text data

Returns:

returns true if validation was a success, false if the validation failed

Throws:

YubiHSMCommandFailedException - if the YubiHSM fail to execute the command

YubiHSMErrorException - if validation fail for some values returned by the YubiHSM

YubiHSMInputException - if an argument does not validate

validateAEAD

public boolean validateAEAD(String nonce,
                   int keyHandle,
                   String aead,
                   String plaintext)
                     throws YubiHSMInputException,
                            YubiHSMCommandFailedException,
                            YubiHSMErrorException

Validate an AEAD using the YubiHSM, matching it against some known plain text. Matching is done inside the YubiHSM so the decrypted AEAD is never exposed.

Parameters:

nonce - the nonce or public_id

keyHandle - the key to use

aead - the AEAD (hex string)

plaintext - the plain text data

Returns:

returns true if validation was a success, false if the validation failed

Throws:

YubiHSMCommandFailedException - if the YubiHSM fail to execute the command

YubiHSMErrorException - if validation fail for some values returned by the YubiHSM

YubiHSMInputException - if an argument does not validate

loadBufferData

public int loadBufferData(String data,
                 int offset)
                   throws YubiHSMErrorException

Load data into the YubiHSMs internal buffer.

Parameters:

data - the data to load into the internal buffer

offset - the offset where to load the data, if set to 0 the buffer will reset before loading the data

Returns:

the length of the loaded buffer

Throws:

YubiHSMErrorException - if validation fail for some values returned by the YubiHSM

loadBufferData

public int loadBufferData(byte[] data,
                 int offset)
                   throws YubiHSMErrorException

Load data into the YubiHSMs internal buffer.

Parameters:

data - the data to load into the internal buffer

offset - the offset where to load the data, if set to 0 the buffer will reset before loading the data

Returns:

the length of the loaded buffer

Throws:

YubiHSMErrorException - if validation fail for some values returned by the YubiHSM

loadRandomBufferData

public int loadRandomBufferData(int length,
                       int offset)
                         throws YubiHSMErrorException

Load random data into the YubiHSMs internal buffer.

Parameters:

length - the length of the generated data

offset - the offset where to load the data, if set to 0 the buffer will reset before loading the data

Returns:

the length of the loaded buffer

Throws:

YubiHSMErrorException - if validation fail for some values returned by the YubiHSM

exitMonitorDebugMode

public void exitMonitorDebugMode()
                          throws YubiHSMErrorException

Tell the YubiHSM to exit to configuration mode (requires 'debug' mode enabled).

Throws:

YubiHSMErrorException - if the YubiHSM exit monitor command fail

loadTemporaryKey

public boolean loadTemporaryKey(String nonce,
                       int keyHandle,
                       String aead)
                         throws YubiHSMCommandFailedException,
                                YubiHSMErrorException,
                                YubiHSMInputException

Load the content of an AEAD into the phantom key handle 0xffffffff.

Parameters:

nonce - the nonce

keyHandle - the key handle with permission to use YSM_TEMP_KEY_LOAD

aead - the AEAD to load into the phantom key handle

Returns:

returns true if the AEAD was successfully loaded

Throws:

YubiHSMCommandFailedException - command fail exception

YubiHSMErrorException - error exception

YubiHSMInputException - argument exceptions

generateHMACSHA1

public byte[] generateHMACSHA1(byte[] bytes,
                      int keyHandle,
                      boolean toBuffer)
                        throws YubiHSMInputException,
                               YubiHSMCommandFailedException,
                               YubiHSMErrorException

Generate HMAC SHA1 using a key handle in the YubiHSM.

Parameters:

bytes - the data used to generate the SHA1

keyHandle - the key handle to use in the YubiHSM

toBuffer - set to true to get the SHA1 stored into the internal buffer, for use in some other cryptographic operations.

Returns:

a map containing status and SHA1 hash

Throws:

YubiHSMCommandFailedException - if the YubiHSM fail to execute the command

YubiHSMErrorException - if validation fail for some values returned by the YubiHSM

YubiHSMInputException - if an argument does not validate

generateHMACSHA1

public Map<String,String> generateHMACSHA1(String data,
                                  int keyHandle,
                                  boolean last,
                                  boolean toBuffer)
                                    throws YubiHSMInputException,
                                           YubiHSMCommandFailedException,
                                           YubiHSMErrorException

Generate HMAC SHA1 using a key handle in the YubiHSM.

Parameters:

data - the data used to generate the SHA1

keyHandle - the key handle to use in the YubiHSM

last - set to false to not get a hash generated for the initial request

toBuffer - set to true to get the SHA1 stored into the internal buffer, for use in some other cryptographic operations.

Returns:

a map containing status and SHA1 hash

Throws:

YubiHSMCommandFailedException - if the YubiHSM fail to execute the command

YubiHSMErrorException - if validation fail for some values returned by the YubiHSM

YubiHSMInputException - if an argument does not validate

generateHMACSHA1

public Map<String,String> generateHMACSHA1(byte[] data,
                                  int keyHandle,
                                  boolean last,
                                  boolean toBuffer)
                                    throws YubiHSMInputException,
                                           YubiHSMCommandFailedException,
                                           YubiHSMErrorException

Generate HMAC SHA1 using a key handle in the YubiHSM.

Parameters:

data - the data used to generate the SHA1

keyHandle - the key handle to use in the YubiHSM

last - set to false to not get a hash generated for the initial request

toBuffer - set to true to get the SHA1 stored into the internal buffer, for use in some other cryptographic operations.

Returns:

a map containing status and SHA1 hash

Throws:

YubiHSMCommandFailedException - if the YubiHSM fail to execute the command

YubiHSMErrorException - if validation fail for some values returned by the YubiHSM

YubiHSMInputException - if an argument does not validate

generateHMACSHA1

public Map<String,String> generateHMACSHA1(String data,
                                  int keyHandle,
                                  byte flags,
                                  boolean last,
                                  boolean toBuffer)
                                    throws YubiHSMInputException,
                                           YubiHSMCommandFailedException,
                                           YubiHSMErrorException

Generate HMAC SHA1 using a key handle in the YubiHSM.

Parameters:

data - the data used to generate the SHA1

keyHandle - the key handle to use in the YubiHSM

flags - set custom flags to be used when generating a SHA1, if set to (byte) 0 defaults will be used.

last - set to false to not get a hash generated for the initial request

toBuffer - set to true to get the SHA1 stored into the internal buffer, for use in some other cryptographic operations.

Returns:

a map containing status and SHA1 hash

Throws:

YubiHSMCommandFailedException - if the YubiHSM fail to execute the command

YubiHSMErrorException - if validation fail for some values returned by the YubiHSM

YubiHSMInputException - if an argument does not validate

generateHMACSHA1

public Map<String,String> generateHMACSHA1(byte[] data,
                                  int keyHandle,
                                  byte flags,
                                  boolean last,
                                  boolean toBuffer)
                                    throws YubiHSMInputException,
                                           YubiHSMCommandFailedException,
                                           YubiHSMErrorException

Generate HMAC SHA1 using a key handle in the YubiHSM.

Parameters:

data - the data used to generate the SHA1

keyHandle - the key handle to use in the YubiHSM

flags - set custom flags to be used when generating a SHA1, if set to (byte) 0 defaults will be used.

last - set to false to not get a hash generated for the initial request

toBuffer - set to true to get the SHA1 stored into the internal buffer, for use in some other cryptographic operations.

Returns:

a map containing status and SHA1 hash

Throws:

YubiHSMCommandFailedException - if the YubiHSM fail to execute the command

YubiHSMErrorException - if validation fail for some values returned by the YubiHSM

YubiHSMInputException - if an argument does not validate

generateHMACSHA1Next

public Map<String,String> generateHMACSHA1Next(String data,
                                      int keyHandle,
                                      boolean last,
                                      boolean toBuffer)
                                        throws YubiHSMInputException,
                                               YubiHSMCommandFailedException,
                                               YubiHSMErrorException

Add more input to the HMAC SHA1, used after calling generateHMACSHA1(byte[], int, boolean) with last set to false.

Parameters:

data - the data to add before generating SHA1

keyHandle - the key handle to use in the YubiHSM

last - set to false to not get a hash generated after this call

toBuffer - set to true to get the SHA1 stored into the internal buffer, for use in some other cryptographic operations.

Returns:

a map containing status and SHA1 hash

Throws:

YubiHSMCommandFailedException - if the YubiHSM fail to execute the command

YubiHSMErrorException - if validation fail for some values returned by the YubiHSM

YubiHSMInputException - if an argument does not validate

generateHMACSHA1Next

public Map<String,String> generateHMACSHA1Next(byte[] data,
                                      int keyHandle,
                                      boolean last,
                                      boolean toBuffer)
                                        throws YubiHSMInputException,
                                               YubiHSMCommandFailedException,
                                               YubiHSMErrorException

Add more input to the HMAC SHA1, used after calling generateHMACSHA1(byte[], int, boolean) with last set to false.

Parameters:

data - the data to add before generating SHA1

keyHandle - the key handle to use in the YubiHSM

last - set to false to not get a hash generated after this call

toBuffer - set to true to get the SHA1 stored into the internal buffer, for use in some other cryptographic operations.

Returns:

a map containing status and SHA1 hash

Throws:

YubiHSMCommandFailedException - if the YubiHSM fail to execute the command

YubiHSMErrorException - if validation fail for some values returned by the YubiHSM

YubiHSMInputException - if an argument does not validate

encryptAES_ECB

public String encryptAES_ECB(String plaintext,
                    int keyHandle)
                      throws YubiHSMErrorException,
                             YubiHSMInputException,
                             YubiHSMCommandFailedException

AES ECB encrypt a plaintext string using a specific key handle.

Parameters:

keyHandle - the key handle to use when encrypting AES ECB

plaintext - the plaintext string

Returns:

a hash string in hex format

Throws:

YubiHSMInputException - if an argument does not validate

YubiHSMErrorException - if validation fail for some values returned by the YubiHSM

YubiHSMCommandFailedException - if the YubiHSM fail to execute the command

decryptAES_ECB

public String decryptAES_ECB(String cipherText,
                    int keyHandle)
                      throws YubiHSMErrorException,
                             YubiHSMInputException,
                             YubiHSMCommandFailedException

AES ECB decrypt a cipher text using a specific key handle.

Parameters:

keyHandle - the key handle to use when decrypting AES ECB

cipherText - the cipher string

Returns:

a plaintext string

Throws:

YubiHSMInputException - if an argument does not validate

YubiHSMErrorException - if validation fail for some values returned by the YubiHSM

YubiHSMCommandFailedException - if the YubiHSM fail to execute the command

compareAES_ECB

public boolean compareAES_ECB(int keyHandle,
                     String cipherText,
                     String plaintext)
                       throws YubiHSMCommandFailedException,
                              YubiHSMErrorException,
                              YubiHSMInputException

AES ECB decrypt a cipher text using a specific key handle, and then compare it with the supplied plaintext.

Parameters:

keyHandle - the key handle to use when comparing AES ECB cipher with plaintext

cipherText - the cipher string

plaintext - the plaintext string

Returns:

true if successful, false if not successful

Throws:

YubiHSMInputException - if an argument does not validate

YubiHSMErrorException - if validation fail for some values returned by the YubiHSM

YubiHSMCommandFailedException - if the YubiHSM fail to execute the command

unlock

public boolean unlock(String password)
               throws YubiHSMErrorException,
                      YubiHSMCommandFailedException,
                      YubiHSMInputException

Generic key store unlock method that calls the appropriate unlock function for this YubiHSM.

Parameters:

password - the Master key/HSM password in hex format

Returns:

true if unlock/decrypt was successful, otherwise an YubiHSMCommandFailedException is thrown

Throws:

YubiHSMCommandFailedException - command failed exception

YubiHSMErrorException - error exception

YubiHSMInputException - argument exception

See Also:

keyStoreDecrypt(String), keyStorageUnlock(String)

keyStoreDecrypt

public boolean keyStoreDecrypt(String key)
                        throws YubiHSMCommandFailedException,
                               YubiHSMErrorException,
                               YubiHSMInputException

Decrypt the YubiHSM key storage using the Master key.

Parameters:

key - the Master key in hex format (see output of automatic Master key generation during HSM configuration)

Returns:

true if unlock was successful, otherwise an YubiHSMCommandFailedException is thrown

Throws:

YubiHSMCommandFailedException - command failed exception

YubiHSMErrorException - error exception

YubiHSMInputException - argument exception

keyStorageUnlock

public boolean keyStorageUnlock(String password)
                         throws YubiHSMCommandFailedException,
                                YubiHSMErrorException,
                                YubiHSMInputException

Unlock the YubiHSM key storage using the HSM password.

Parameters:

password - the password in hex format (see output of automatic password generation during HSM configuration)

Returns:

true if unlock was successful, otherwise an YubiHSMCommandFailedException is thrown

Throws:

YubiHSMCommandFailedException - command failed exception

YubiHSMErrorException - error exception

YubiHSMInputException - argument exception

unlockOtp

public boolean unlockOtp(String publicId,
                String otp)
                  throws YubiHSMCommandFailedException,
                         YubiHSMErrorException,
                         YubiHSMInputException

Have the YubiHSM unlock the HSM operations (those involving the keystore) with a YubiKey OTP.

Parameters:

publicId - the YubiKey public id (in hex)

otp - the YubiKey OTP (in hex)

Returns:

true if unlock was successful

Throws:

YubiHSMErrorException - error exceptions

YubiHSMInputException - argument exceptions

YubiHSMCommandFailedException - command failed exception

validateOathHOTP

public int validateOathHOTP(int keyHandle,
                   String nonce,
                   String aead,
                   int counter,
                   String otp,
                   int lookAhead)
                     throws YubiHSMCommandFailedException,
                            YubiHSMErrorException,
                            YubiHSMInputException

Validate OATH-HOTP by a token whose seed is available to the YubiHSM through an AEAD.

Parameters:

keyHandle - a keyHandle with the permission YSM_TEMP_KEY_LOAD enabled

nonce - the nonce used to generate the AEAD

aead - the AEAD based on the token seed

counter - the current OTP counter

otp - the token OTP

lookAhead - the number of iterations to run to find the current users OTP

Returns:

return next counter value on success, 0 if the OTP couldn't be validated

Throws:

YubiHSMInputException - argument exceptions

YubiHSMCommandFailedException - command failed exception

YubiHSMErrorException - error exception

validateOathTOTP

public boolean validateOathTOTP(int keyHandle,
                       String nonce,
                       String aead,
                       String otp,
                       int period,
                       int drift,
                       int backwardDrift,
                       int forwardDrift)
                         throws YubiHSMInputException,
                                YubiHSMCommandFailedException,
                                YubiHSMErrorException

Validate OATH-TOTP by a token whose seed is available to the YubiHSM through an AEAD.

Parameters:

keyHandle - a keyHandle with the permission YSM_TEMP_KEY_LOAD enabled

nonce - the nonce used to generate the AEAD

aead - the AEAD based on the token seed

otp - the token OTP

period - an integer giving the period between changes of the OTP value in seconds

drift - drift of the local clock to the client clock, can be used to adjust the time skew without changing the size of @backwardDrift and @forwardDrift

backwardDrift - the number of @period's we allow to backstep

forwardDrift - the number of @period's we allow to look ahead

Returns:

return boolean, true if the OTP validated, false if the OTP validation failed

Throws:

YubiHSMInputException - argument exceptions

YubiHSMCommandFailedException - command failed exception

YubiHSMErrorException - error exception

validateOathTOTP

public boolean validateOathTOTP(int keyHandle,
                       String nonce,
                       String aead,
                       String otp)
                         throws YubiHSMInputException,
                                YubiHSMCommandFailedException,
                                YubiHSMErrorException

Validate OATH-TOTP by a token whose seed is available to the YubiHSM through an AEAD. This method sets the following defaults: period = 30 seconds, drift = 0, backwardDrift = 1 and forwardDrift = 1.

Parameters:

keyHandle - a keyHandle with the permission YSM_TEMP_KEY_LOAD enabled

nonce - the nonce used to generate the AEAD

aead - the AEAD based on the token seed

otp - the token OTP

Returns:

return boolean, true if the OTP validated, false if the OTP validation failed

Throws:

YubiHSMInputException - argument exceptions

YubiHSMCommandFailedException - command failed exception

YubiHSMErrorException - error exception

getNonce

public Nonce getNonce(short increment)
               throws YubiHSMErrorException,
                      YubiHSMCommandFailedException

Get a nonce from the YubiHSM. Increment the nonce by the number supplied as increment. To get the current nonce send 0 as increment.

Parameters:

increment - the increment (short)

Returns:

returns a Nonce class

Throws:

YubiHSMErrorException - error exception

YubiHSMCommandFailedException - command failed exception

getRandom

public byte[] getRandom(int bytes)
                 throws YubiHSMErrorException,
                        YubiHSMInputException

Tell the YubiHSM to generate a number of random bytes.

Parameters:

bytes - the number of bytes to generate

Returns:

returns a byte array of random bytes

Throws:

YubiHSMErrorException - error exception

YubiHSMInputException - invalid argument exception

randomReseed

public boolean randomReseed(String seed)
                     throws YubiHSMCommandFailedException,
                            YubiHSMErrorException,
                            YubiHSMInputException

Provide YubiHSM DRBG_CTR with a new seed. The seed is a string of a length 32.

Parameters:

seed - the seed string with a length of 32

Returns:

return true on success, otherwise a YubiHSMCommandFailedException is thrown

Throws:

YubiHSMInputException - argument exception

YubiHSMErrorException - error exception

YubiHSMCommandFailedException - command failed exception

decodeYubikeyOtp

public Map<String,Integer> decodeYubikeyOtp(String publicId,
                                   int keyHandle,
                                   String aead,
                                   String otp)
                                     throws YubiHSMInputException,
                                            YubiHSMErrorException,
                                            YubiHSMCommandFailedException

Decrypt a YubiKey OTP using an AEAD.

Parameters:

publicId - the nonce used to generate the AEAD (YubiKey publicId)

keyHandle - a keyHandle with the permission YSM_AEAD_YUBIKEY_OTP_DECODE enabled

aead - the AEAD based on the token seed

otp - the token OTP (in hex)

Returns:

a map with the decrypted data fields

Throws:

YubiHSMInputException - argument exceptions

YubiHSMCommandFailedException - command failed exception

YubiHSMErrorException - error exception

drainData

public boolean drainData()

Drain all remaining output from the YubiHSM, used for debugging.

Returns:

true if successful, false otherwise.

getRawDevice

public DeviceHandler getRawDevice()

Get the raw device, used for debugging.

Returns:

the device handler

getMinHashLength

public int getMinHashLength()

Get the minimum hash length used when generating or validating an AEAD.

Returns:

the minimum hash length

setMinHashLength

public void setMinHashLength(int value)

Set the minimum hash length generating or validating an AEAD.

Parameters:

value - the minimum hash length