util.encrypted_fields
=====================

.. py:module:: util.encrypted_fields

.. autoapi-nested-parse::

   Encrypted fields for sensitive data using PKCS#11 DEK encryption.





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

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

   Bases: :py:obj:`django.db.models.TextField`\ [\ :py:obj:`str`\ , :py:obj:`str`\ ]


   A TextField that automatically encrypts/decrypts data using PKCS#11 DEK.

   This field uses AES-256-CBC encryption with the DEK (Data Encryption Key)
   from the PKCS#11 token to encrypt sensitive data before storing it in the database.


   .. py:attribute:: description


   .. py:method:: raise_validation_error(msg)

      Raise a ValidationError with the given message.

      :param msg: The error message to include in the ValidationError.
      :type msg: str

      :raises ValidationError: Always raised with the provided message.



   .. py:method:: should_encrypt()

      Check if encryption should be used based on crypto storage configuration.

      :returns: True if storage type is SoftHSM or Physical HSM, False for software storage.
      :rtype: bool

      :raises ValidationError: If crypto storage config is not found or there's an error accessing it.



   .. py:method:: get_dek()

      Get the DEK from PKCS#11 token, preferring cached value.

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

      :raises ValidationError: If no PKCS#11 token is configured or DEK unavailable.



   .. py:method:: encrypt_value(value)

      Encrypt a string value using AES-256-GCM with the PKCS#11 DEK.

      :param value: The plaintext string to encrypt.

      :returns: Base64-encoded encrypted data in format: nonce:tag:ciphertext
      :rtype: str



   .. py:method:: decrypt_value(encrypted_value)

      Decrypt a base64-encoded encrypted value using the PKCS#11 DEK.

      :param encrypted_value: Base64-encoded encrypted data.

      :returns: The decrypted plaintext string.
      :rtype: str



   .. py:method:: from_db_value(value, expression, connection)

      Convert value from database to Python object.

      This method is called when data is loaded from the database.



   .. py:method:: to_python(value)

      Convert value to Python object.

      This method is called during deserialization and in forms.



   .. py:method:: get_prep_value(value)

      Convert Python object to database value.

      This method is called when saving data to the database.



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

   Bases: :py:obj:`django.db.models.CharField`\ [\ :py:obj:`str`\ , :py:obj:`str`\ ]


   A CharField that automatically encrypts/decrypts data using PKCS#11 DEK.

   Similar to EncryptedTextField but with CharField constraints.


   .. py:attribute:: description


   .. py:method:: deconstruct()

      Return field deconstruction for migrations.

      This method ensures that the encrypted size (not plaintext) is stored in migrations,
      but the model field keeps the plaintext max_length, preventing migration regeneration.



   .. py:method:: db_type(connection)

      Return the database column type with encrypted size.

      This ensures the database actually has enough space for encrypted data.



   .. py:method:: raise_validation_error(msg)

      Raise a ValidationError with the given message.

      :param msg: The error message to include in the ValidationError.
      :type msg: str

      :raises ValidationError: Always raised with the provided message.



   .. py:method:: should_encrypt()

      Check if encryption should be used based on crypto storage configuration.

      :returns: True if storage type is SoftHSM or Physical HSM, False for software storage.
      :rtype: bool

      :raises ValidationError: If crypto storage config is not found or there's an error accessing it.



   .. py:method:: get_dek()

      Get the DEK from PKCS#11 token, preferring cached value.



   .. py:method:: encrypt_value(value)

      Encrypt a string value using AES-256-GCM with the PKCS#11 DEK.



   .. py:method:: decrypt_value(encrypted_value)

      Decrypt a base64-encoded encrypted value using the PKCS#11 DEK.



   .. py:method:: from_db_value(value, expression, connection)

      Convert value from database to Python object.



   .. py:method:: to_python(value)

      Convert value to Python object.



   .. py:method:: get_prep_value(value)

      Convert Python object to database value.