management.models.pkcs11
========================

.. py:module:: management.models.pkcs11

.. autoapi-nested-parse::

   PKCS#11 Token Model.





Module Contents
---------------

.. py:class:: PKCS11Token(*args, **kwargs)

   Bases: :py:obj:`django.db.models.Model`, :py:obj:`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.


   .. py:attribute:: KEK_ENCRYPTION_KEY_LABEL
      :value: 'trustpoint-kek'



   .. py:attribute:: DEK_CACHE_LABEL
      :value: 'trustpoint-dek-chache'



   .. py:attribute:: WRAPPED_DEK_LENGTH
      :value: 40



   .. py:attribute:: ARGON2_TIME_COST
      :value: 3



   .. py:attribute:: ARGON2_MEMORY_COST
      :value: 65536



   .. py:attribute:: ARGON2_PARALLELISM
      :value: 1



   .. py:attribute:: ARGON2_HASH_LENGTH
      :value: 32



   .. py:attribute:: label


   .. py:attribute:: slot


   .. py:attribute:: module_path


   .. py:attribute:: encrypted_dek


   .. py:attribute:: bek_encrypted_dek


   .. py:attribute:: kek


   .. py:attribute:: created_at


   .. py:class:: Meta

      Meta options for the PKCS11Token model.


      .. py:attribute:: verbose_name


      .. py:attribute:: verbose_name_plural



   .. py:method:: save(*args, **kwargs)

      Ensure only one instance exists (singleton pattern).



   .. py:method:: load()
      :classmethod:


      Returns the single instance, creating it if necessary.



   .. py:method:: clean()

      Ensure only one PKCS11Token instance exists.

      Raises:
      ------
      ValidationError
          If more than one PKCS11Token instance is attempted to be created.



   .. py:method:: generate_kek(key_length = 256)

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

      :param key_length: AES key length in bits (default: 256)

      :returns: True if key was generated successfully, False otherwise
      :rtype: bool

      :raises RuntimeError: If key generation fails



   .. py:method:: 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
      :rtype: bool



   .. py:method:: generate_and_wrap_dek(dek_size = 32)

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

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

      :returns: The wrapped DEK data
      :rtype: bytes

      :raises RuntimeError: If DEK generation or wrapping fails



   .. py:method:: wrap_dek(dek_bytes)

      Wrap a DEK using the HSM AES key.

      :param dek_bytes: The plain DEK to wrap

      :returns: The wrapped DEK data
      :rtype: bytes

      :raises RuntimeError: If wrapping fails



   .. py:method:: get_dek()

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

      :returns: The 32-byte DEK
      :rtype: bytes

      :raises RuntimeError: If DEK cannot be retrieved or unwrapped



   .. py:method:: 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.
      :rtype: bytes | None



   .. py:method:: clear_dek_cache()

      Clear the cached DEK from memory.



   .. py:method:: 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.
      :rtype: str

      :raises ImproperlyConfigured: If no PIN is available.



   .. py:method:: set_backup_password(password, dek_size = 32)

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

      :param password: The backup password to use for BEK derivation
      :param dek_size: Size of the DEK in bytes (default: 32 for AES-256)

      :raises RuntimeError: If DEK encryption with BEK fails
      :raises ValueError: If no DEK is available to encrypt or invalid parameters



   .. py:method:: get_dek_with_backup_password(password)

      Retrieve the DEK using the backup password.

      :param password: The backup password used for BEK derivation

      :returns: The decrypted DEK
      :rtype: bytes

      :raises RuntimeError: If DEK decryption fails
      :raises ValueError: If no backup encryption is available



   .. py:method:: verify_backup_password(password)

      Verify if the provided backup password is correct.

      :param password: The backup password to verify

      :returns: True if password is correct, False otherwise
      :rtype: bool



   .. py:method:: remove_backup_encryption()

      Remove backup encryption (BEK-encrypted DEK).

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



   .. py:method:: has_backup_encryption()

      Check if backup encryption is configured.

      :returns: True if backup encryption is available, False otherwise
      :rtype: bool