yubihsm.core

Core classes for YubiHSM communication.

Attributes

KEY_ENC
KEY_MAC
KEY_RMAC
CARD_CRYPTOGRAM
HOST_CRYPTOGRAM

Classes

DeviceInfo	Data class holding various information about the YubiHSM.
LogEntry	YubiHSM log entry.
LogData	Data class holding response data from a GET_LOGS command.
YubiHsm	An unauthenticated connection to a YubiHSM.
SymmetricAuth	A negotiation of an authenticated Session with a YubiHSM.
AsymmetricAuth	A negotiation of an authenticated Session with a YubiHSM.
AuthSession	An authenticated secure session with a YubiHSM.

Module Contents

yubihsm.core.KEY_ENC = 4

yubihsm.core.KEY_MAC = 6

yubihsm.core.KEY_RMAC = 7

yubihsm.core.CARD_CRYPTOGRAM = 0

yubihsm.core.HOST_CRYPTOGRAM = 1

class yubihsm.core.DeviceInfo

Data class holding various information about the YubiHSM.

Variables:

• version – YubiHSM version tuple.

• serial – YubiHSM serial number.

• log_size – Log entry storage capacity.

• log_used – Log entries currently stored.

• supported_algorithms – List of supported algorithms.

• part_number – Chip designator.

FORMAT: ClassVar[str] = '!BBBIBB'

LENGTH: ClassVar[int]

version: yubihsm.defs.Version

serial: int

log_size: int

log_used: int

supported_algorithms: Set[yubihsm.defs.ALGORITHM]

part_number: str | None

classmethod parse(first_page, second_page=None)

Parse a DeviceInfo from its binary representation.

Parameters:

• first_page (bytes)

• second_page (Optional[bytes])

Return type:

DeviceInfo

class yubihsm.core.LogEntry

YubiHSM log entry.

Parameters:

• number (int) – The sequence number of the entry.

• command (int) – The COMMAND executed.

• length (int) – The length of the command.

• session_key (int) – The ID of the Authentication Key for the session.

• target_key (int) – The ID of the key used by the command.

• second_key (int) – The ID of the secondary key used by the command, if applicable.

• result (int) – The result byte of the response.

• tick (int) – The YubiHSM system tick value when the command was run.

• digest (bytes) – A truncated hash of the entry and previous digest.

FORMAT: ClassVar[str] = '!HBHHHHBL16s'

LENGTH: ClassVar[int]

number: int

command: yubihsm.defs.COMMAND

length: int

session_key: int

target_key: int

second_key: int

result: int

tick: int

digest: bytes

property data: bytes

Get log entry binary data.

Returns:

The binary LogEntry data, excluding the digest.

Return type:

bytes

classmethod parse(data)

Parse a LogEntry from its binary representation.

Parameters:

data (bytes) – Binary data to unpack from.

Returns:

The parsed object.

Return type:

LogEntry

validate(previous_entry)

Validate the hash of a single log entry.

Validates the hash of this entry with regard to the previous entry’s hash. The previous entry is the LogEntry with the previous number, previous_entry.number == self.number - 1

Parameters:

previous_entry (LogEntry) – The previous log entry to validate against.

Returns:

True if the digest is correct, False if not.

Return type:

bool

class yubihsm.core.LogData

Bases: NamedTuple

Data class holding response data from a GET_LOGS command.

Parameters:

• n_boot – Number of unlogged boot events.

• n_auth – Number of unlogged authentication events.

• entries – List of LogEntry items.

n_boot: int

n_auth: int

entries: Sequence[LogEntry]

class yubihsm.core.YubiHsm(backend)

An unauthenticated connection to a YubiHSM.

Parameters:

backend (yubihsm.backends.YhsmBackend)

close()

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

Return type:

None

send_cmd(cmd, data=b'')

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()

Get general device information from the YubiHSM.

Returns:

Device information.

Return type:

DeviceInfo

get_device_public_key()

Retrieve the device’s public key.

Returns:

The device public key.

Return type:

cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey

init_session(auth_key_id)

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)

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)

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)

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)

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)

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

class yubihsm.core.SymmetricAuth(hsm, sid, context, card_crypto)

A negotiation of an authenticated Session with a YubiHSM.

This class is used to begin the mutual authentication process for establishing an authenticated session with the YubiHSM, using symmetric authentication. Typically you get an instance of this class by calling init_session().

Parameters:

• hsm (YubiHsm)

• sid (int)

• context (bytes)

• card_crypto (bytes)

property context: bytes

The authentication context (host challenge + card challenge).

Return type:

bytes

property card_crypto: bytes

The card cryptogram.

Return type:

bytes

classmethod init_session(hsm, auth_key_id)

Initiate the mutual symmetric session authentication process.

Parameters:

• hsm (YubiHsm) – The YubiHSM connection.

• auth_key_id (int) – The ID of the Authentication key used to authenticate the session.

Return type:

SymmetricAuth

classmethod create_session(hsm, auth_key_id, key_enc, key_mac)

Construct an authenticated session.

Parameters:

• hsm (YubiHsm) – The YubiHSM connection.

• auth_key_id (int) – The ID of the Authentication key used to authenticate the session.

• key_enc (bytes) – Static K-ENC used to establish the session.

• key_mac (bytes) – Static K-MAC used to establish the session.

Return type:

AuthSession

authenticate(key_senc, key_smac, key_srmac)

Construct an authenticated session.

Parameters:

• key_senc (bytes) – S-ENC used for data confidentiality.

• key_smac (bytes) – S-MAC used for data and protocol integrity.

• key_srmac (bytes) – S-RMAC used for data and protocol integrity.

Returns:

An authenticated session.

Return type:

AuthSession

class yubihsm.core.AsymmetricAuth(hsm, sid, context, receipt)

A negotiation of an authenticated Session with a YubiHSM.

This class is used to begin the mutual authentication process for establishing an authenticated session with the YubiHSM, using asymmetric authentication. Typically you get an instance of this class by calling init_session_asymmetric().

Parameters:

• hsm (YubiHsm)

• sid (int)

• context (bytes)

• receipt (bytes)

property context: bytes

The authentication context (EPK.OCE + EPK.SD).

Return type:

bytes

property receipt: bytes

The receipt.

Return type:

bytes

property epk_hsm: bytes

The ephemeral public key of the YubiHSM.

Return type:

bytes

classmethod init_session(hsm, auth_key_id, epk_oce)

Initiate the mutual asymmetric session authentication process.

Parameters:

• hsm (YubiHsm) – The YubiHSM connection.

• 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

classmethod create_session(hsm, auth_key_id, private_key, public_key)

Construct an authenticated session.

Parameters:

• hsm (YubiHsm) – The YubiHSM connection.

• 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 (cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey) – The device’s public key.

Return type:

AuthSession

authenticate(key_senc, key_smac, key_srmac)

Construct an authenticated session.

Parameters:

• key_senc (bytes) – S-ENC used for data confidentiality.

• key_smac (bytes) – S-MAC used for data and protocol integrity.

• key_srmac (bytes) – S-RMAC used for data and protocol integrity.

Returns:

An authenticated session.

Return type:

AuthSession

class yubihsm.core.AuthSession(hsm, sid, key_enc, key_mac, key_rmac, mac_chain)

An authenticated secure session with a YubiHSM.

Typically you get an instance of this class by calling create_session(), create_session_derived(), or create_session_asymmetric().

Parameters:

• hsm (YubiHsm)

• sid (int)

• key_enc (bytes)

• key_mac (bytes)

• key_rmac (bytes)

• mac_chain (bytes)

close()

Close this session with the YubiHSM.

Once closed, this session object can no longer be used, unless re-connected.

Return type:

None

property sid: int | None

Session ID

Returns:

The ID of the session.

Return type:

Optional[int]

send_secure_cmd(cmd, data=b'')

Send a command over the encrypted session.

Parameters:

• cmd (yubihsm.defs.COMMAND) – The command to send.

• data (bytes) – The command payload to send.

Returns:

The decrypted response data from the YubiHSM.

Return type:

bytes

list_objects(object_id=None, object_type=None, domains=None, capabilities=None, algorithm=None, label=None)

List objects from the YubiHSM.

This returns a list of all objects currently stored on the YubiHSM, which are accessible by this session. The arguments to this method can be used to filter the results returned.

Parameters:

• object_id (Optional[int]) – Return only objects with this ID.

• object_type (Optional[yubihsm.defs.OBJECT]) – Return only objects of this type.

• domains (Optional[int]) – Return only objects belonging to one or more of these domains.

• capabilities (Optional[int]) – Return only objects with one or more of these capabilities.

• algorithm (Optional[yubihsm.defs.ALGORITHM]) – Return only objects with this algorithm.

• label (Optional[str]) – Return only objects with this label.

Returns:

A list of matched objects.

Return type:

Sequence[yubihsm.objects.YhsmObject]

get_object(object_id, object_type)

Get a reference to a YhsmObject with the given id and type.

The object returned will be a subclass of YhsmObject corresponding to the given object_type.

Parameters:

• object_id (int) – The ID of the object to retrieve.

• object_type (yubihsm.defs.OBJECT) – The type of the object to retrieve.

Returns:

An object reference.

Return type:

yubihsm.objects.YhsmObject

get_pseudo_random(length)

Get bytes from YubiHSM PRNG.

Parameters:

length (int) – The number of bytes to return.

Returns:

The requested number of random bytes.

Return type:

bytes

reset_device()

Perform a factory reset of the YubiHSM.

Resets and reboots the YubiHSM, deletes all Objects and restores the default Authkey.

Return type:

None

get_log_entries(previous_entry=None)

Get logs from the YubiHSM.

This returns a tuple of the number of unlogged boot events, the number of unlogged authentication events, and the log entries from the YubiHSM. The chain of entry digests will be validated, starting from the first entry returned, or the one supplied as previous_entry.

Parameters:

previous_entry (Optional[LogEntry]) – Entry to start verification against.

Returns:

A tuple consisting of the number of unlogged boot and authentication events, and the list of log entries.

Return type:

LogData

set_log_index(index)

Clear logs to free up space for use with forced audit.

Parameters:

index (int) – The log entry index to clear up to (inclusive).

Return type:

None

put_option(option, value)

Set the raw value of a YubiHSM device option.

Parameters:

• option (yubihsm.defs.OPTION) – The OPTION to set.

• value (bytes) – The value to set the OPTION to.

Return type:

None

get_option(option)

Get the raw value of a YubiHSM device option.

Parameters:

option (yubihsm.defs.OPTION) – The OPTION to get.

Returns:

The currently set value for the given OPTION

Return type:

bytes

set_force_audit(audit)

Set the FORCE_AUDIT mode of the YubiHSM.

Parameters:

audit (yubihsm.defs.AUDIT) – The AUDIT mode to set.

Return type:

None

get_force_audit()

Get the current setting for forced audit mode.

Returns:

The AUDIT setting for FORCE_AUDIT.

Return type:

yubihsm.defs.AUDIT

set_command_audit(commands)

Set audit mode of commands.

Takes a dict of COMMAND -> AUDIT pairs and updates the audit settings for the commands given.

Parameters:

commands (Mapping[yubihsm.defs.COMMAND, yubihsm.defs.AUDIT]) – Settings to update.

Example:

Return type:

None

>>> session.set_comment_audit({
...     COMMAND.ECHO: AUDIT.OFF,
...     COMMAND.LIST_OBJECTS: AUDIT.ON
... })

get_command_audit()

Get a mapping of all available commands and their audit settings.

Returns:

Dictionary of COMMAND -> AUDIT pairs.

Return type:

Mapping[yubihsm.defs.COMMAND, yubihsm.defs.AUDIT]

set_enabled_algorithms(algorithms)

Set audit mode of commands.

New in YubiHSM 2.2.0.

Algorithms can only be toggled on a “fresh” device (after reset, before adding objects).

Takes a dict of ALGORITHM -> bool pairs and updates the enabled algorithm settings for the algorithms given.

Parameters:

algorithms (Mapping[yubihsm.defs.ALGORITHM, bool]) – The algorithms to update.

Example:

Return type:

None

>>> session.set_enabled_algorithms({
...     ALGORITHM.RSA_2048: False,
...     ALGORITHM.RSA_OAEP_SHA256_: True,
... })

get_enabled_algorithms()

Get the algorithms available, and whether or not they are enabled.

Returns:

A mapping of algorithms, to whether or not they are enabled.

Return type:

Mapping[yubihsm.defs.ALGORITHM, bool]

set_fips_mode(mode)

Set the FIPS mode of the YubiHSM.

YubiHSM2 FIPS only.

This can only be toggled on a “fresh” device (after reset, before adding objects).

Parameters:

mode (bool) – Whether to be in FIPS compliant mode or not.

Return type:

None

get_fips_status()

Get the current FIPS status.

YubiHSM2 FIPS only.

Returns:

The FipsStatus value.

Return type:

yubihsm.defs.FIPS_STATUS

get_fips_mode()

Get the current setting for FIPS mode.

YubiHSM2 FIPS only.

Returns:

True if in FIPS mode, False if not.

Return type:

bool