gemstone_utils.crypto

Symmetric encryption registry, PBKDF2 primitive, and wire encoding helpers.

gemstone_utils.crypto.DEFAULT_PBKDF2_ITERATIONS_STRONG = 600000

OWASP-style iteration count for PBKDF2-HMAC-SHA256 persisted KDF defaults.

gemstone_utils.crypto.RECOMMENDED_DATA_ALG: Final[str] = 'A256GCM'

Default symmetric algorithm id for new field encryption and data_alg rows.

gemstone_utils.crypto.SUPPORTED_SYM_ALGS: frozenset[str] = frozenset({'A256GCM'})

Registered symmetric algorithm ids (read-only; use is_supported_sym_alg).

class gemstone_utils.crypto.SymAlgSpec(key_length, validate_sym_params, encrypt_impl, decrypt_impl)

Bases: NamedTuple

Registered symmetric algorithm: key size, param validation, and crypto ops.

Parameters:

• key_length (int)

• validate_sym_params (Callable[[Dict[str, Any]], None])

• encrypt_impl (Callable[[bytes, bytes, Dict[str, Any]], Tuple[bytes, Dict[str, Any]]])

• decrypt_impl (Callable[[bytes, bytes, Dict[str, Any]], bytes])

decrypt_impl: Callable[[bytes, bytes, Dict[str, Any]], bytes]

Alias for field number 3

encrypt_impl: Callable[[bytes, bytes, Dict[str, Any]], Tuple[bytes, Dict[str, Any]]]

Alias for field number 2

key_length: int

Alias for field number 0

validate_sym_params: Callable[[Dict[str, Any]], None]

Alias for field number 1

gemstone_utils.crypto.aesgcm_decrypt(dk, blob, aad=None)

Parameters:

• dk (bytes)

• blob (bytes)

• aad (bytes | None)

Return type:

bytes

gemstone_utils.crypto.aesgcm_encrypt(dk, plaintext, aad=None)

Parameters:

• dk (bytes)

• plaintext (bytes)

• aad (bytes | None)

Return type:

bytes

gemstone_utils.crypto.b64decode(data)

Decode a URL-safe base64 ASCII string to bytes.

Parameters:

data (str) – URL-safe base64 string.

Returns:

Decoded bytes.

Return type:

bytes

gemstone_utils.crypto.b64encode(data)

URL-safe base64-encode bytes to an ASCII string.

Parameters:

data (bytes) – Raw bytes.

Returns:

URL-safe base64 string without padding issues for wire segments.

Return type:

str

gemstone_utils.crypto.decrypt_alg(alg, key, ciphertext, params=None)

Decrypt with a registered symmetric algorithm.

Parameters:

• alg (str) – Registered symmetric algorithm id.

• key (bytes) – Key bytes sized for alg.

• ciphertext (bytes) – Ciphertext blob.

• params (Mapping[str, Any] | None) – Optional algorithm parameters (validated per algorithm).

Returns:

Plaintext bytes.

Raises:

ValueError – If alg is unsupported or params are invalid.

Return type:

bytes

gemstone_utils.crypto.decrypt_with_alg(alg, key, blob)

Decrypt with empty symmetric parameters (backward-compatible wrapper).

Parameters:

• alg (str) – Registered symmetric algorithm id.

• key (bytes) – Key bytes sized for alg.

• blob (bytes) – Ciphertext blob.

Returns:

Plaintext bytes.

Raises:

ValueError – If alg is unsupported or decryption fails.

Return type:

bytes

gemstone_utils.crypto.derive_pbkdf2_hmac_sha256(passphrase, salt, *, iterations, length=32)

Derive key bytes with PBKDF2-HMAC-SHA256.

Parameters:

• passphrase (str) – UTF-8 passphrase material.

• salt (bytes) – Salt bytes.

• iterations (int) – PBKDF2 iteration count.

• length (int) – Derived key length in bytes.

Returns:

Derived key bytes.

Raises:

TypeError – If passphrase or salt has the wrong type.

Return type:

bytes

gemstone_utils.crypto.encrypt_alg(alg, key, plaintext, params=None)

Encrypt with a registered symmetric algorithm.

Parameters:

• alg (str) – Registered symmetric algorithm id.

• key (bytes) – Key bytes sized for alg.

• plaintext (bytes) – Plaintext bytes.

• params (Mapping[str, Any] | None) – Optional algorithm parameters (validated per algorithm).

Returns:

A tuple (ciphertext, updated_params). Persist updated_params in the wire JSON segment when nonces or metadata are stored outside the blob.

Raises:

ValueError – If alg is unsupported or params are invalid.

Return type:

Tuple[bytes, Dict[str, Any]]

gemstone_utils.crypto.encrypt_with_alg(alg, key, plaintext)

Encrypt and return ciphertext only (backward-compatible wrapper).

Same as encrypt_alg() with empty params, discarding updated_params.

Parameters:

• alg (str) – Registered symmetric algorithm id.

• key (bytes) – Key bytes sized for alg.

• plaintext (bytes) – Plaintext bytes.

Returns:

Ciphertext bytes.

Raises:

ValueError – If alg is unsupported.

Return type:

bytes

gemstone_utils.crypto.generate_key_by_alg(alg)

Generate random key bytes sized for a registered algorithm.

Parameters:

alg (str) – Registered symmetric algorithm id.

Returns:

os.urandom(key_length) for alg.

Raises:

ValueError – If alg is not registered.

Return type:

bytes

gemstone_utils.crypto.is_supported_sym_alg(alg)

Return whether alg is a registered symmetric algorithm id.

Parameters:

alg (str) – Algorithm id (for example "A256GCM").

Returns:

True if alg is registered.

Return type:

bool

gemstone_utils.crypto.recommended_data_alg()

Return the symmetric algorithm id recommended for new field encryption.

Matches the default for KeyContext.alg and GemstoneKeyRecord.data_alg.

Returns:

Algorithm id string (currently RECOMMENDED_DATA_ALG).

Return type:

str

gemstone_utils.crypto.require_supported_sym_alg(alg)

Parameters:

alg (str)

Return type:

SymAlgSpec

gemstone_utils.crypto.sym_alg_key_length(alg)

Return the required key length in bytes for a registered algorithm.

Parameters:

alg (str) – Registered symmetric algorithm id.

Returns:

Key length in bytes.

Raises:

ValueError – If alg is not registered.

Return type:

int