gemstone_utils.encrypted_fields

Encrypted-field wire format and string encrypt/decrypt helpers.

gemstone_utils.encrypted_fields.decrypt_string(value, keyctx)[source]

Decrypt a wire string with keyctx.

Parameters:

  • value (str | None) – Wire string, or None.

  • keyctx (KeyContext) – Data key context matching segment 2 and algorithm.

Returns:

Decrypted UTF-8 string, or None if value is None.

Raises:

ValueError – If algorithm or key id does not match keyctx, or decrypt fails.

Return type:

str | None

gemstone_utils.encrypted_fields.encrypt_string(plaintext, keyctx)[source]

Encrypt a UTF-8 string with keyctx.

Parameters:

  • plaintext (str | None) – String to encrypt, or None.

  • keyctx (KeyContext) – Active data key context.

Returns:

Wire string, or None if plaintext is None.

Return type:

str | None

gemstone_utils.encrypted_fields.format_encrypted_field(alg, keyid, blob, params=None)[source]

Build the five-part encrypted-field wire string.

Format: $<alg>$<keyid>$<params_b64>$<blob_b64>.

Parameters:

  • alg (str) – Registered symmetric algorithm id.

  • keyid (str) – Canonical UUID string for the logical DEK.

  • blob (bytes) – Ciphertext blob.

  • params (Dict[str, Any] | None) – Algorithm parameters JSON object (default empty dict).

Returns:

Wire string suitable for storage or resolve_secret post-processing.

Raises:

ValueError – If alg is unsupported or keyid is not a valid UUID.

Return type:

str

gemstone_utils.encrypted_fields.is_encrypted_prefix(value)[source]

Return whether value looks like an encrypted-field wire string.

Parameters:

value (str) – Candidate string.

Returns:

True if value starts with $<registered_alg>$....

Return type:

bool

gemstone_utils.encrypted_fields.parse_encrypted_field(value)[source]

Parse a five-part (or legacy four-part) encrypted-field wire string.

Parameters:

value (str) – Wire string beginning with $.

Returns:

(alg_id, keyid, params, blob) where keyid is canonical UUID text.

Raises:

ValueError – If the format is invalid or the algorithm id is unsupported.

Warns:

DeprecationWarning – For legacy four-part wires without a params segment.

Return type:

Tuple[str, str, Dict[str, Any], bytes]