management.models.pkcs11

PKCS#11 Token Model.

Module Contents

class management.models.pkcs11.PKCS11Token(*args, **kwargs)

Bases: django.db.models.Model, trustpoint.logger.LoggerMixin

Model representing a PKCS#11 token (e.g., a SoftHSM slot/token pair).

Stores metadata required to authenticate and interact with the token, including slot number, user and security officer PINs, and the path to the PKCS#11 module library.

KEK_ENCRYPTION_KEY_LABEL = 'trustpoint-kek'

DEK_CACHE_LABEL = 'trustpoint-dek-chache'

WRAPPED_DEK_LENGTH = 40

ARGON2_TIME_COST = 3

ARGON2_MEMORY_COST = 65536

ARGON2_PARALLELISM = 1

ARGON2_HASH_LENGTH = 32

label

slot

module_path

encrypted_dek

bek_encrypted_dek

kek

created_at

class Meta

Meta options for the PKCS11Token model.

verbose_name

verbose_name_plural

save(*args, **kwargs)

Ensure only one instance exists (singleton pattern).

Parameters:

• args (Any)

• kwargs (Any)

Return type:

None

classmethod load()

Returns the single instance, creating it if necessary.

Return type:

PKCS11Token

clean()

Ensure only one PKCS11Token instance exists.

Raises:

ValidationError

If more than one PKCS11Token instance is attempted to be created.

Return type:

None

generate_kek(key_length=256)

Generate the KEK (key encryption key) in the PKCS#11 token.

Parameters:

key_length (int) – AES key length in bits (default: 256)

Returns:

True if key was generated successfully, False otherwise

Return type:

bool

Raises:

RuntimeError – If key generation fails

load_kek()

Load and verify the KEK (key encryption key) exists on the PKCS#11 token.

This method checks if the KEK actually exists on the physical HSM, not just in the database. It attempts to load the key from the HSM.

Returns:

True if KEK exists on HSM, False otherwise

Return type:

bool

generate_and_wrap_dek(dek_size=32)

Generate a new DEK and wrap it using the HSM AES key.

Parameters:

dek_size (int) – Size of the DEK in bytes (default: 32 for AES-256)

Returns:

The wrapped DEK data

Return type:

bytes

Raises:

RuntimeError – If DEK generation or wrapping fails

wrap_dek(dek_bytes)

Wrap a DEK using the HSM AES key.

Parameters:

dek_bytes (bytes) – The plain DEK to wrap

Returns:

The wrapped DEK data

Return type:

bytes

Raises:

RuntimeError – If wrapping fails

get_dek()

Get the Data Encryption Key (DEK), unwrapping it if necessary.

Returns:

The 32-byte DEK

Return type:

bytes

Raises:

RuntimeError – If DEK cannot be retrieved or unwrapped

get_dek_cache()

Get the cached DEK without triggering unwrapping.

This method provides direct access to the cached DEK value without performing any PKCS#11 operations. Returns None if the cache is empty.

Returns:

The cached DEK bytes if available, None otherwise.

Return type:

bytes | None

clear_dek_cache()

Clear the cached DEK from memory.

Return type:

None

get_pin()

Get the user PIN for this PKCS#11 token.

PIN retrieval priority: 1. HSM_PIN_FILE environment variable (Docker secrets) 2. HSM_PIN environment variable

Returns:

The user PIN for token authentication.

Return type:

str

Raises:

ImproperlyConfigured – If no PIN is available.

set_backup_password(password, dek_size=32)

Set a backup password and encrypt the current DEK with BEK derived from it using Argon2.

Parameters:

• password (str) – The backup password to use for BEK derivation

• dek_size (int) – Size of the DEK in bytes (default: 32 for AES-256)

Raises:

• RuntimeError – If DEK encryption with BEK fails

• ValueError – If no DEK is available to encrypt or invalid parameters

Return type:

None

get_dek_with_backup_password(password)

Retrieve the DEK using the backup password.

Parameters:

password (str) – The backup password used for BEK derivation

Returns:

The decrypted DEK

Return type:

bytes

Raises:

• RuntimeError – If DEK decryption fails

• ValueError – If no backup encryption is available

verify_backup_password(password)

Verify if the provided backup password is correct.

Parameters:

password (str) – The backup password to verify

Returns:

True if password is correct, False otherwise

Return type:

bool

remove_backup_encryption()

Remove backup encryption (BEK-encrypted DEK).

This only removes the backup encryption, the primary KEK-encrypted DEK remains.

Return type:

None

has_backup_encryption()

Check if backup encryption is configured.

Returns:

True if backup encryption is available, False otherwise

Return type:

bool