Ciphers#

Base cipher interface module.

This module provides the abstract base class for all cipher implementations in the core_ciphers package.

class core_ciphers.base.ICipher(key: bytes | None = None, mode: int = 11, encoding: str = 'UTF-8')[source]#

Bases: ABC

Base class for all cipher implementations

__init__(key: bytes | None = None, mode: int = 11, encoding: str = 'UTF-8') → None[source]#

Initialize the cipher with encryption parameters.

Parameters:

  • key – Encryption key as bytes. If None, a random key is generated (32 bytes for MODE_SIV, 16 bytes for other modes).

  • mode – AES cipher mode (default: AES.MODE_GCM).

  • encoding – Character encoding for string operations (default: “UTF-8”).

abstractmethod encrypt(data: Any, *args: Any, **kwargs: Any) → Any[source]#

Encrypt the data.

Parameters:

data – The data to encrypt.

Returns:

The encrypted data (implementation-specific format).

abstractmethod decrypt(data: Any, *args: Any, **kwargs: Any) → Any[source]#

Decrypt the data.

Parameters:

data – The encrypted data to decrypt.

Returns:

The decrypted data (implementation-specific format).

The AESCipher class implements the ICipher interface and provides AES encryption/decryption functionality supporting multiple cipher modes.

class core_ciphers.aes_cipher.AESCipher(key: bytes | None = None, mode: int = 11, encoding: str = 'UTF-8', block_size: int = 16, authenticated_modes: Tuple[int, ...] | None = None, padding_modes: Tuple[int, ...] | None = None)[source]#

Bases: ICipher

Cipher that use AES (Advanced Encryption Standard) method with MODE_GCM

This symmetric/reversible key encryption block clipper is equipped to handle 128-bit blocks, using keys sized at 128, 192, and 256 bits.

This block chipper is especially recognized for protecting data at rest, and it’s widely regarded as the most secure symmetric key encryption cipher yet invented.

AES Cipher Modes The cipher modes are required for a usual AES implementation. An incorrect implementation or application of modes may severely compromise the AES algorithm security. There are multiple chipper modes are available in AES, Some highly used AES cipher modes as follows:

  • ECB mode: Electronic Code Book mode

  • CBC mode: Cipher Block Chaining mode

  • CFB mode: Cipher Feedback mode

  • OFB mode: Output FeedBack mode

  • CTR mode: Counter mode

  • GCM mode: Galois/Counter mode

CBC mode: Cipher Block Chaining mode In CBC the mode, every encryption of the same plaintext should result in a different ciphertext. The CBC mode does this with an initialization vector. The vector has the same size as the block that is encrypted.

Problems in (CBC mode) One of the major problems an error of one plaintext block will affect all the following blocks. At the same time, Cipher Block Chaining mode(CBC) is vulnerable to multiple attack types:

  • Chosen Plaintext Attack(CPA)

  • Chosen Ciphertext Attack(CCA)

  • Padding oracle attacks

AES-GCM instead of AES-CBC Both the AES-CBC and AES-GCM are able to secure your valuable data with a good implementation. but to prevent complex CBC attacks such as Chosen Plaintext Attack(CPA) and Chosen Ciphertext Attack(CCA) it is necessary to use Authenticated Encryption. So the best option is for that is GCM. AES-GCM is written in parallel which means throughput is significantly higher than AES-CBC by lowering encryption overheads.

AES-GCM In simple terms, Galois Counter Mode (GCM) block clipper is a combination of Counter mode (CTR) and Authentication it’s faster and more secure with a better implementation for table-driven field operations. GCM has two operations, authenticated encryption and authenticated decryption.

The GCM mode will accept pipelined and parallelized implementations and have minimal computational latency in order to be useful at high data rates. As a conclusion, we can choose the Galois Counter Mode (GCM) block clipper mode to achieve excellent security performance for data at rest.

__init__(key: bytes | None = None, mode: int = 11, encoding: str = 'UTF-8', block_size: int = 16, authenticated_modes: Tuple[int, ...] | None = None, padding_modes: Tuple[int, ...] | None = None) → None[source]#

Initialize the AES cipher with encryption parameters.

Parameters:

  • key – Encryption key as bytes. If None, a random key is generated (32 bytes for MODE_SIV, 16 bytes for other modes).

  • mode – AES cipher mode (default: AES.MODE_GCM).

  • encoding – Character encoding for string operations (default: “UTF-8”).

  • block_size – Block size for padding operations (default: 16 bytes).

  • authenticated_modes – Tuple of AES modes that support authenticated encryption. Default: (MODE_GCM, MODE_EAX, MODE_CCM, MODE_SIV, MODE_OCB).

  • padding_modes – Tuple of AES modes that require padding. Default: (MODE_ECB, MODE_CBC). Note: Stream cipher modes (CFB, OFB, CTR) and authenticated modes (GCM, EAX, CCM, SIV) do not require padding.

encrypt(data: str, *args, **kwargs) → Dict[source]#

Encrypts the provided string data using AES encryption.

The method converts the input string to bytes, applies padding if required for the cipher mode, encrypts the data, and generates an authentication tag for authenticated encryption modes (GCM, EAX, CCM, SIV, OCB).

Parameters:

data – The plaintext string to encrypt.

Returns:

A dictionary containing hex-encoded encryption components:

  • ciphertext (str): The encrypted data.

  • tag (str, optional): Authentication tag for authenticated modes.

  • nonce (str, optional): Nonce used for encryption (for nonce-based modes).

  • iv (str, optional): Initialization vector (for IV-based modes).

decrypt(data: Dict, *args, **kwargs) → str[source]#

Decrypts the encrypted data and returns the original plaintext string.

The method processes a dictionary containing hex-encoded encryption components, converts them back to bytes, decrypts the ciphertext using the appropriate cipher mode, removes padding if necessary, and verifies the authentication tag for authenticated encryption modes.

Parameters:

data –

Dictionary containing hex-encoded encryption components:

  • ciphertext (str): The encrypted data to decrypt.

  • tag (str, optional): Authentication tag (required for authenticated modes).

  • nonce (str, optional): Nonce used during encryption.

  • iv (str, optional): Initialization vector used during encryption.

Returns:

The decrypted plaintext string.