yubihsm package

Subpackages

Submodules

yubihsm.core module

Core classes for YubiHSM communication.

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

Bases: object

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

authenticate(key_senc, key_smac, key_srmac)[source]

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.

Return type:

AuthSession

Returns:

An authenticated session.

property context: bytes

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

classmethod create_session(hsm, auth_key_id, private_key, public_key)[source]

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 (EllipticCurvePrivateKey) – Private key corresponding to the public authentication key object.

  • public_key (EllipticCurvePublicKey) – The device’s public key.

Return type:

AuthSession

property epk_hsm: bytes

The ephemeral public key of the YubiHSM.

classmethod init_session(hsm, auth_key_id, epk_oce)[source]

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

property receipt: bytes

The receipt.

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

Bases: object

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

close()[source]

Close this session with the YubiHSM.

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

Return type:

None

get_command_audit()[source]

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

Return type:

Mapping[COMMAND, AUDIT]

Returns:

Dictionary of COMMAND -> AUDIT pairs.

get_enabled_algorithms()[source]

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

Return type:

Mapping[ALGORITHM, bool]

Returns:

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

get_fips_mode()[source]

Get the current setting for FIPS mode.

YubiHSM2 FIPS only.

Return type:

bool

Returns:

True if in FIPS mode, False if not.

get_fips_status()[source]

Get the current FIPS status.

YubiHSM2 FIPS only.

Return type:

FIPS_STATUS

Returns:

The FipsStatus value.

get_force_audit()[source]

Get the current setting for forced audit mode.

Return type:

AUDIT

Returns:

The AUDIT setting for FORCE_AUDIT.

get_log_entries(previous_entry=None)[source]

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.

Return type:

LogData

Returns:

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

get_object(object_id, object_type)[source]

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 (OBJECT) – The type of the object to retrieve.

Return type:

YhsmObject

Returns:

An object reference.

get_option(option)[source]

Get the raw value of a YubiHSM device option.

Parameters:

option (OPTION) – The OPTION to get.

Return type:

bytes

Returns:

The currently set value for the given OPTION

get_pseudo_random(length)[source]

Get bytes from YubiHSM PRNG.

Parameters:

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

Return type:

bytes

Returns:

The requested number of random bytes.

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

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[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[ALGORITHM]) – Return only objects with this algorithm.

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

Return type:

Sequence[YhsmObject]

Returns:

A list of matched objects.

put_option(option, value)[source]

Set the raw value of a YubiHSM device option.

Parameters:

  • option (OPTION) – The OPTION to set.

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

Return type:

None

reset_device()[source]

Perform a factory reset of the YubiHSM.

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

Return type:

None

send_secure_cmd(cmd, data=b'')[source]

Send a command over the encrypted session.

Parameters:

  • cmd (COMMAND) – The command to send.

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

Return type:

bytes

Returns:

The decrypted response data from the YubiHSM.

set_command_audit(commands)[source]

Set audit mode of commands.

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

Parameters:

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

Example:

>>> session.set_comment_audit({
:rtype: :sphinx_autodoc_typehints_type:`\:py\:obj\:\`None\``
...     COMMAND.ECHO: AUDIT.OFF,
...     COMMAND.LIST_OBJECTS: AUDIT.ON
... })
set_enabled_algorithms(algorithms)[source]

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[ALGORITHM, bool]) – The algorithms to update.

Example:

>>> session.set_enabled_algorithms({
:rtype: :sphinx_autodoc_typehints_type:`\:py\:obj\:\`None\``
...     ALGORITHM.RSA_2048: False,
...     ALGORITHM.RSA_OAEP_SHA256_: True,
... })
set_fips_mode(mode)[source]

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

set_force_audit(audit)[source]

Set the FORCE_AUDIT mode of the YubiHSM.

Parameters:

audit (AUDIT) – The AUDIT mode to set.

Return type:

None

set_log_index(index)[source]

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

property sid: int | None

Session ID

Returns:

The ID of the session.

class yubihsm.core.DeviceInfo(version, serial, log_size, log_used, supported_algorithms, part_number)[source]

Bases: object

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] = 9
log_size: int
log_used: int
classmethod parse(first_page, second_page=None)[source]

Parse a DeviceInfo from its binary representation.

Return type:

DeviceInfo

part_number: Optional[str]
serial: int
supported_algorithms: Set[ALGORITHM]
version: Tuple[int, int, int]
class yubihsm.core.LogData(n_boot: int, n_auth: int, entries: Sequence[LogEntry])[source]

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.

entries: Sequence[LogEntry]

Alias for field number 2

n_auth: int

Alias for field number 1

n_boot: int

Alias for field number 0

class yubihsm.core.LogEntry(number, command, length, session_key, target_key, second_key, result, tick, digest)[source]

Bases: object

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] = 32
command: COMMAND
property data: bytes

Get log entry binary data.

Returns:

The binary LogEntry data, excluding the digest.

digest: bytes
length: int
number: int
classmethod parse(data)[source]

Parse a LogEntry from its binary representation.

Parameters:

data (bytes) – Binary data to unpack from.

Return type:

LogEntry

Returns:

The parsed object.

result: int
second_key: int
session_key: int
target_key: int
tick: int
validate(previous_entry)[source]

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.

Return type:

bool

Returns:

True if the digest is correct, False if not.

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

Bases: object

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

authenticate(key_senc, key_smac, key_srmac)[source]

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.

Return type:

AuthSession

Returns:

An authenticated session.

property card_crypto: bytes

The card cryptogram.

property context: bytes

The authentication context (host challenge + card challenge).

classmethod create_session(hsm, auth_key_id, key_enc, key_mac)[source]

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

classmethod init_session(hsm, auth_key_id)[source]

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

class yubihsm.core.YubiHsm(backend)[source]

Bases: object

An unauthenticated connection to a YubiHSM.

close()[source]

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

Return type:

None

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.

Return type:

YubiHsm

Returns:

A YubiHsm instance connected to the backend referenced by the url.

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.

Return type:

AuthSession

Returns:

An authenticated session.

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 (EllipticCurvePrivateKey) – Private key corresponding to the public authentication key object.

  • public_key (Optional[EllipticCurvePublicKey]) – The device’s public key. If omitted, the public key is fetched from the YubiHSM.

Return type:

AuthSession

Returns:

An authenticated session.

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.

Return type:

AuthSession

Returns:

An authenticated session.

get_device_info()[source]

Get general device information from the YubiHSM.

Return type:

DeviceInfo

Returns:

Device information.

get_device_public_key()[source]

Retrieve the device’s public key.

Return type:

EllipticCurvePublicKey

Returns:

The device public key.

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.

Return type:

SymmetricAuth

Returns:

A negotiation of an authenticated Session with a YubiHSM.

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

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

Encode and send a command byte and its associated data.

Parameters:

  • cmd (COMMAND) – The command to send.

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

Return type:

bytes

Returns:

The response data from the YubiHSM.

yubihsm.defs module

Named constants used in YubiHSM commands.

class yubihsm.defs.ALGORITHM(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Various algorithm constants

AES128 = 50
AES128_CCM_WRAP = 29
AES128_YUBICO_AUTHENTICATION = 38
AES128_YUBICO_OTP = 37
AES192 = 51
AES192_CCM_WRAP = 41
AES192_YUBICO_OTP = 39
AES256 = 52
AES256_CCM_WRAP = 42
AES256_YUBICO_OTP = 40
AES_CBC = 54
AES_ECB = 53
AES_KWP = 55
EC_BP256 = 16
EC_BP384 = 17
EC_BP512 = 18
EC_ECDH = 24
EC_ECDSA_SHA1 = 23
EC_ECDSA_SHA256 = 43
EC_ECDSA_SHA384 = 44
EC_ECDSA_SHA512 = 45
EC_ED25519 = 46
EC_K256 = 15
EC_P224 = 47
EC_P256 = 12
EC_P256_YUBICO_AUTHENTICATION = 49
EC_P384 = 13
EC_P521 = 14
HMAC_SHA1 = 19
HMAC_SHA256 = 20
HMAC_SHA384 = 21
HMAC_SHA512 = 22
OPAQUE_DATA = 30
OPAQUE_X509_CERTIFICATE = 31
RSA_2048 = 9
RSA_3072 = 10
RSA_4096 = 11
RSA_MGF1_SHA1 = 32
RSA_MGF1_SHA256 = 33
RSA_MGF1_SHA384 = 34
RSA_MGF1_SHA512 = 35
RSA_OAEP_SHA1 = 25
RSA_OAEP_SHA256 = 26
RSA_OAEP_SHA384 = 27
RSA_OAEP_SHA512 = 28
RSA_PKCS1_DECRYPT = 48
RSA_PKCS1_SHA1 = 1
RSA_PKCS1_SHA256 = 2
RSA_PKCS1_SHA384 = 3
RSA_PKCS1_SHA512 = 4
RSA_PSS_SHA1 = 5
RSA_PSS_SHA256 = 6
RSA_PSS_SHA384 = 7
RSA_PSS_SHA512 = 8
TEMPLATE_SSH = 36
static for_curve(curve)[source]

Returns a member corresponding to a Cryptography curve instance.

Example:

Return type:

ALGORITHM

>>> ALGORITHM.for_curve(ec.SECP256R1()) == ALGORITHM.EC_P256
True
to_curve()[source]

Return a Cryptography EC curve instance for a given member.

Returns:

The corresponding curve.

Return type:

cryptography.hazmat.primitives.ec.

Example:

>>> isinstance(ALGORITHM.EC_P256.to_curve(), ec.SECP256R1)
True
to_hash_algorithm()[source]

Return the cryptography hash algorithm object corresponding to the algorithm.

:return The corresponding cryptography hash algorithm object.

Example:

Return type:

HashAlgorithm

>>> ALGORITHM.HMAC_SHA1.to_hash_algorithm()
hashes.SHA1
to_key_size()[source]

Return the expected size (in bytes) of a key corresponding to an algorithm.

Return type:

int

Returns:

The corresponding key size (in bytes) to an algorithm.

Example:

>>> ALGORITHM.AES128.to_key_size()
16
class yubihsm.defs.AUDIT(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Values for audit options

FIXED = 2
OFF = 0
ON = 1
class yubihsm.defs.CAPABILITY(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntFlag

YubiHSM object capability flags

ALL = 72057594037927935[source]
CHANGE_AUTHENTICATION_KEY = 70368744177664
CREATE_OTP_AEAD = 1073741824
DECRYPT_CBC = 4503599627370496
DECRYPT_ECB = 1125899906842624
DECRYPT_OAEP = 1024
DECRYPT_OTP = 536870912
DECRYPT_PKCS = 512
DELETE_ASYMMETRIC_KEY = 2199023255552
DELETE_AUTHENTICATION_KEY = 1099511627776
DELETE_HMAC_KEY = 8796093022208
DELETE_OPAQUE = 549755813888
DELETE_OTP_AEAD_KEY = 35184372088832
DELETE_SYMMETRIC_KEY = 562949953421312
DELETE_TEMPLATE = 17592186044416
DELETE_WRAP_KEY = 4398046511104
DERIVE_ECDH = 2048
ENCRYPT_CBC = 9007199254740992
ENCRYPT_ECB = 2251799813685248
EXPORTABLE_UNDER_WRAP = 65536
EXPORT_WRAPPED = 4096
GENERATE_ASYMMETRIC_KEY = 16
GENERATE_HMAC_KEY = 2097152
GENERATE_OTP_AEAD_KEY = 68719476736
GENERATE_SYMMETRIC_KEY = 281474976710656
GENERATE_WRAP_KEY = 32768
GET_LOG_ENTRIES = 16777216
GET_OPAQUE = 1
GET_OPTION = 262144
GET_PSEUDO_RANDOM = 524288
GET_TEMPLATE = 67108864
IMPORT_WRAPPED = 8192
NONE = 0[source]
PUBLIC_WRAP_KEY_DELETE = 36028797018963968
PUBLIC_WRAP_KEY_WRITE = 18014398509481984
PUT_ASYMMETRIC = 8
PUT_AUTHENTICATION_KEY = 4
PUT_HMAC_KEY = 1048576
PUT_OPAQUE = 2
PUT_OTP_AEAD_KEY = 34359738368
PUT_SYMMETRIC_KEY = 140737488355328
PUT_TEMPLATE = 134217728
PUT_WRAP_KEY = 16384
RANDOMIZE_OTP_AEAD = 2147483648
RESET_DEVICE = 268435456
REWRAP_FROM_OTP_AEAD_KEY = 4294967296
REWRAP_TO_OTP_AEAD_KEY = 8589934592
SET_OPTION = 131072
SIGN_ATTESTATION_CERTIFICATE = 17179869184
SIGN_ECDSA = 128
SIGN_EDDSA = 256
SIGN_HMAC = 4194304
SIGN_PKCS = 32
SIGN_PSS = 64
SIGN_SSH_CERTIFICATE = 33554432
UNWRAP_DATA = 274877906944
VERIFY_HMAC = 8388608
WRAP_DATA = 137438953472
class yubihsm.defs.COMMAND(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Commands available to send to the YubiHSM

AUTHENTICATE_SESSION = 4
CHANGE_AUTHENTICATION_KEY = 108
CLOSE_SESSION = 64
CREATE_OTP_AEAD = 97
CREATE_SESSION = 3
DECRYPT_CBC = 113
DECRYPT_ECB = 111
DECRYPT_OAEP = 89
DECRYPT_OTP = 96
DECRYPT_PKCS1 = 73
DELETE_OBJECT = 88
DERIVE_ECDH = 87
DEVICE_INFO = 6
ECHO = 1
ENCRYPT_CBC = 114
ENCRYPT_ECB = 112
ERROR = 127
EXPORT_WRAPPED = 74
EXPORT_WRAPPED_RSA = 118
GENERATE_ASYMMETRIC_KEY = 70
GENERATE_HMAC_KEY = 90
GENERATE_OTP_AEAD_KEY = 102
GENERATE_SYMMETRIC_KEY = 110
GENERATE_WRAP_KEY = 91
GET_DEVICE_PUBLIC_KEY = 10
GET_LOG_ENTRIES = 77
GET_OBJECT_INFO = 78
GET_OPAQUE = 67
GET_OPTION = 80
GET_PSEUDO_RANDOM = 81
GET_PUBLIC_KEY = 84
GET_STORAGE_INFO = 65
GET_TEMPLATE = 95
IMPORT_WRAPPED = 75
IMPORT_WRAPPED_RSA = 119
LIST_OBJECTS = 72
PUT_ASYMMETRIC_KEY = 69
PUT_AUTHENTICATION_KEY = 68
PUT_HMAC_KEY = 82
PUT_OPAQUE = 66
PUT_OTP_AEAD_KEY = 101
PUT_PUBLIC_WRAP_KEY = 115
PUT_SYMMETRIC_KEY = 109
PUT_TEMPLATE = 94
PUT_WRAP_KEY = 76
RANDOMIZE_OTP_AEAD = 98
RESET_DEVICE = 8
REWRAP_OTP_AEAD = 99
SESSION_MESSAGE = 5
SET_LOG_INDEX = 103
SET_OPTION = 79
SIGN_ATTESTATION_CERTIFICATE = 100
SIGN_ECDSA = 86
SIGN_EDDSA = 106
SIGN_HMAC = 83
SIGN_PKCS1 = 71
SIGN_PSS = 85
SIGN_SSH_CERTIFICATE = 93
UNWRAP_DATA = 105
UNWRAP_KEY_RSA = 117
VERIFY_HMAC = 92
WRAP_DATA = 104
WRAP_KEY_RSA = 116
class yubihsm.defs.ERROR(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Error codes returned by the YubiHSM

ALGORITHM_DISABLED = 18
AUTHENTICATION_FAILED = 4
COMMAND_UNEXECUTED = 255
DEMO_MODE = 16
INSUFFICIENT_PERMISSIONS = 9
INVALID_COMMAND = 1
INVALID_DATA = 2
INVALID_ID = 12
INVALID_OTP = 15
INVALID_SESSION = 3
LOG_FULL = 10
OBJECT_EXISTS = 17
OBJECT_NOT_FOUND = 11
OK = 0
SESSIONS_FULL = 5
SESSION_FAILED = 6
SSH_CA_CONSTRAINT_VIOLATION = 14
STORAGE_FAILED = 7
WRONG_LENGTH = 8
class yubihsm.defs.FIPS_STATUS(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Values for FIPS status

OFF = 0
ON = 1
PENDING = 3
class yubihsm.defs.LIST_FILTER(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Keys for use to filter on in list_objects

ALGORITHM = 5
CAPABILITIES = 4
DOMAINS = 3
ID = 1
LABEL = 6
TYPE = 2
class yubihsm.defs.OBJECT(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

YubiHSM object types

ASYMMETRIC_KEY = 3
AUTHENTICATION_KEY = 2
HMAC_KEY = 5
OPAQUE = 1
OTP_AEAD_KEY = 7
PUBLIC_WRAP_KEY = 9
SYMMETRIC_KEY = 8
TEMPLATE = 6
WRAP_KEY = 4
class yubihsm.defs.OPTION(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

YubiHSM device options

ALGORITHM_TOGGLE = 4
COMMAND_AUDIT = 3
FIPS_MODE = 5
FORCE_AUDIT = 1
class yubihsm.defs.ORIGIN(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntFlag

GENERATED = 1
IMPORTED = 2
IMPORTED_WRAPPED = 16

yubihsm.exceptions module

Exceptions thrown by this library.

exception yubihsm.exceptions.YubiHsmAuthenticationError[source]

Bases: YubiHsmError

Authentication failed.

exception yubihsm.exceptions.YubiHsmConnectionError[source]

Bases: YubiHsmError

The connection to the YubiHSM failed.

exception yubihsm.exceptions.YubiHsmDeviceError(code)[source]

Bases: YubiHsmError

The YubiHSM returned an error code.

Parameters:

code (int) – The device error code.

exception yubihsm.exceptions.YubiHsmError[source]

Bases: Exception

Baseclass for YubiHSM errors.

exception yubihsm.exceptions.YubiHsmInvalidRequestError[source]

Bases: YubiHsmError

The request was not able to be sent to the YubiHSM.

exception yubihsm.exceptions.YubiHsmInvalidResponseError[source]

Bases: YubiHsmError

The YubiHSM returned an unexpected response.

yubihsm.objects module

Classes for interacting with objects on a YubiHSM.

class yubihsm.objects.AsymmetricKey(session, object_id, seq=None)[source]

Bases: YhsmObject

Used to sign/decrypt data with the private key of an asymmetric key pair.

Supported algorithms:
attest(attesting_key_id=0)[source]

Attest this asymmetric key.

Creates an X509 certificate containing this key pair’s public key, signed by the asymmetric key identified by the given ID. You also need a X509 certificate stored with the same ID as the attesting key in the YubiHSM, to be used as a template.

Parameters:

attesting_key_id (int) – (optional) The ID of the asymmetric key used to attest. If omitted, the built-in Yubico attestation key is used.

Return type:

Certificate

Returns:

The attestation certificate.

decrypt_oaep(data, label=b'', hash=<cryptography.hazmat.primitives.hashes.SHA256 object>, mgf_hash=<cryptography.hazmat.primitives.hashes.SHA256 object>)[source]

Decrypt data encrypted with RSAES-OAEP.

Parameters:

  • data (bytes) – The ciphertext to decrypt.

  • label (bytes) – (optional) OAEP label.

  • hash (HashAlgorithm) – (optional) The algorithm to use when hashing the data.

  • mgf_hash (HashAlgorithm) – (optional) The algorithm to use for MGF1.

Return type:

bytes

Returns:

The decrypted plaintext.

decrypt_pkcs1v1_5(data)[source]

Decrypt data encrypted with RSAES-PKCS1-v1_5.

Parameters:

data (bytes) – The ciphertext to decrypt.

Return type:

bytes

Returns:

The decrypted plaintext.

derive_ecdh(public_key)[source]

Perform an ECDH key exchange as specified in SP 800-56A.

Parameters:

public_key (EllipticCurvePublicKey) – The public key to use for the key exchange.

Return type:

bytes

Returns:

The resulting shared key.

classmethod generate(session, object_id, label, domains, capabilities, algorithm)[source]

Generate a new private key in the YubiHSM.

Parameters:

  • session (AuthSession) – The session to import via.

  • object_id (int) – The ID to set for the object. Set to 0 to let the YubiHSM designate an ID.

  • label (str) – A text label to give the object.

  • domains (int) – The set of domains to assign the object to.

  • capabilities (CAPABILITY) – The set of capabilities to give the object.

  • algorithm (ALGORITHM) – The algorithm to use for the private key.

Return type:

AsymmetricKey

Returns:

A reference to the newly created object.

get_certificate()[source]

Get the X509 certificate associated with the key.

An X509 certificate is associated with an asymmetric key if it is stored as an Opaque object with the same object ID as the key, and it has the OPAQUE_X509_CERTIFICATE algorithm set.

Equivalent to calling Opaque(session, key_id).get_certificate().

Return type:

Certificate

Returns:

The certificate stored for the object.

get_public_key()[source]

Get the public key of the key pair.

This will return either a RSAPublicKey or a EllipticCurvePublicKey depending on the algorithm of the key.

Ed25519 keys will be returned as a Cryptography Ed25519PublicKey object if possible (requires Cryptography 2.6 or later), or an internal representation if not, either which can be serialized using the serialize_ed25519_public_key() function.

Returns:

The public key of the key pair.

object_type: ClassVar[OBJECT] = 3
classmethod put(session, object_id, label, domains, capabilities, key)[source]

Import a private key into the YubiHSM.

RSA and EC keys can be created by using the cryptography APIs. You can then pass either a RSAPrivateKey , a EllipticCurvePrivateKey , or a Ed25519PrivateKey as key.

Parameters:

  • session (AuthSession) – The session to import via.

  • object_id (int) – The ID to set for the object. Set to 0 to let the YubiHSM designate an ID.

  • label (str) – A text label to give the object.

  • domains (int) – The set of domains to assign the object to.

  • capabilities (CAPABILITY) – The set of capabilities to give the object.

  • key – The private key to import.

Return type:

AsymmetricKey

Returns:

A reference to the newly created object.

put_certificate(label, domains, capabilities, certificate)[source]

Store an X509 certificate associated with this key.

Equivalent to calling Opaque.put_certificate(session, key_id, …).

Parameters:

  • label (str) – A text label to give the object.

  • domains (int) – The set of domains to assign the object to.

  • capabilities (CAPABILITY) – The set of capabilities to give the object.

  • certificate (Certificate) – A certificate to import.

Return type:

Opaque

Returns:

A reference to the newly created object.

sign_ecdsa(data, hash=<cryptography.hazmat.primitives.hashes.SHA256 object>, length=0)[source]

Sign data using ECDSA.

Parameters:

  • data (bytes) – The data to sign.

  • hash (HashAlgorithm) – (optional) The algorithm to use when hashing the data.

  • length (int) – (optional) length to pad/truncate the hash to.

Return type:

bytes

Returns:

The resulting signature.

sign_eddsa(data)[source]

Sign data using EdDSA.

Parameters:

data (bytes) – The data to sign.

Return type:

bytes

Returns:

The resulting signature.

sign_pkcs1v1_5(data, hash=<cryptography.hazmat.primitives.hashes.SHA256 object>)[source]

Sign data using RSASSA-PKCS1-v1_5.

Parameters:

  • data (bytes) – The data to sign.

  • hash (HashAlgorithm) – (optional) The algorithm to use when hashing the data.

Return type:

bytes

Returns:

The resulting signature.

sign_pss(data, salt_len, hash=<cryptography.hazmat.primitives.hashes.SHA256 object>, mgf_hash=<cryptography.hazmat.primitives.hashes.SHA256 object>)[source]

Sign data using RSASSA-PSS with MGF1.

Parameters:

  • data (bytes) – The data to sign.

  • salt_len (int) – The length of the salt to use.

  • hash (HashAlgorithm) – (optional) The algorithm to use when hashing the data.

  • mgf_hash (HashAlgorithm) – (optional) The algorithm to use for MGF1.

Return type:

bytes

Returns:

The resulting signature.

sign_ssh_certificate(template_id, request, algorithm=ALGORITHM.RSA_PKCS1_SHA1)[source]

Sign an SSH certificate request.

Parameters:

  • template_id (int) – The ID of the SSH TEMPLATE to use.

  • request (bytes) – The SSH certificate request.

Return type:

bytes

Returns:

The SSH certificate signature.

class yubihsm.objects.AuthenticationKey(session, object_id, seq=None)[source]

Bases: YhsmObject

Used to authenticate a session with the YubiHSM.

AuthenticationKeys use two separate keys to mutually authenticate and set up a secure session with a YubiHSM. These two keys can either be given explicitly, or be derived from a password.

change_key(key_enc, key_mac)[source]

Change the raw keys used to authenticate a session.

Parameters:

  • key_enc (bytes) – The raw encryption key.

  • key_mac (bytes) – The raw MAC key.

Return type:

None

change_password(password)[source]

Change the password used to authenticate a session.

Changes the raw keys used for authentication, by deriving them from a password.

Parameters:

password (str) – The password to derive raw keys from.

Return type:

None

change_public_key(public_key)[source]

Change an asymmetric AuthenticationKey’s public key

Parameters:

public_key (EllipticCurvePublicKey) – The new public key.

Return type:

None

object_type: ClassVar[OBJECT] = 2
classmethod put(session, object_id, label, domains, capabilities, delegated_capabilities, key_enc, key_mac)[source]

Create an AuthenticationKey by providing raw keys.

Parameters:

  • session (AuthSession) – The session to import via.

  • object_id (int) – The ID to set for the object. Set to 0 to let the YubiHSM designate an ID.

  • label (str) – A text label to give the object.

  • domains (int) – The set of domains to assign the object to.

  • capabilities (CAPABILITY) – The set of capabilities to give the object.

  • delegated_capabilities (CAPABILITY) – The set of capabilities that the AuthenticationKey can give to objects created when authenticated using it.

  • key_enc (bytes) – The raw encryption key.

  • key_mac (bytes) – The raw MAC key.

Return type:

AuthenticationKey

Returns:

A reference to the newly created object.

classmethod put_derived(session, object_id, label, domains, capabilities, delegated_capabilities, password)[source]

Create an AuthenticationKey derived from a password.

Parameters:

  • session (AuthSession) – The session to import via.

  • object_id (int) – The ID to set for the object. Set to 0 to let the YubiHSM designate an ID.

  • label (str) – A text label to give the object.

  • domains (int) – The set of domains to assign the object to.

  • capabilities (CAPABILITY) – The set of capabilities to give the object.

  • delegated_capabilities (CAPABILITY) – The set of capabilities that the AuthenticationKey can give to objects created when authenticated using it.

  • password (str) – The password to derive raw keys from.

Return type:

AuthenticationKey

Returns:

A reference to the newly created object.

classmethod put_public_key(session, object_id, label, domains, capabilities, delegated_capabilities, public_key)[source]

Create an asymmetric AuthenticationKey by providing a public key

Parameters:

  • session (AuthSession) – The session to import via.

  • object_id (int) – The ID to set for the object. Set to 0 to let the YubiHSM designate an ID.

  • label (str) – A text label to give the object.

  • domains (int) – The set of domains to assign the object to.

  • capabilities (CAPABILITY) – The set of capabilities to give the object.

  • delegated_capabilities (CAPABILITY) – The set of capabilities that the AuthenticationKey can give to objects created when authenticated using it.

  • public_key (EllipticCurvePublicKey) – The public key to import.

Return type:

AuthenticationKey

Returns:

A reference to the newly created object.

class yubihsm.objects.HmacKey(session, object_id, seq=None)[source]

Bases: YhsmObject

Used to calculate and verify HMAC signatures.

Supported algorithms:
classmethod generate(session, object_id, label, domains, capabilities, algorithm=ALGORITHM.HMAC_SHA256)[source]

Generate a new HMAC key in the YubiHSM.

Parameters:

  • session (AuthSession) – The session to import via.

  • object_id (int) – The ID to set for the object. Set to 0 to let the YubiHSM designate an ID.

  • label (str) – A text label to give the object.

  • domains (int) – The set of domains to assign the object to.

  • capabilities (CAPABILITY) – The set of capabilities to give the object.

  • algorithm (ALGORITHM) – (optional) The algorithm to use for the HMAC key.

Return type:

HmacKey

Returns:

A reference to the newly created object.

object_type: ClassVar[OBJECT] = 5
classmethod put(session, object_id, label, domains, capabilities, key, algorithm=ALGORITHM.HMAC_SHA256)[source]

Import an HMAC key into the YubiHSM.

Parameters:

  • session (AuthSession) – The session to import via.

  • object_id (int) – The ID to set for the object. Set to 0 to let the YubiHSM designate an ID.

  • label (str) – A text label to give the object.

  • domains (int) – The set of domains to assign the object to.

  • capabilities (CAPABILITY) – The set of capabilities to give the object.

  • key (bytes) – The raw key corresponding to the algorithm.

  • algorithm – (optional) The algorithm to use for the HMAC key.

Return type:

HmacKey

Returns:

A reference to the newly created object.

sign_hmac(data)[source]

Calculate the HMAC signature of the given data.

Parameters:

data (bytes) – The data to sign.

Return type:

bytes

Returns:

The signature.

verify_hmac(signature, data)[source]

Verify an HMAC signature.

Parameters:

  • signature (bytes) – The signature to verify.

  • data (bytes) – The data to verify the signature against.

Return type:

bool

Returns:

True if verification succeeded, False if not.

class yubihsm.objects.ObjectInfo(capabilities, id, size, domains, object_type, algorithm, sequence, origin, label, delegated_capabilities)[source]

Bases: object

Data structure holding various information about an object.

Variables:

  • capabilities – The capabilities of the object.

  • id – The ID of the object.

  • size – The size of the object.

  • domains – The set of domains the object belongs to.

  • object_type – The type of the object.

  • algorithm – The algorithm of the object.

  • sequence – The sequence number of the object.

  • origin – How the object was created/imported.

  • label – The label of the object.

  • delegated_capabilities – The set of delegated capabilities for the object.

FORMAT: ClassVar[str] = '!QHHHBBBB40sQ'
LENGTH: ClassVar[int] = 66
algorithm: ALGORITHM
capabilities: CAPABILITY
delegated_capabilities: CAPABILITY
domains: int
id: int
label: Union[str, bytes]
object_type: OBJECT
origin: ORIGIN
classmethod parse(value)[source]

Parse an ObjectInfo from its binary representation.

Return type:

ObjectInfo

sequence: int
size: int
class yubihsm.objects.Opaque(session, object_id, seq=None)[source]

Bases: YhsmObject

Object used to store arbitrary data on the YubiHSM.

Supported algorithms:
get()[source]

Read the data of an Opaque object from the YubiHSM.

Return type:

bytes

Returns:

The data stored for the object.

get_certificate()[source]

Read an Opaque object from the YubiHSM, parsed as a certificate.

Return type:

Certificate

Returns:

The certificate stored for the object.

object_type: ClassVar[OBJECT] = 1
classmethod put(session, object_id, label, domains, capabilities, algorithm, data)[source]

Import an Opaque object into the YubiHSM.

Parameters:

  • session (AuthSession) – The session to import via.

  • object_id (int) – The ID to set for the object. Set to 0 to let the YubiHSM designate an ID.

  • label (str) – A text label to give the object.

  • domains (int) – The set of domains to assign the object to.

  • capabilities (CAPABILITY) – The set of capabilities to give the object.

  • algorithm (ALGORITHM) – The algorithm to use for the object.

  • data (bytes) – The binary data to store.

Return type:

Opaque

Returns:

A reference to the newly created object.

classmethod put_certificate(session, object_id, label, domains, capabilities, certificate)[source]

Import an X509 certificate into the YubiHSM as an Opaque.

Parameters:

  • session (AuthSession) – The session to import via.

  • object_id (int) – The ID to set for the object. Set to 0 to let the YubiHSM designate an ID.

  • label (str) – A text label to give the object.

  • domains (int) – The set of domains to assign the object to.

  • capabilities (CAPABILITY) – The set of capabilities to give the object.

  • certificate (Certificate) – A certificate to import.

Return type:

Opaque

Returns:

A reference to the newly created object.

class yubihsm.objects.OtpAeadKey(session, object_id, seq=None)[source]

Bases: YhsmObject

Used to decrypt and use a Yubico OTP AEAD for OTP decryption.

Supported algorithms:
create_otp_aead(key, identity)[source]

Create a new Yubico OTP credential AEAD.

Parameters:

  • key (bytes) – 16 byte AES key for the credential.

  • identity (bytes) – 6 byte private ID for the credential.

Return type:

bytes

Returns:

A new AEAD.

decrypt_otp(aead, otp)[source]

Decrypt a Yubico OTP using an AEAD.

Parameters:

  • aead (bytes) – The AEAD containing encrypted credential data.

  • otp (bytes) – The 16 byte encrypted OTP payload to decrypt.

Return type:

OtpData

Returns:

The decrypted OTP data.

classmethod generate(session, object_id, label, domains, capabilities, algorithm, nonce_id)[source]

Generate a new OTP AEAD key in the YubiHSM.

Parameters:

  • session (AuthSession) – The session to import via.

  • object_id (int) – The ID to set for the object. Set to 0 to let the YubiHSM designate an ID.

  • label (str) – A text label to give the object.

  • domains (int) – The set of domains to assign the object to.

  • capabilities (CAPABILITY) – The set of capabilities to give the object.

  • algorithm (ALGORITHM) – The algorithm to use for the key.

  • nonce_id (int) – The nonce ID used for AEADs.

Return type:

OtpAeadKey

Returns:

A reference to the newly created object.

object_type: ClassVar[OBJECT] = 7
classmethod put(session, object_id, label, domains, capabilities, algorithm, nonce_id, key)[source]

Import an OTP AEAD key into the YubiHSM.

Parameters:

  • session (AuthSession) – The session to import via.

  • object_id (int) – The ID to set for the object. Set to 0 to let the YubiHSM designate an ID.

  • label (str) – A text label to give the object.

  • domains (int) – The set of domains to assign the object to.

  • capabilities (CAPABILITY) – The set of capabilities to give the object.

  • algorithm (ALGORITHM) – The algorithm to use for the key.

  • nonce_id (int) – The nonce ID used for AEADs.

  • key (bytes) – The key to import, corresponding to the algorithm.

Return type:

OtpAeadKey

Returns:

A reference to the newly created object.

randomize_otp_aead()[source]

Create a new Yubico OTP credential AEAD using random data.

Return type:

bytes

Returns:

A new AEAD.

rewrap_otp_aead(new_key_id, aead)[source]

Decrypt and re-encrypt an AEAD from one key to another.

Parameters:

  • new_key_id (int) – The ID of the OtpAeadKey to wrap to.

  • aead (bytes) – The AEAD to re-wrap.

Return type:

bytes

Returns:

The new AEAD.

class yubihsm.objects.OtpData(use_counter: int, session_counter: int, timestamp_high: int, timestamp_low: int)[source]

Bases: NamedTuple

Decrypted OTP counter values.

Parameters:

  • use_counter – 16 bit counter incremented on each power cycle.

  • session_counter – 8 bit counter incremented on each touch.

  • timestamp_high – 8 bit high part of the timestamp.

  • timestamp_low – 16 bit low part of the timestamp.

session_counter: int

Alias for field number 1

timestamp_high: int

Alias for field number 2

timestamp_low: int

Alias for field number 3

use_counter: int

Alias for field number 0

class yubihsm.objects.PublicWrapKey(session, object_id, seq=None)[source]

Bases: YhsmObject

Used to export other objects under wrap using the public key of an asymmetric key pair.

The algorithm used for wrapping is CKM_RSA_AES_KEY_WRAP, as specified in PKCS#11.

Supported algorithms: - RSA_2048 - RSA_3072 - RSA_4096

export_raw_key(key, algorithm=ALGORITHM.AES256, oaep_hash=<cryptography.hazmat.primitives.hashes.SHA256 object>, mgf_hash=<cryptography.hazmat.primitives.hashes.SHA256 object>, oaep_label=b'')[source]

Export an (a)symmetric key object under asymmetric wrap.

This command wraps only the raw key material of the key object. Asymmetric keys are serialized as PKCS#8.

Parameters:

  • key (Union[AsymmetricKey, SymmetricKey]) – The (a)symmetric key object to wrap.

  • algorithm (ALGORITHM) – (optional) The algorithm for the ephemeral key.

  • oaep_hash (HashAlgorithm) – (optional) The hash algorithm to use for OAEP label.

  • mgf_hash (HashAlgorithm) – (optional) The hash algorithm to use for MGF1.

  • oaep_label (bytes) – (optional) OAEP label.

Return type:

bytes

Returns:

The encrypted key.

export_wrapped_rsa(obj, algorithm=ALGORITHM.AES256, oaep_hash=<cryptography.hazmat.primitives.hashes.SHA256 object>, mgf_hash=<cryptography.hazmat.primitives.hashes.SHA256 object>, oaep_label=b'')[source]

Export an object under asymmetric wrap.

Parameters:

  • obj (YhsmObject) – The object to export.

  • algorithm (ALGORITHM) – (optional) The algorithm to use for the ephemeral key.

  • oaep_hash (HashAlgorithm) – (optional) The hash algorithm to use for OAEP label.

  • mgf_hash (HashAlgorithm) – (optional) The hash algorithm to use for MGF1.

  • oaep_label (bytes) – (optional) OAEP label.

Return type:

bytes

Returns:

The encrypted object data.

object_type: ClassVar[OBJECT] = 9
classmethod put(session, object_id, label, domains, capabilities, delegated_capabilities, public_key)[source]

Import a public RSA wrapkey into the YubiHSM.

The RSA public key can be supplied using the cryptography API. You can then pass a RSAPublicKey as public_key.

Parameters:

  • session (AuthSession) – The session to import via.

  • object_id (int) – The ID to set for the object. Set to 0 to let the YubiHSM designate an ID.

  • label (str) – A text label to give the object.

  • domains (int) – The set of domains to assign the object to.

  • capabilities (CAPABILITY) – The set of capabilities to give the object.

  • delegated_capabilities (CAPABILITY) – The set of capabilities that the WrapKey can give to objects that it imports.

  • public_key (RSAPublicKey) – The public key to import.

Return type:

PublicWrapKey

Returns:

A reference to the newly created object.

class yubihsm.objects.SymmetricKey(session, object_id, seq=None)[source]

Bases: YhsmObject

Used to encrypt/decrypt data using a symmetric key.

Supported algorithms:
decrypt_cbc(iv, data)[source]

Decrypt data in CBC mode.

Parameters:

  • iv (bytes) – The initialization vector.

  • data (bytes) – The data to decrypt.

Return type:

bytes

Returns:

The decrypted data.

decrypt_ecb(data)[source]

Decrypt data in ECB mode.

Parameters:

data (bytes) – The data to decrypt.

Return type:

bytes

Returns:

The decrypted data.

encrypt_cbc(iv, data)[source]

Encrypt data in CBC mode.

Parameters:

  • iv (bytes) – The initialization vector.

  • data (bytes) – The data to encrypt.

Return type:

bytes

Returns:

The encrypted data.

encrypt_ecb(data)[source]

Encrypt data in ECB mode.

Parameters:

data (bytes) – The data to encrypt.

Return type:

bytes

Returns:

The encrypted data.

classmethod generate(session, object_id, label, domains, capabilities, algorithm)[source]

Generate a new symmetric key in the YubiHSM.

Parameters:

  • session (AuthSession) – The session to import via.

  • object_id (int) – The ID to set for the object. Set to 0 to let the YubiHSM designate an ID.

  • label (str) – A text label to give the object.

  • domains (int) – The set of domains to assign the object to.

  • capabilities (CAPABILITY) – The set of capabilities to give the object.

  • algorithm (ALGORITHM) – The algorithm to use for the symmetric key.

Return type:

SymmetricKey

Returns:

A reference to the newly created object.

object_type: ClassVar[OBJECT] = 8
classmethod put(session, object_id, label, domains, capabilities, algorithm, key)[source]

Import a symmetric key into the YubiHSM.

Parameters:

  • session (AuthSession) – The session to import via.

  • object_id (int) – The ID to set for the object. Set to 0 to let the YubiHSM designate an ID.

  • label (str) – A text label to give the object.

  • domains (int) – The set of domains to assign the object to.

  • capabilities (CAPABILITY) – The set of capabilities to give the object.

  • algorithm (ALGORITHM) – The algorithm to use for the symmetric key.

  • key (bytes) – The raw encryption key corresponding to the algorithm.

Return type:

SymmetricKey

Returns:

A reference to the newly created object.

class yubihsm.objects.Template(session, object_id, seq=None)[source]

Bases: YhsmObject

Binary template used to validate SSH certificate requests.

Supported algorithms:
get()[source]

Read a Template from the YubiHSM.

Return type:

bytes

Returns:

The template data.

object_type: ClassVar[OBJECT] = 6
classmethod put(session, object_id, label, domains, capabilities, algorithm, data)[source]

Import a Template into the YubiHSM.

Parameters:

  • session (AuthSession) – The session to import via.

  • object_id (int) – The ID to set for the object. Set to 0 to let the YubiHSM designate an ID.

  • label (str) – A text label to give the object.

  • domains (int) – The set of domains to assign the object to.

  • capabilities (CAPABILITY) – The set of capabilities to give the object.

  • algorithm (ALGORITHM) – The algorithm to use for the template.

  • data (bytes) – The template data.

Return type:

Template

Returns:

A reference to the newly created object.

class yubihsm.objects.WrapKey(session, object_id, seq=None)[source]

Bases: YhsmObject

Used to import and export other objects under wrap.

Asymmetric wrapkeys are only used for importing wrapped objects. To export objects under asymmetric wrap, use PublicWrapKey.

Supported algorithms:
export_wrapped(obj, seed=False)[source]

Export an object under wrap.

Parameters:

  • obj (YhsmObject) – The object to export.

  • seed (bool) – (optional) Export key with seed. Only applicable for ed25519 key objects.

Return type:

bytes

Returns:

The encrypted object data.

classmethod generate(session, object_id, label, domains, capabilities, algorithm, delegated_capabilities)[source]

Generate a new wrap key in the YubiHSM.

Parameters:

  • session (AuthSession) – The session to import via.

  • object_id (int) – The ID to set for the object. Set to 0 to let the YubiHSM designate an ID.

  • label (str) – A text label to give the object.

  • domains (int) – The set of domains to assign the object to.

  • capabilities (CAPABILITY) – The set of capabilities to give the object.

  • algorithm (ALGORITHM) – The algorithm to use for the wrap key.

Return type:

WrapKey

Returns:

A reference to the newly created object.

get_public_key()[source]

Get the public key of the wrapkey pair.

Return type:

RSAPublicKey

import_raw_key(object_id, object_type, label, domains, capabilities, algorithm, wrapped, oaep_hash=<cryptography.hazmat.primitives.hashes.SHA256 object>, mgf_hash=<cryptography.hazmat.primitives.hashes.SHA256 object>, oaep_label=b'')[source]

Import an (a)symmetric key previously exported under asymmetric wrap.

Asymmetric keys are expected to have been serialized as PKCS#8.

Parameters:

  • object_id (int) – The ID to set for the object. Set to 0 to let the YubiHSM designate an ID.

  • object_type (OBJECT) – The key object type (OBJECT.ASYMMETRIC_KEY or OBJECT.SYMMETRIC_KEY).

  • label (str) – A text label to give the object.

  • domains (int) – The set of domains to assign the object to.

  • capabilities (CAPABILITY) – The set of capabilities to give the object.

  • algorithm (ALGORITHM) – The algorithm of the key.

  • wrapped (bytes) – The wrapped key object.

  • oaep_hash (HashAlgorithm) – (optional) The hash algorithm to use for OAEP label.

  • mgf_hash (HashAlgorithm) – (optional) The hash algorithm to use for MGF1.

  • oaep_label (bytes) – (optional) OAEP label.

Return type:

YhsmObject

Returns:

A reference to the imported key object.

import_wrapped(wrapped_obj)[source]

Import an object previously exported under wrap.

Parameters:

wraped_obj – The encrypted object data.

Return type:

YhsmObject

Returns:

A reference to the imported object.

import_wrapped_rsa(wrapped_obj, oaep_hash=<cryptography.hazmat.primitives.hashes.SHA256 object>, mgf_hash=<cryptography.hazmat.primitives.hashes.SHA256 object>, oaep_label=b'')[source]

Import an object previously exported under asymmetric wrap.

Parameters:

  • wrapped_obj (bytes) – The encrypted object data.

  • oaep_hash (HashAlgorithm) – (optional) The hash algorithm to use for OAEP label.

  • mgf_hash (HashAlgorithm) – (optional) The hash algorithm to use for MGF1.

  • oaep_label (bytes) – (optional) OAEP label.

Return type:

YhsmObject

Returns:

A reference to the imported object.

object_type: ClassVar[OBJECT] = 4
classmethod put(session, object_id, label, domains, capabilities, algorithm, delegated_capabilities, key)[source]

Import a wrap key into the YubiHSM.

Asymmetric keys can be imported using the cryptography API. You can then pass a RSAPrivateKey as key.

Parameters:

  • session (AuthSession) – The session to import via.

  • object_id (int) – The ID to set for the object. Set to 0 to let the YubiHSM designate an ID.

  • label (str) – A text label to give the object.

  • domains (int) – The set of domains to assign the object to.

  • capabilities (CAPABILITY) – The set of capabilities to give the object.

  • algorithm (ALGORITHM) – The algorithm to use for the wrap key.

  • delegated_capabilities (CAPABILITY) – The set of capabilities that the WrapKey can give to objects that it imports.

  • key (Union[bytes, RSAPrivateKey]) – The encryption key corresponding to the algorithm.

Return type:

WrapKey

Returns:

A reference to the newly created object.

unwrap_data(data)[source]

Unwrap (decrypt) arbitrary data.

Parameters:

data (bytes) – The encrypted data to decrypt.

Return type:

bytes

Returns:

The decrypted data.

wrap_data(data)[source]

Wrap (encrypt) arbitrary data.

Parameters:

data (bytes) – The data to encrypt.

Return type:

bytes

Returns:

The encrypted data.

class yubihsm.objects.YhsmObject(session, object_id, seq=None)[source]

Bases: object

A reference to an object stored in a YubiHSM.

YubiHSM objects are uniquely identified by their type and ID combined.

Variables:

  • session – The session to use for YubiHSM communication.

  • id – The ID of the object.

  • object_type – The type of the object.

delete()[source]

Delete the object from the YubiHSM. :rtype: None

Warning

This action in irreversible.

get_info()[source]

Read extended information about the object from the YubiHSM.

Return type:

ObjectInfo

Returns:

Information about the object.

object_type: ClassVar[OBJECT]
with_session(session)[source]

Get a copy of the object reference, using the given session.

Parameters:

session (AuthSession) – The session to use for the created reference.

Return type:

TypeVar(T_Object, bound= YhsmObject)

Returns:

A new reference to the object, associated wth the given session.

yubihsm.utils module

Various utility functions used throughout the library.

yubihsm.utils.password_to_key(password)[source]

Derive keys for establishing a YubiHSM session from a password.

Return type:

Tuple[bytes, bytes]

Returns:

A tuple containing the encryption key, and MAC key.

Module contents

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