yubihsm

Contains the main YubiHsm class used to connect to a YubiHSM device.

See YubiHsm.

Example:

>>> from yubihsm import YubiHsm
... hsm = YubiHsm.connect('http://localhost:12345')
... session = hsm.create_session_derived(1, 'password')

Submodules

Classes

YubiHsm

An unauthenticated connection to a YubiHSM.

Package Contents

class yubihsm.YubiHsm(backend)[source]

An unauthenticated connection to a YubiHSM.

Parameters:: backend (yubihsm.backends.YhsmBackend)

close()[source]

Disconnect from the backend, freeing any resources in use by it.

Return type:: None

send_cmd(cmd, data=b'')[source]

Encode and send a command byte and its associated data.

Parameters:

cmd (yubihsm.defs.COMMAND) – The command to send.
data (bytes) – The command payload to send.

Returns:

The response data from the YubiHSM.

Return type:

bytes

get_device_info()[source]

Get general device information from the YubiHSM.

Returns:: Device information.
Return type:: DeviceInfo

get_device_public_key()[source]

Retrieve the device’s public key.

Returns:: The device public key.
Return type:: cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey

init_session(auth_key_id)[source]

Initiate the symmetric authentication process for establishing an authenticated session with the YubiHSM.

Parameters:: auth_key_id (int) – The ID of the Authentication key used to authenticate the session.
Returns:: A negotiation of an authenticated Session with a YubiHSM.
Return type:: SymmetricAuth

init_session_asymmetric(auth_key_id, epk_oce)[source]

Initiate the asymmetric authentication process for establishing an authenticated session with the YubiHSM.

Parameters:

auth_key_id (int) – The ID of the Authentication key used to authenticate the session.
epk_oce (bytes) – The ephemeral public key of the OCE used for key agreement.

Return type:

AsymmetricAuth

create_session(auth_key_id, key_enc, key_mac)[source]

Create an authenticated session with the YubiHSM.

See also create_session_derived, which derives K-ENC and K-MAC from a password.

Parameters:

auth_key_id (int) – The ID of the Authentication key used to authenticate the session.
key_enc (bytes) – Static K-ENC used to establish session.
key_mac (bytes) – Static K-MAC used to establish session.

Returns:

An authenticated session.

Return type:

AuthSession

create_session_derived(auth_key_id, password)[source]

Create an authenticated session with the YubiHSM.

Uses a supplied password to derive the keys K-ENC and K-MAC.

Parameters:

auth_key_id (int) – The ID of the Authentication key used to authenticate the session.
password (str) – The password used to derive the keys from.

Returns:

An authenticated session.

Return type:

AuthSession

create_session_asymmetric(auth_key_id, private_key, public_key=None)[source]

Create an authenticated session with the YubiHSM.

Parameters:

auth_key_id (int) – The ID of the Authentication key used to authenticate the session.
private_key (cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey) – Private key corresponding to the public authentication key object.
public_key (Optional[cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey]) – The device’s public key. If omitted, the public key is fetched from the YubiHSM.

Returns:

An authenticated session.

Return type:

AuthSession

classmethod connect(url=None)[source]

Return a YubiHsm connected to the backend specified by the URL.

If no URL is given this will attempt to connect to a YubiHSM connector running on localhost, using the default port.

Parameters:: url (Optional[str]) – A http(s):// or yhusb:// backend URL.
Returns:: A YubiHsm instance connected to the backend referenced by the url.
Return type:: YubiHsm