orionis.encrypter.Encrypter

THE ORIONIS API

Build with clarity.

Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.

Explore modules View classes

class documentation

class Encrypter(IEncrypter): (source)

Constructor: Encrypter(app)

View In Hierarchy

Undocumented

Method	`__decodePayload`	Decode base64 payload and parse as typed _Payload struct.
Method	`__decryptCBC`	Decrypt CBC-encrypted data and remove PKCS7 padding.
Method	`__decryptGCM`	Decrypt GCM-encrypted data using AESGCM with authentication tag.
Method	`__encryptCBC`	Encrypt data using AES-CBC with PKCS7 padding.
Method	`__encryptGCM`	Encrypt data using AES-GCM mode with authentication.
Method	`__extractPayloadData`	Extract payload fields, base64-decoding binary values.
Method	`__init__`	Initialize the encrypter with application configuration.
Method	`__performDecryption`	Perform decryption based on the configured cipher mode.
Method	`__validateCipherMatch`	Validate that payload cipher matches the configured cipher.
Method	`__validateIvSize`	Validate that the IV size matches the configured cipher requirements.
Method	`decrypt`	Decrypt an encrypted payload using the configured cipher algorithm.
Method	`encrypt`	Encrypt plaintext using the configured cipher algorithm.
Constant	`AES_128_KEY_SIZE`	Undocumented
Constant	`AES_256_KEY_SIZE`	Undocumented
Constant	`CBC_IV_SIZE`	Undocumented
Constant	`GCM_IV_SIZE`	Undocumented
Constant	`GCM_TAG_SIZE`	Undocumented
Constant	`PKCS7_BLOCK_SIZE`	Undocumented
Constant	`SUPPORTED_CIPHERS`	Undocumented
Class Variable	`__slots__`	Undocumented
Instance Variable	`_aesgcm`	Undocumented
Instance Variable	`_is_gcm`	Undocumented
Instance Variable	`cipher`	Undocumented
Instance Variable	`key`	Undocumented

def __decodePayload(self, payload: str) -> _Payload: (source) ¶

Decode base64 payload and parse as typed _Payload struct.

Parameters
payload:`str`	Base64-encoded JSON payload string to decode.

Returns
`_Payload`	Decoded and schema-validated payload struct.

Raises
`ValueError`	If payload cannot be decoded or parsed as JSON.

def __decryptCBC(self, ct: bytes, iv: bytes) -> bytes: (source) ¶

Decrypt CBC-encrypted data and remove PKCS7 padding.

Parameters
ct:`bytes`	The encrypted ciphertext to decrypt.
iv:`bytes`	The initialization vector used during encryption.

Returns
`bytes`	The decrypted plaintext with padding removed.

Raises
`ValueError`	If decrypted data is empty or padding is invalid.
`RuntimeError`	If CBC decryption fails.

def __decryptGCM(self, value: bytes, iv: bytes, tag: bytes | None) -> bytes: (source) ¶

Decrypt GCM-encrypted data using AESGCM with authentication tag.

Parameters
value:`bytes`	The encrypted ciphertext to decrypt.
iv:`bytes`	The initialization vector used during encryption.
tag:`bytes \| None`	The authentication tag for GCM mode verification.

Returns
`bytes`	The decrypted plaintext as raw bytes.

Raises
`ValueError`	If tag is None or GCM verification fails.
`RuntimeError`	If GCM decryption fails for any other reason.

def __encryptCBC(self, data: bytes) -> str: (source) ¶

Encrypt data using AES-CBC with PKCS7 padding.

Parameters
data:`bytes`	The raw data to encrypt.

Returns
`str`	Base64-encoded JSON payload containing IV, encrypted value, and cipher.

Raises
`RuntimeError`	If CBC encryption fails.

def __encryptGCM(self, data: bytes) -> str: (source) ¶

Encrypt data using AES-GCM mode with authentication.

Parameters
data:`bytes`	The raw data to encrypt.

Returns
`str`	Base64-encoded JSON payload containing IV, encrypted value, tag, and cipher.

Raises
`RuntimeError`	If GCM encryption fails.

def __extractPayloadData(self, data: _Payload) -> tuple[str, bytes, bytes, bytes | None]: (source) ¶

Extract payload fields, base64-decoding binary values.

Parameters
data:`_Payload`	Parsed payload struct (fields already validated by msgspec).

Returns
`tuple[str, bytes, bytes, bytes \| None]`	Tuple containing (cipher, iv, value, tag) where tag may be None.

Raises
`ValueError`	If base64 decoding of any field fails.

def __init__(self, app: IApplication): (source) ¶

Initialize the encrypter with application configuration.

Parameters
app:`IApplication`	The application instance providing configuration access.

Returns
`None`	This method initializes the instance and returns None.

Raises
`ValueError`	If the cipher is not supported or key length is invalid.

def __performDecryption(self, value: bytes, iv: bytes, tag: bytes | None) -> str: (source) ¶

Perform decryption based on the configured cipher mode.

Parameters
value:`bytes`	The encrypted data to decrypt.
iv:`bytes`	The initialization vector used during encryption.
tag:`bytes \| None`	The authentication tag for GCM mode, None for CBC mode.

Returns
`str`	The decrypted plaintext as a UTF-8 string.

Raises
`ValueError`	If tag requirements are not met for GCM mode.
`RuntimeError`	If decryption fails for any reason.

def __validateCipherMatch(self, cipher: str): (source) ¶

Validate that payload cipher matches the configured cipher.

Parameters
cipher:`str`	The cipher algorithm name from the payload.

Returns
`None`	This method validates compatibility and returns None.

Raises
`ValueError`	If the payload cipher does not match the configured cipher.

def __validateIvSize(self, iv: bytes): (source) ¶

Validate that the IV size matches the configured cipher requirements.

Parameters
iv:`bytes`	The initialization vector bytes to validate.

Returns
`None`	This method validates IV size and returns None.

Raises
`ValueError`	If IV size does not match the cipher requirements.

def decrypt(self, payload: str) -> str: (source) ¶

overrides orionis.encrypter.contracts.IEncrypter.decrypt

Decrypt an encrypted payload using the configured cipher algorithm.

Parameters
payload:`str`	Base64-encoded encrypted payload containing IV, value, tag, and cipher.

Returns
`str`	The decrypted plaintext as a UTF-8 string.

Raises
`TypeError`	If payload is not a string.
`ValueError`	If payload is empty or invalid.
`RuntimeError`	If decryption fails.

def encrypt(self, plaintext: str) -> str: (source) ¶

overrides orionis.encrypter.contracts.IEncrypter.encrypt

Encrypt plaintext using the configured cipher algorithm.

Parameters
plaintext:`str`	The text to encrypt.

Returns
`str`	Base64-encoded encrypted payload containing IV, value, tag, and cipher.

Raises
`TypeError`	If plaintext is not a string.
`ValueError`	If plaintext is empty or has encoding issues.
`RuntimeError`	If encryption fails.

AES_128_KEY_SIZE: int = (source) ¶

Undocumented

Value

AES_256_KEY_SIZE: int = (source) ¶

Undocumented

Value

CBC_IV_SIZE: int = (source) ¶

Undocumented

Value

GCM_IV_SIZE: int = (source) ¶

Undocumented

Value

GCM_TAG_SIZE: int = (source) ¶

Undocumented

Value

PKCS7_BLOCK_SIZE: int = (source) ¶

Undocumented

Value

SUPPORTED_CIPHERS: ClassVar[frozenset[str]] = (source) ¶

Undocumented

Value

frozenset((cipher.value for cipher in OrionisCipher))

__slots__: tuple[str, ...] = (source) ¶

overrides orionis.encrypter.contracts.IEncrypter.__slots__

Undocumented

_aesgcm: AESGCM | None = (source) ¶

Undocumented

_is_gcm: bool = (source) ¶

Undocumented

cipher: str = (source) ¶

Undocumented

key: bytes = (source) ¶

Undocumented