imaging_api.utils.encryption
============================

.. py:module:: imaging_api.utils.encryption


Functions
---------

.. autoapisummary::

   imaging_api.utils.encryption.get_aes_key
   imaging_api.utils.encryption.encrypt
   imaging_api.utils.encryption.decrypt


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

.. py:function:: get_aes_key() -> bytes

   Retrieve the AES key from the environment file and return it as bytes.

   :returns: The decoded AES key (16, 24, or 32 bytes).
   :rtype: bytes

   :raises ValueError: If the AES key is missing from configuration or has an invalid length.


.. py:function:: encrypt(plaintext: str, key: bytes | None = None) -> str

   Encrypt plaintext using AES-CBC with PKCS7 padding. Returns Base64-encoded ciphertext.

   :param plaintext: The plaintext string to encrypt.
   :type plaintext: str
   :param key: The AES key to use. If None, the shared AES key is retrieved via
               :func:`get_aes_key`.
   :type key: bytes | None

   :returns: Base64-encoded ciphertext with the random 16-byte IV prepended to the ciphertext
             bytes before encoding.
   :rtype: str


.. py:function:: decrypt(encoded_payload: str, key: bytes | None = None) -> str

   Decrypt Base64-encoded ciphertext using AES-CBC with PKCS7 padding. Returns the original plaintext.

   :param encoded_payload: Base64-encoded payload where the first 16 bytes are the IV and the
                           remaining bytes are the ciphertext.
   :type encoded_payload: str
   :param key: The AES key to use. If None, the shared AES key is retrieved via
               :func:`get_aes_key`.
   :type key: bytes | None

   :returns: The decrypted plaintext.
   :rtype: str