encryption

Utilities for generating keys and encrypting/decrypting messages using the x25519 key exchange and AES-GCM encryption (formatted in the way the vLLM plugin expects).

Functions:

Name	Description
concatenate_ciphertexts_str	Concatenate multiple base64-encoded ciphertexts into a single deliminated, base64-encoded ciphertext.
decrypt	Decrypt a ciphertext using AES-GCM.
decrypt_str	Decrypt a |-delimited, base64-encoded ciphertext using the decryption scheme (the decrypt function expects bytes payload).
decrypt_str_with	Decrypt a |-delimited, base64-encoded ciphertext using an already-constructed cipher.
decrypt_with	Decrypt a ciphertext using an already-constructed AES-GCM cipher.
derive_shared_aes_key	Derive a shared (secret) AES key from a private key and a peer's public key.
encrypt	Encrypt a plaintext using AES-GCM.
encrypt_str	Encrypt a UTF-8 string using the encryption scheme (the encrypt function expects bytes payload).
encrypt_str_with	Encrypt a UTF-8 string using an already-constructed AES-GCM cipher.
encrypt_with	Encrypt a plaintext using an already-constructed AES-GCM cipher.
generate_ephemeral_keypair	Generate an ephemeral x25519 keypair.
new_cipher	Build a reusable AES-GCM cipher from a shared key.

Attributes:

Name	Type	Description
CONCATENATED_CIPHERTEXT_SEPARATOR	Final[str]	Separator used when concatenating multiple base64-encoded ciphertexts into a single string.
SCRUBBED_TOKEN_ID	Final[int]	Placeholder written over every token ID, so no vocabulary information leaves the server.

CONCATENATED_CIPHERTEXT_SEPARATOR module-attribute

CONCATENATED_CIPHERTEXT_SEPARATOR: Final[str] = '|'

Separator used when concatenating multiple base64-encoded ciphertexts into a single string.

SCRUBBED_TOKEN_ID module-attribute

SCRUBBED_TOKEN_ID: Final[int] = -1

Placeholder written over every token ID, so no vocabulary information leaves the server.

concatenate_ciphertexts_str

concatenate_ciphertexts_str(
    ciphertexts: Sequence[str],
) -> str

Concatenate multiple base64-encoded ciphertexts into a single deliminated, base64-encoded ciphertext.

Parameters:

Name	Type	Description	Default
ciphertexts	Sequence[str]	The list of base64-encoded ciphertexts to concatenate.	required

Returns:

Type	Description
str	The concatenated base64-encoded ciphertext.

decrypt

decrypt(ciphertext: bytes, shared_aes_key: bytes) -> bytes

Decrypt a ciphertext using AES-GCM.

Parameters:

Name	Type	Description	Default
ciphertext	bytes	The ciphertext to decrypt.	required
shared_aes_key	bytes	The shared AES key.	required

Returns:

Type	Description
bytes	The plaintext.

decrypt_str

decrypt_str(string: str, shared_aes_key: bytes) -> str

Decrypt a |-delimited, base64-encoded ciphertext using the decryption scheme (the decrypt function expects bytes payload).

Multiple ciphertexts separated by | are supported; they are decrypted individually and concatenated.

Parameters:

Name	Type	Description	Default
string	str	Ciphertext to decrypt.	required
shared_aes_key	bytes	Shared AES key.	required

Returns:

Type	Description
str	The decrypted plaintext (as a utf-8 string)

decrypt_str_with

decrypt_str_with(string: str, aes_gcm: AESGCM) -> str

Decrypt a |-delimited, base64-encoded ciphertext using an already-constructed cipher.

Parameters:

Name	Type	Description	Default
string	str	Ciphertext to decrypt.	required
aes_gcm	AESGCM	Cipher from new_cipher.	required

Returns:

Type	Description
str	The decrypted plaintext (as a utf-8 string)

decrypt_with

decrypt_with(ciphertext: bytes, aes_gcm: AESGCM) -> bytes

Decrypt a ciphertext using an already-constructed AES-GCM cipher.

Parameters:

Name	Type	Description	Default
ciphertext	bytes	The ciphertext to decrypt, with the nonce prepended.	required
aes_gcm	AESGCM	Cipher from new_cipher.	required

Returns:

Type	Description
bytes	The plaintext.

derive_shared_aes_key

derive_shared_aes_key(
    private_key: X25519PrivateKey,
    peer_public_key: X25519PublicKey,
) -> bytes

Derive a shared (secret) AES key from a private key and a peer's public key.

Parameters:

Name	Type	Description	Default
private_key	X25519PrivateKey	The private key.	required
peer_public_key	X25519PublicKey	The peer's public key.	required

Returns:

Type	Description
bytes	The shared AES key.

Raises:

Type	Description
ValueError	If the peer's public key is the same as the private key's public key.

encrypt

encrypt(plaintext: bytes, shared_aes_key: bytes) -> bytes

Encrypt a plaintext using AES-GCM.

Parameters:

Name	Type	Description	Default
plaintext	bytes	The plaintext to encrypt.	required
shared_aes_key	bytes	The shared AES key.	required

Returns:

Type	Description
bytes	The ciphertext.

encrypt_str

encrypt_str(string: str, shared_aes_key: bytes) -> str

Encrypt a UTF-8 string using the encryption scheme (the encrypt function expects bytes payload).

Parameters:

Name	Type	Description	Default
string	str	Plaintext to encrypt.	required
shared_aes_key	bytes	AES key used to encrypt the string.	required

Returns:

Type	Description
str	The base64-encoded, encrypted ciphertext.

encrypt_str_with

encrypt_str_with(string: str, aes_gcm: AESGCM) -> str

Encrypt a UTF-8 string using an already-constructed AES-GCM cipher.

Parameters:

Name	Type	Description	Default
string	str	Plaintext to encrypt.	required
aes_gcm	AESGCM	Cipher from new_cipher.	required

Returns:

Type	Description
str	The base64-encoded, encrypted ciphertext.

encrypt_with

encrypt_with(plaintext: bytes, aes_gcm: AESGCM) -> bytes

Encrypt a plaintext using an already-constructed AES-GCM cipher.

Parameters:

Name	Type	Description	Default
plaintext	bytes	The plaintext to encrypt.	required
aes_gcm	AESGCM	Cipher from new_cipher.	required

Returns:

Type	Description
bytes	The ciphertext, with the nonce prepended.

generate_ephemeral_keypair

generate_ephemeral_keypair() -> tuple[
    x25519.X25519PrivateKey, x25519.X25519PublicKey
]

Generate an ephemeral x25519 keypair.

Returns:

Type	Description
tuple[x25519.X25519PrivateKey, x25519.X25519PublicKey]	The private and public keypair.

new_cipher

new_cipher(shared_aes_key: bytes) -> aead.AESGCM

Build a reusable AES-GCM cipher from a shared key.

Constructing an AESGCM expands the AES key schedule. That cost belongs once per request, alongside the key derivation, not once per generated token: the encryption entry points below run on the vLLM API server's event loop for every streaming step of every request.

Parameters:

Name	Type	Description	Default
shared_aes_key	bytes	The shared AES key.	required

Returns:

Type	Description
aead.AESGCM	A cipher bound to shared_aes_key, safe to reuse for many messages.