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