pyhsm.base.YHSM

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, test_comm=True) |
__repr__(self) |
bool |
reset(self, test_sync=True) Perform stream resynchronization. |
bool |
set_debug(self, new) Set debug mode. |
test_comm(self) Verify that data we send to and receive from the YubiHSM isn't mangled. |
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, nonce=None) 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

### test_comm(self) |
Verify that data we send to and receive from the YubiHSM isn't mangled. In some scenarios, communications with the YubiHSM might be affected by terminal line settings turning CR into LF for example.

### echo(self, data) |
Echo test. Parameters: `data` (string) Returns: string data read from YubiHSM -- should equal `data' See Also: pyhsm.basic_cmd.YHSM_Cmd_Echo

### info(self) |
Get firmware version and unique ID from YubiHSM. Returns: YHSM_Cmd_System_Info System information See Also: pyhsm.basic_cmd.YHSM_Cmd_System_Info

### 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 See Also: pyhsm.basic_cmd.YHSM_Cmd_Random

### 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 See Also: pyhsm.basic_cmd.YHSM_Cmd_Random_Reseed

### 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 See Also: pyhsm.basic_cmd.YHSM_Cmd_Nonce_Get

### 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 See Also: pyhsm.basic_cmd.YHSM_Cmd_Temp_Key_Load

### 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 See Also: pyhsm.basic_cmd.YHSM_Cmd_Key_Storage_Unlock, pyhsm.basic_cmd.YHSM_Cmd_HSM_Unlock

### 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: `secret` (pyhsm.aead_cmd.YHSM_YubiKeySecret or string) - YubiKey secret to load Returns: integer Number of bytes in YubiHSM internal buffer after load See Also: pyhsm.buffer_cmd.YHSM_Cmd_Buffer_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 See Also: pyhsm.buffer_cmd.YHSM_Cmd_Buffer_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 See Also: pyhsm.buffer_cmd.YHSM_Cmd_Buffer_Random_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. See Also: pyhsm.aead_cmd.YHSM_Cmd_AEAD_Generate

### 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. See Also: pyhsm.aead_cmd.YHSM_Cmd_AEAD_Random_Generate

### 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. See Also: pyhsm.aead_cmd.YHSM_Cmd_AEAD_Buffer_Generate

### 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. See Also: pyhsm.aead_cmd.YHSM_Cmd_AEAD_Decrypt_Cmp

### 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 See Also: pyhsm.validate_cmd.YHSM_Cmd_AEAD_Validate_OTP

### monitor_exit(self) |
Ask YubiHSM to exit to configuration mode (requires 'debug' mode enabled). Returns: NoneType None See Also: pyhsm.debug_cmd.YHSM_Cmd_Monitor_Exit

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

### 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 See Also: pyhsm.hmac_cmd.YHSM_Cmd_HMAC_SHA1_Write

### db_store_yubikey(self, public_id, key_handle, aead, nonce=None) |
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: `public_id` (string) - The six bytes public id of the YubiKey `key_handle` (integer or string) - Key handle that can decrypt the YubiKey AEAD `aead` (YHSM_GeneratedAEAD or string) - AEAD of an pyhsm.aead_cmd.YHSM_YubiKeySecret `nonce` (None or string) - Nonce, if different from public_id. Returns: bool True on success See Also: pyhsm.db_cmd.YHSM_Cmd_DB_YubiKey_Store

### 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 See Also: pyhsm.db_cmd.YHSM_Cmd_DB_Validate_OTP