Package pyhsm :: Module base :: Class YHSM
[frames] | no frames]

Class YHSM

Base class for accessing a YubiHSM.

Instance Methods
 
__init__(self, device, debug=False, timeout=1)
 
__repr__(self)
bool
reset(self, test_sync=True)
Perform stream resynchronization.
bool
set_debug(self, new)
Set debug mode.
string
echo(self, data)
Echo test.
YHSM_Cmd_System_Info
info(self)
Get firmware version and unique ID from YubiHSM.
string
random(self, num_bytes)
Get random bytes from YubiHSM.
bool
random_reseed(self, seed)
Provide YubiHSM DRBG_CTR with a new seed.
YHSM_NonceResponse
get_nonce(self, increment=1)
Get current nonce from YubiHSM.
bool
load_temp_key(self, nonce, key_handle, aead)
Load the contents of an AEAD into the phantom key handle 0xffffffff.
bool
unlock(self, password=None, otp=None)
Unlock the YubiHSM using the master key and/or a YubiKey OTP.
 
key_storage_unlock(self, password)
integer
load_secret(self, secret)
Ask YubiHSM to load a pre-existing YubiKey secret.
integer
load_data(self, data, offset)
Ask YubiHSM to load arbitrary data into it's internal buffer, at any offset.
integer
load_random(self, num_bytes, offset=0)
Ask YubiHSM to generate a number of random bytes to any offset of it's internal buffer.
YHSM_GeneratedAEAD
generate_aead_simple(self, nonce, key_handle, data)
Generate AEAD block from data for a specific key in a single step (without using the YubiHSM internal buffer).
YHSM_GeneratedAEAD
generate_aead_random(self, nonce, key_handle, num_bytes)
Generate a random AEAD block using the YubiHSM internal DRBG_CTR random generator.
YHSM_GeneratedAEAD
generate_aead(self, nonce, key_handle)
Ask YubiHSM to return an AEAD made of the contents of it's internal buffer (see load_secret, load_data and load_random) encrypted with the specified key_handle.
bool
validate_aead(self, nonce, key_handle, aead, cleartext)
Validate the contents of an AEAD using the YubiHSM.
YHSM_ValidationResult
validate_aead_otp(self, public_id, otp, key_handle, aead)
Ask YubiHSM to validate a YubiKey OTP using an AEAD and a key_handle to decrypt the AEAD.
NoneType
monitor_exit(self)
Ask YubiHSM to exit to configuration mode (requires 'debug' mode enabled).
Serial
get_raw_device(self)
Get the raw device.
bool
drain(self)
Read until there is nothing more to be read.
string
aes_ecb_encrypt(self, key_handle, plaintext)
AES ECB encrypt using a key handle.
string
aes_ecb_decrypt(self, key_handle, ciphertext)
AES ECB decrypt using a key handle.
bool
aes_ecb_compare(self, key_handle, ciphertext, plaintext)
AES ECB decrypt and then compare using a key handle.
YHSM_Cmd_HMAC_SHA1_Write
hmac_sha1(self, key_handle, data, flags=None, final=True, to_buffer=False)
Have the YubiHSM generate a HMAC SHA1 of 'data' using a key handle.
bool
db_store_yubikey(self, public_id, key_handle, aead)
Ask YubiHSM to store data about a YubiKey in the internal database (not buffer).
YHSM_ValidationResult
db_validate_yubikey_otp(self, public_id, otp)
Request the YubiHSM to validate an OTP for a YubiKey stored in the internal database.
Method Details

reset(self, test_sync=True)

 

Perform stream resynchronization.

Parameters:
  • test_sync (bool) - Verify sync with YubiHSM after reset
Returns: bool
True if successful

set_debug(self, new)

 

Set debug mode.

Parameters:
  • new (bool) - new value
Returns: bool
old value

echo(self, data)

 

Echo test.

Parameters:
  • data (string)
Returns: string
data read from YubiHSM -- should equal `data'

info(self)

 

Get firmware version and unique ID from YubiHSM.

Returns: YHSM_Cmd_System_Info
System information

random(self, num_bytes)

 

Get random bytes from YubiHSM.

The random data is DRBG_CTR seeded on each startup by a hardware TRNG, so it should be of very good quality.

Parameters:
  • num_bytes (integer)
Returns: string
Bytes with random data

random_reseed(self, seed)

 

Provide YubiHSM DRBG_CTR with a new seed.

Parameters:
  • seed (string) - new seed -- must be exactly 32 bytes
Returns: bool
True on success

get_nonce(self, increment=1)

 

Get current nonce from YubiHSM.

Use increment 0 to just fetch the value without incrementing it.

Parameters:
  • increment - requested increment (optional)
Returns: YHSM_NonceResponse
nonce value _before_ increment

load_temp_key(self, nonce, key_handle, aead)

 

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

Parameters:
  • nonce (string) - The nonce used when creating the AEAD
  • key_handle (integer or string) - The key handle that can decrypt the AEAD
  • aead (YHSM_GeneratedAEAD or string) - AEAD containing the cryptographic key and permission flags
Returns: bool
True on success

unlock(self, password=None, otp=None)

 

Unlock the YubiHSM using the master key and/or a YubiKey OTP.

If the master key is given during configuration, all key handles will be encrypted (with AES-256) using that passphrase.

If one or more admin Yubikey public id's are given during configuration, an OTP from one of these must be provided to the YubiHSM for it to start responding to cryptographic requests. The admin YubiKeys must be present in the internal database for this validation to work.

Parameters:
  • password (NoneType or string) - The 'master key' set during YubiHSM configuration
  • otp (NoneType or string) - A YubiKey OTP from an 'admin' YubiKey (modhex), to unlock YubiHSM.
Returns: bool
Only returns (True) on success

key_storage_unlock(self, password)

 

Deprecated: Too specific (and hard to remember) name.

See Also: unlock

load_secret(self, secret)

 

Ask YubiHSM to load a pre-existing YubiKey secret.

The data is stored internally in the YubiHSM in temporary memory - this operation would typically be followed by one or more generate_aead commands to actually retreive the generated secret (in encrypted form).

Parameters:
Returns: integer
Number of bytes in YubiHSM internal buffer after load

load_data(self, data, offset)

 

Ask YubiHSM to load arbitrary data into it's internal buffer, at any offset.

The data is stored internally in the YubiHSM in temporary memory - this operation would typically be followed by one or more generate_aead commands to actually retreive the generated secret (in encrypted form).

Load data to offset 0 to reset the buffer.

Parameters:
  • data (string) - arbitrary data to load
Returns: integer
Number of bytes in YubiHSM internal buffer after load

load_random(self, num_bytes, offset=0)

 

Ask YubiHSM to generate a number of random bytes to any offset of it's internal buffer.

The data is stored internally in the YubiHSM in temporary memory - this operation would typically be followed by one or more generate_aead commands to actually retreive the generated secret (in encrypted form).

Parameters:
  • num_bytes (integer) - Number of bytes to generate
Returns: integer
Number of bytes in YubiHSM internal buffer after load

generate_aead_simple(self, nonce, key_handle, data)

 

Generate AEAD block from data for a specific key in a single step (without using the YubiHSM internal buffer).

Parameters:
  • nonce (string) - The nonce to use when creating the AEAD
  • key_handle (integer or string) - The key handle that can encrypt data into an AEAD
  • data (string) - Data to put inside the AEAD
Returns: YHSM_GeneratedAEAD
The generated AEAD on success.

generate_aead_random(self, nonce, key_handle, num_bytes)

 

Generate a random AEAD block using the YubiHSM internal DRBG_CTR random generator.

To generate a secret for a YubiKey, use public_id as nonce.

Parameters:
  • nonce (string) - The nonce to use when creating the AEAD
  • key_handle (integer or string) - The key handle that can encrypt the random data into an AEAD
  • num_bytes (integer) - Number of random data bytes to put inside the AEAD
Returns: YHSM_GeneratedAEAD
The generated AEAD on success.

generate_aead(self, nonce, key_handle)

 

Ask YubiHSM to return an AEAD made of the contents of it's internal buffer (see load_secret, load_data and load_random) encrypted with the specified key_handle.

For a YubiKey secret, the nonce should be the public_id.

Parameters:
  • nonce (string) - The nonce to use when creating the AEAD
  • key_handle (integer or string) - The key handle that can create an AEAD
Returns: YHSM_GeneratedAEAD
The generated AEAD on success.

validate_aead(self, nonce, key_handle, aead, cleartext)

 

Validate the contents of an AEAD using the YubiHSM. The matching is done inside the YubiHSM so the contents of the AEAD is never exposed (well, except indirectionally when the cleartext does match).

The cleartext should naturally be of the same length as the AEAD minus the size of the MAC (8 bytes).

Parameters:
  • nonce (string) - The nonce used when creating the AEAD
  • key_handle (integer or string) - The key handle that can decrypt the AEAD
  • aead (YHSM_GeneratedAEAD or string) - AEAD containing the cryptographic key and permission flags
  • cleartext (string) - The presumed cleartext of the AEAD
Returns: bool
Whether or not the cleartext matches the contents of the AEAD.

validate_aead_otp(self, public_id, otp, key_handle, aead)

 

Ask YubiHSM to validate a YubiKey OTP using an AEAD and a key_handle to decrypt the AEAD.

Parameters:
  • public_id (string) - The six bytes public id of the YubiKey
  • otp (string) - The one time password (OTP) to validate
  • key_handle (integer or string) - The key handle that can decrypt the AEAD
  • aead (YHSM_GeneratedAEAD or string) - AEAD containing the cryptographic key and permission flags
Returns: YHSM_ValidationResult
validation response

monitor_exit(self)

 

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

Returns: NoneType
None

get_raw_device(self)

 

Get the raw device. Only intended for test code/debugging!

Returns: Serial
serial device

drain(self)

 

Read until there is nothing more to be read. Only intended for test code/debugging!

Returns: bool
True on success

aes_ecb_encrypt(self, key_handle, plaintext)

 

AES ECB encrypt using a key handle.

Parameters:
  • key_handle (integer or string) - Key handle to use for AES ECB encryption
  • plaintext (string) - Data to encrypt
Returns: string
Ciphertext

Warning: Please be aware of the known limitations of AES ECB mode before using it!

See Also: pyhsm.aes_ecb_cmd.YHSM_Cmd_AES_ECB_Encrypt

aes_ecb_decrypt(self, key_handle, ciphertext)

 

AES ECB decrypt using a key handle.

Parameters:
  • key_handle (integer or string) - Key handle to use for AES ECB decryption
  • ciphertext (string) - Data to decrypt
Returns: string
Plaintext

Warning: Please be aware of the known limitations of AES ECB mode before using it!

See Also: pyhsm.aes_ecb_cmd.YHSM_Cmd_AES_ECB_Decrypt

aes_ecb_compare(self, key_handle, ciphertext, plaintext)

 

AES ECB decrypt and then compare using a key handle.

The comparison is done inside the YubiHSM so the plaintext is never exposed (well, except indirectionally when the provided plaintext does match).

Parameters:
  • key_handle (integer or string) - Key handle to use for AES ECB decryption
  • plaintext (string) - Data to decrypt
Returns: bool
Match result

Warning: Please be aware of the known limitations of AES ECB mode before using it!

See Also: pyhsm.aes_ecb_cmd.YHSM_Cmd_AES_ECB_Compare.parse_result

hmac_sha1(self, key_handle, data, flags=None, final=True, to_buffer=False)

 

Have the YubiHSM generate a HMAC SHA1 of 'data' using a key handle.

Use the pyhsm.hmac_cmd.YHSM_Cmd_HMAC_SHA1_Write.next to add more input (until 'final' has been set to True).

Use the pyhsm.hmac_cmd.YHSM_Cmd_HMAC_SHA1_Write.get_hash to get the hash result this far.

Parameters:
  • key_handle (integer or string) - Key handle to use when generating HMAC SHA1
  • data (string) - what to calculate the HMAC SHA1 checksum of
  • flags (None or integer) - bit-flags, overrides 'final' and 'to_buffer'
  • final - True when there is no more data, False if there is more
  • to_buffer - Should the final result be stored in the YubiHSM internal buffer or not
Returns: YHSM_Cmd_HMAC_SHA1_Write
HMAC-SHA1 instance

db_store_yubikey(self, public_id, key_handle, aead)

 

Ask YubiHSM to store data about a YubiKey in the internal database (not buffer).

The input is an AEAD with the secrets of a YubiKey, perhaps previously created using load_secret.

Parameters:
Returns: bool
True on success

db_validate_yubikey_otp(self, public_id, otp)

 

Request the YubiHSM to validate an OTP for a YubiKey stored in the internal database.

Parameters:
  • public_id (string) - The six bytes public id of the YubiKey
  • otp (string) - The OTP from a YubiKey in binary form (16 bytes)
Returns: YHSM_ValidationResult
validation response