yubikit.hsmauth

Attributes

TAG_LABEL
TAG_LABEL_LIST
TAG_CREDENTIAL_PASSWORD
TAG_ALGORITHM
TAG_KEY_ENC
TAG_KEY_MAC
TAG_CONTEXT
TAG_RESPONSE
TAG_VERSION
TAG_TOUCH
TAG_MANAGEMENT_KEY
TAG_PUBLIC_KEY
TAG_PRIVATE_KEY
INS_PUT
INS_DELETE
INS_CALCULATE
INS_GET_CHALLENGE
INS_LIST
INS_RESET
INS_GET_VERSION
INS_PUT_MANAGEMENT_KEY
INS_GET_MANAGEMENT_KEY_RETRIES
INS_GET_PUBLIC_KEY
MANAGEMENT_KEY_LEN
CREDENTIAL_PASSWORD_LEN
MIN_LABEL_LEN
MAX_LABEL_LEN
DEFAULT_MANAGEMENT_KEY
INITIAL_RETRY_COUNTER

Classes

ALGORITHM	Algorithms for YubiHSM Auth credentials.
Credential	A YubiHSM Auth credential object.
SessionKeys	YubiHSM Session Keys.
HsmAuthSession	A session with the YubiHSM Auth application.

Module Contents

yubikit.hsmauth.TAG_LABEL = 113

yubikit.hsmauth.TAG_LABEL_LIST = 114

yubikit.hsmauth.TAG_CREDENTIAL_PASSWORD = 115

yubikit.hsmauth.TAG_ALGORITHM = 116

yubikit.hsmauth.TAG_KEY_ENC = 117

yubikit.hsmauth.TAG_KEY_MAC = 118

yubikit.hsmauth.TAG_CONTEXT = 119

yubikit.hsmauth.TAG_RESPONSE = 120

yubikit.hsmauth.TAG_VERSION = 121

yubikit.hsmauth.TAG_TOUCH = 122

yubikit.hsmauth.TAG_MANAGEMENT_KEY = 123

yubikit.hsmauth.TAG_PUBLIC_KEY = 124

yubikit.hsmauth.TAG_PRIVATE_KEY = 125

yubikit.hsmauth.INS_PUT = 1

yubikit.hsmauth.INS_DELETE = 2

yubikit.hsmauth.INS_CALCULATE = 3

yubikit.hsmauth.INS_GET_CHALLENGE = 4

yubikit.hsmauth.INS_LIST = 5

yubikit.hsmauth.INS_RESET = 6

yubikit.hsmauth.INS_GET_VERSION = 7

yubikit.hsmauth.INS_PUT_MANAGEMENT_KEY = 8

yubikit.hsmauth.INS_GET_MANAGEMENT_KEY_RETRIES = 9

yubikit.hsmauth.INS_GET_PUBLIC_KEY = 10

yubikit.hsmauth.MANAGEMENT_KEY_LEN = 16

yubikit.hsmauth.CREDENTIAL_PASSWORD_LEN = 16

yubikit.hsmauth.MIN_LABEL_LEN = 1

yubikit.hsmauth.MAX_LABEL_LEN = 64

yubikit.hsmauth.DEFAULT_MANAGEMENT_KEY = b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'

yubikit.hsmauth.INITIAL_RETRY_COUNTER = 8

class yubikit.hsmauth.ALGORITHM

Bases: enum.IntEnum

Algorithms for YubiHSM Auth credentials.

AES128_YUBICO_AUTHENTICATION = 38

EC_P256_YUBICO_AUTHENTICATION = 39

property key_len: int

Return type:

int

property pubkey_len

class yubikit.hsmauth.Credential

A YubiHSM Auth credential object.

label: str

algorithm: ALGORITHM

counter: int

touch_required: bool | None

__lt__(other)

__eq__(other)

__hash__()

Return type:

int

class yubikit.hsmauth.SessionKeys

Bases: NamedTuple

YubiHSM Session Keys.

key_senc: bytes

key_smac: bytes

key_srmac: bytes

classmethod parse(response)

Parameters:

response (bytes)

Return type:

SessionKeys

class yubikit.hsmauth.HsmAuthSession(connection, scp_key_params=None)

A session with the YubiHSM Auth application.

Parameters:

• connection (yubikit.core.smartcard.SmartCardConnection)

• scp_key_params (Optional[yubikit.core.smartcard.ScpKeyParams])

protocol

property version: yubikit.core.Version

The YubiHSM Auth application version.

Return type:

yubikit.core.Version

reset()

Perform a factory reset on the YubiHSM Auth application.

Return type:

None

list_credentials()

List YubiHSM Auth credentials on YubiKey

Return type:

list[Credential]

put_credential_symmetric(management_key, label, key_enc, key_mac, credential_password, touch_required=False)

Import a symmetric YubiHSM Auth credential.

Parameters:

• management_key (bytes) – The management key.

• label (str) – The label of the credential.

• key_enc (bytes) – The static K-ENC.

• key_mac (bytes) – The static K-MAC.

• credential_password (Union[bytes, str]) – The password used to protect access to the credential.

• touch_required (bool) – The touch requirement policy.

Return type:

Credential

put_credential_derived(management_key, label, derivation_password, credential_password, touch_required=False)

Import a symmetric YubiHSM Auth credential derived from password.

Parameters:

• management_key (bytes) – The management key.

• label (str) – The label of the credential.

• derivation_password (str) – The password used to derive the keys from.

• credential_password (Union[bytes, str]) – The password used to protect access to the credential.

• touch_required (bool) – The touch requirement policy.

Return type:

Credential

put_credential_asymmetric(management_key, label, private_key, credential_password, touch_required=False)

Import an asymmetric YubiHSM Auth credential.

Parameters:

• management_key (bytes) – The management key.

• label (str) – The label of the credential.

• private_key (cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKeyWithSerialization) – Private key corresponding to the public authentication key object on the YubiHSM.

• credential_password (Union[bytes, str]) – The password used to protect access to the credential.

• touch_required (bool) – The touch requirement policy.

Return type:

Credential

generate_credential_asymmetric(management_key, label, credential_password, touch_required=False)

Generate an asymmetric YubiHSM Auth credential.

Generates a private key on the YubiKey, whose corresponding public key can be retrieved using get_public_key.

Parameters:

• management_key (bytes) – The management key.

• label (str) – The label of the credential.

• credential_password (Union[bytes, str]) – The password used to protect access to the credential.

• touch_required (bool) – The touch requirement policy.

Return type:

Credential

get_public_key(label)

Get the public key for an asymmetric credential.

This will return the long-term public key “PK-OCE” for an asymmetric credential.

Parameters:

label (str) – The label of the credential.

Return type:

cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey

delete_credential(management_key, label)

Delete a YubiHSM Auth credential.

Parameters:

• management_key (bytes) – The management key.

• label (str) – The label of the credential.

Return type:

None

put_management_key(management_key, new_management_key)

Change YubiHSM Auth management key

Parameters:

• management_key (bytes) – The current management key.

• new_management_key (bytes) – The new management key.

Return type:

None

get_management_key_retries()

Get retries remaining for Management key

Return type:

int

calculate_session_keys_symmetric(label, context, credential_password, card_crypto=None)

Calculate session keys from a symmetric YubiHSM Auth credential.

Parameters:

• label (str) – The label of the credential.

• context (bytes) – The context (host challenge + hsm challenge).

• credential_password (Union[bytes, str]) – The password used to protect access to the credential.

• card_crypto (Optional[bytes]) – The card cryptogram.

Return type:

SessionKeys

calculate_session_keys_asymmetric(label, context, public_key, credential_password, card_crypto)

Calculate session keys from an asymmetric YubiHSM Auth credential.

Parameters:

• label (str) – The label of the credential.

• context (bytes) – The context (EPK.OCE + EPK.SD).

• public_key (cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey) – The YubiHSM device’s public key.

• credential_password (Union[bytes, str]) – The password used to protect access to the credential.

• card_crypto (bytes) – The card cryptogram.

Return type:

SessionKeys

get_challenge(label, credential_password=None)

Get the Host Challenge.

For symmetric credentials this is Host Challenge, a random 8 byte value. For asymmetric credentials this is EPK-OCE.

Parameters:

• label (str) – The label of the credential.

• credential_password (Union[bytes, str, None]) – The password used to protect access to the credential, needed for asymmetric credentials.

Return type:

bytes