yubihsm.objects

Classes for interacting with objects on a YubiHSM.

Attributes

LABEL_LENGTH

MAX_AES_PAYLOAD_SIZE

AES_BLOCK_SIZE

RSA_PUBLIC_EXPONENT

RSA_SIZES

T_AttestationExtensions

T_Object

Classes

ObjectInfo

Data structure holding various information about an object.

AttestationExtensions

Base attestation extensions.

DeviceAttestationExtensions

Device attestation extensions. Available on YubiHSM FIPS only.

KeyAttestationExtensions

Key attestation extensions.

YhsmObject

A reference to an object stored in a YubiHSM.

Opaque

Object used to store arbitrary data on the YubiHSM.

AuthenticationKey

Used to authenticate a session with the YubiHSM.

AsymmetricKey

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

WrapKey

Used to import and export other objects under wrap.

PublicWrapKey

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

HmacKey

Used to calculate and verify HMAC signatures.

Template

Binary template used to validate SSH certificate requests.

OtpData

Decrypted OTP counter values.

OtpAeadKey

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

SymmetricKey

Used to encrypt/decrypt data using a symmetric key.

Module Contents

yubihsm.objects.LABEL_LENGTH = 40
yubihsm.objects.MAX_AES_PAYLOAD_SIZE = 2026
yubihsm.objects.AES_BLOCK_SIZE = 16
yubihsm.objects.RSA_PUBLIC_EXPONENT = 65537
yubihsm.objects.RSA_SIZES = [2048, 3072, 4096]
class yubihsm.objects.ObjectInfo[source]

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]
capabilities: yubihsm.defs.CAPABILITY
id: int
size: int
domains: int
object_type: yubihsm.defs.OBJECT
algorithm: yubihsm.defs.ALGORITHM
sequence: int
origin: yubihsm.defs.ORIGIN
label: str | bytes
delegated_capabilities: yubihsm.defs.CAPABILITY
classmethod parse(value)[source]

Parse an ObjectInfo from its binary representation.

Parameters:

value (bytes)

Return type:

ObjectInfo

yubihsm.objects.T_AttestationExtensions
class yubihsm.objects.AttestationExtensions[source]

Base attestation extensions.

Variables:

  • firmware_version – YubiHSM firmware version.

  • serial – YubiHSM serial number.

firmware_version: yubihsm.defs.Version
serial: int
classmethod parse(certificate, *args)[source]
Parameters:

certificate (cryptography.x509.Certificate)

Return type:

T_AttestationExtensions

class yubihsm.objects.DeviceAttestationExtensions[source]

Bases: AttestationExtensions

Device attestation extensions. Available on YubiHSM FIPS only.

Variables:

fips_certificate – The FIPS certificate.

fips_certificate: int | None
classmethod parse(certificate, *args)[source]
Parameters:

certificate (cryptography.x509.Certificate)

class yubihsm.objects.KeyAttestationExtensions[source]

Bases: AttestationExtensions

Key attestation extensions.

Variables:

  • origin – The origin of the key.

  • domains – The set of domains assigned to the key object.

  • capabilities – The set of capabilities assigned to the key object.

  • object_id – The ID of the key object.

  • label – The label of the key object.

  • fips_approved – (available on YubiHSM FIPS >= 2.4.1 only) True if the key attestation was generated in FIPS-approved mode.

origin: yubihsm.defs.ORIGIN
domains: int
capabilities: yubihsm.defs.CAPABILITY
object_id: int
label: str | bytes
fips_approved: bool | None
classmethod parse(certificate, *args)[source]

Extracts the attributes from an an attestation certificate.

Parameters:

certificate (cryptography.x509.Certificate)

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

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.

Parameters:
object_type: ClassVar[yubihsm.defs.OBJECT]
session
id: int
with_session(session)[source]

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

Parameters:

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

Returns:

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

Return type:

T_Object

get_info()[source]

Read extended information about the object from the YubiHSM.

Returns:

Information about the object.

Return type:

ObjectInfo

delete()[source]

Delete the object from the YubiHSM.

Warning

This action in irreversible.

Return type:

None

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

Bases: YhsmObject

Object used to store arbitrary data on the YubiHSM.

Supported algorithms:
Parameters:
object_type
classmethod put(session, object_id, label, domains, capabilities, algorithm, data)[source]

Import an Opaque object into the YubiHSM.

Parameters:

  • session (yubihsm.core.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 (yubihsm.defs.CAPABILITY) – The set of capabilities to give the object.

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

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

Returns:

A reference to the newly created object.

Return type:

Opaque

get()[source]

Read the data of an Opaque object from the YubiHSM.

Returns:

The data stored for the object.

Return type:

bytes

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

Import an X509 certificate into the YubiHSM as an Opaque.

Parameters:

  • session (yubihsm.core.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 (yubihsm.defs.CAPABILITY) – The set of capabilities to give the object.

  • certificate (cryptography.x509.Certificate) – A certificate to import.

  • compress (bool) – (optional) Compress the certificate.

Returns:

A reference to the newly created object.

Return type:

Opaque

get_certificate()[source]

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

Returns:

The certificate stored for the object.

Return type:

cryptography.x509.Certificate

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.

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

Create an AuthenticationKey derived from a password.

Parameters:

  • session (yubihsm.core.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 (yubihsm.defs.CAPABILITY) – The set of capabilities to give the object.

  • delegated_capabilities (yubihsm.defs.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.

Returns:

A reference to the newly created object.

Return type:

AuthenticationKey

classmethod put(session, object_id, label, domains, capabilities, delegated_capabilities, key_enc, key_mac)[source]

Create an AuthenticationKey by providing raw keys.

Parameters:

  • session (yubihsm.core.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 (yubihsm.defs.CAPABILITY) – The set of capabilities to give the object.

  • delegated_capabilities (yubihsm.defs.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.

Returns:

A reference to the newly created object.

Return type:

AuthenticationKey

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:
Returns:

A reference to the newly created object.

Return type:

AuthenticationKey

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_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_public_key(public_key)[source]

Change an asymmetric AuthenticationKey’s public key

Parameters:

public_key (cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey) – The new public key.

Return type:

None

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:
Parameters:
object_type
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 (yubihsm.core.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 (yubihsm.defs.CAPABILITY) – The set of capabilities to give the object.

  • key – The private key to import.

Returns:

A reference to the newly created object.

Return type:

AsymmetricKey

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

Generate a new private key in the YubiHSM.

Parameters:

  • session (yubihsm.core.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 (yubihsm.defs.CAPABILITY) – The set of capabilities to give the object.

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

Returns:

A reference to the newly created object.

Return type:

AsymmetricKey

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.

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

Returns:

The certificate stored for the object.

Return type:

cryptography.x509.Certificate

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:
Returns:

A reference to the newly created object.

Return type:

Opaque

sign_ecdsa(data, hash=hashes.SHA256(), length=0)[source]

Sign data using ECDSA.

Parameters:
Returns:

The resulting signature.

Return type:

bytes

derive_ecdh(public_key)[source]

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

Parameters:

public_key (cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey) – The public key to use for the key exchange.

Returns:

The resulting shared key.

Return type:

bytes

sign_pkcs1v1_5(data, hash=hashes.SHA256())[source]

Sign data using RSASSA-PKCS1-v1_5.

Parameters:
Returns:

The resulting signature.

Return type:

bytes

decrypt_pkcs1v1_5(data)[source]

Decrypt data encrypted with RSAES-PKCS1-v1_5.

Parameters:

data (bytes) – The ciphertext to decrypt.

Returns:

The decrypted plaintext.

Return type:

bytes

sign_pss(data, salt_len, hash=hashes.SHA256(), mgf_hash=hashes.SHA256())[source]

Sign data using RSASSA-PSS with MGF1.

Parameters:
Returns:

The resulting signature.

Return type:

bytes

decrypt_oaep(data, label=b'', hash=hashes.SHA256(), mgf_hash=hashes.SHA256())[source]

Decrypt data encrypted with RSAES-OAEP.

Parameters:
Returns:

The decrypted plaintext.

Return type:

bytes

sign_eddsa(data)[source]

Sign data using EdDSA.

Parameters:

data (bytes) – The data to sign.

Returns:

The resulting signature.

Return type:

bytes

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.

Returns:

The attestation certificate.

Return type:

cryptography.x509.Certificate

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

Sign an SSH certificate request.

Parameters:
Returns:

The SSH certificate signature.

Return type:

bytes

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:
Parameters:
object_type
classmethod generate(session, object_id, label, domains, capabilities, algorithm, delegated_capabilities)[source]

Generate a new wrap key in the YubiHSM.

Parameters:
Returns:

A reference to the newly created object.

Return type:

WrapKey

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:
Returns:

A reference to the newly created object.

Return type:

WrapKey

get_public_key()[source]

Get the public key of the wrapkey pair.

Return type:

cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey

wrap_data(data)[source]

Wrap (encrypt) arbitrary data.

Parameters:

data (bytes) – The data to encrypt.

Returns:

The encrypted data.

Return type:

bytes

unwrap_data(data)[source]

Unwrap (decrypt) arbitrary data.

Parameters:

data (bytes) – The encrypted data to decrypt.

Returns:

The decrypted data.

Return type:

bytes

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.

Returns:

The encrypted object data.

Return type:

bytes

import_wrapped(wrapped_obj)[source]

Import an object previously exported under wrap.

Parameters:

  • wraped_obj – The encrypted object data.

  • wrapped_obj (bytes)

Returns:

A reference to the imported object.

Return type:

YhsmObject

import_wrapped_rsa(wrapped_obj, oaep_hash=hashes.SHA256(), mgf_hash=hashes.SHA256(), oaep_label=b'')[source]

Import an object previously exported under asymmetric wrap.

Parameters:
Returns:

A reference to the imported object.

Return type:

YhsmObject

import_raw_key(object_id, object_type, label, domains, capabilities, algorithm, wrapped, oaep_hash=hashes.SHA256(), mgf_hash=hashes.SHA256(), 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:
Returns:

A reference to the imported key object.

Return type:

YhsmObject

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

Parameters:
object_type
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:
Returns:

A reference to the newly created object.

Return type:

PublicWrapKey

get_public_key()[source]

Get the public wrapkey.

Return type:

cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey

export_wrapped_rsa(obj, algorithm=ALGORITHM.AES256, oaep_hash=hashes.SHA256(), mgf_hash=hashes.SHA256(), oaep_label=b'')[source]

Export an object under asymmetric wrap.

Parameters:
Returns:

The encrypted object data.

Return type:

bytes

export_raw_key(key, algorithm=ALGORITHM.AES256, oaep_hash=hashes.SHA256(), mgf_hash=hashes.SHA256(), 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:
Returns:

The encrypted key.

Return type:

bytes

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

Bases: YhsmObject

Used to calculate and verify HMAC signatures.

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

Generate a new HMAC key in the YubiHSM.

Parameters:

  • session (yubihsm.core.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 (yubihsm.defs.CAPABILITY) – The set of capabilities to give the object.

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

Returns:

A reference to the newly created object.

Return type:

HmacKey

classmethod put(session, object_id, label, domains, capabilities, key, algorithm=ALGORITHM.HMAC_SHA256)[source]

Import an HMAC key into the YubiHSM.

Parameters:

  • session (yubihsm.core.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 (yubihsm.defs.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.

Returns:

A reference to the newly created object.

Return type:

HmacKey

sign_hmac(data)[source]

Calculate the HMAC signature of the given data.

Parameters:

data (bytes) – The data to sign.

Returns:

The signature.

Return type:

bytes

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.

Returns:

True if verification succeeded, False if not.

Return type:

bool

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

Bases: YhsmObject

Binary template used to validate SSH certificate requests.

Supported algorithms:
Parameters:
object_type
classmethod put(session, object_id, label, domains, capabilities, algorithm, data)[source]

Import a Template into the YubiHSM.

Parameters:

  • session (yubihsm.core.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 (yubihsm.defs.CAPABILITY) – The set of capabilities to give the object.

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

  • data (bytes) – The template data.

Returns:

A reference to the newly created object.

Return type:

Template

get()[source]

Read a Template from the YubiHSM.

Returns:

The template data.

Return type:

bytes

class yubihsm.objects.OtpData[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.

use_counter: int
session_counter: int
timestamp_high: int
timestamp_low: int
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:
Parameters:
object_type
classmethod put(session, object_id, label, domains, capabilities, algorithm, nonce_id, key)[source]

Import an OTP AEAD key into the YubiHSM.

Parameters:

  • session (yubihsm.core.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 (yubihsm.defs.CAPABILITY) – The set of capabilities to give the object.

  • algorithm (yubihsm.defs.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.

Returns:

A reference to the newly created object.

Return type:

OtpAeadKey

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

Generate a new OTP AEAD key in the YubiHSM.

Parameters:

  • session (yubihsm.core.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 (yubihsm.defs.CAPABILITY) – The set of capabilities to give the object.

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

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

Returns:

A reference to the newly created object.

Return type:

OtpAeadKey

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.

Returns:

A new AEAD.

Return type:

bytes

randomize_otp_aead()[source]

Create a new Yubico OTP credential AEAD using random data.

Returns:

A new AEAD.

Return type:

bytes

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.

Returns:

The decrypted OTP data.

Return type:

OtpData

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.

Returns:

The new AEAD.

Return type:

bytes

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

Bases: YhsmObject

Used to encrypt/decrypt data using a symmetric key.

Supported algorithms:
Parameters:
object_type
classmethod put(session, object_id, label, domains, capabilities, algorithm, key)[source]

Import a symmetric key into the YubiHSM.

Parameters:

  • session (yubihsm.core.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 (yubihsm.defs.CAPABILITY) – The set of capabilities to give the object.

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

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

Returns:

A reference to the newly created object.

Return type:

SymmetricKey

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

Generate a new symmetric key in the YubiHSM.

Parameters:

  • session (yubihsm.core.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 (yubihsm.defs.CAPABILITY) – The set of capabilities to give the object.

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

Returns:

A reference to the newly created object.

Return type:

SymmetricKey

encrypt_ecb(data)[source]

Encrypt data in ECB mode.

Parameters:

data (bytes) – The data to encrypt.

Returns:

The encrypted data.

Return type:

bytes

decrypt_ecb(data)[source]

Decrypt data in ECB mode.

Parameters:

data (bytes) – The data to decrypt.

Returns:

The decrypted data.

Return type:

bytes

encrypt_cbc(iv, data)[source]

Encrypt data in CBC mode.

Parameters:

  • iv (bytes) – The initialization vector.

  • data (bytes) – The data to encrypt.

Returns:

The encrypted data.

Return type:

bytes

decrypt_cbc(iv, data)[source]

Decrypt data in CBC mode.

Parameters:

  • iv (bytes) – The initialization vector.

  • data (bytes) – The data to decrypt.

Returns:

The decrypted data.

Return type:

bytes