cadrumo.adapters.persistence.storage.crypto.encrypted_columns module¶

SQLAlchemy deterministic lookup type and secure-object AEAD helpers.

HashedLookup provides deterministic HMAC-SHA256 keyed by a: sub-key derived from the master key plus a stable context. Storage type is LargeBinary (32 bytes). Use this column when consumers need WHERE column = ? lookups without leaking plaintext.

The secure-object helpers bind namespace, object_key digest, and schema_version into payload AEAD associated data so ciphertext copied across rows fails authentication.

All decorators and helpers resolve key bytes through get_active_master_key() on the active BucketSession. Tests use EphemeralBucketSession, whose context manager enters a real session without touching the OS keychain or file backend.

Secure-object payloads use row-identity AAD.

secure_object_payload_aad(namespace, object_key_digest, schema_version)[source]¶

Bind a secure-object row’s identity into its payload AEAD associated data.

The associated data length-prefixes the namespace, the object_key HMAC digest, and the schema version so the AEAD authentication tag is valid only for the exact row that produced the ciphertext. A ciphertext copied into a different (namespace, object_key) row fails the tag and refuses to decrypt, closing the at-rest row-substitution gap.

Return type:

bytes

Parameters:

namespace (str)
object_key_digest (bytes)
schema_version (int)

secure_object_key_digest(object_key)[source]¶

Return the stored object_key digest for a natural or pre-digested key.

Mirrors the HashedLookup column’s bind behaviour so the digest used to build the payload AAD at write time matches the digest persisted in the object_key column (and therefore the value reconstructed on read).

Return type:: bytes
Parameters:: object_key (str | bytes)

encrypt_secure_object_payload(plaintext, *, associated_data)[source]¶

Encrypt a secure-object payload under the active DEK, bound to associated_data.

Return type:

bytes

Parameters:

plaintext (bytes)
associated_data (bytes)

decrypt_secure_object_payload(wire, *, associated_data)[source]¶

Decrypt a row-AAD-bound secure-object payload; raises on a tag mismatch.

Return type:

bytes

Parameters:

wire (bytes)
associated_data (bytes)

class HashedLookup(*args, **kwargs)[source]¶

Bases: TypeDecorator

Deterministic HMAC-SHA256 keyed by a master-key-derived sub-key.

Storage type is LargeBinary (32 bytes). The HMAC key is derived from the master key via HKDF-SHA256 with a stable context, so the same plaintext maps to the same digest across processes that share the master key. The plaintext is NEVER recoverable from the digest.

Bind accepts a str (digested via compute()) or already- computed bytes (pass-through after size validation). Result is always the raw 32-byte digest.

Use cases:

Indexable lookup of an encrypted natural key (e.g. a secret identifier whose plaintext lives in a sibling separately encrypted payload). Consumers query WHERE lookup_column = "plaintext" (the str is digested at bind time) or WHERE lookup_column = HashedLookup.compute(...).
Idempotency keys keyed by sensitive content where the digest is acceptable as the storage key.

Security note: deterministic encryption / hashing is only safe when the consumer accepts that two equal plaintexts produce equal digests (they do, by design; that is the point). Do NOT use this decorator for low-entropy plaintexts (e.g. yes/no flags, short enumerations) — a frequency analysis on the digest column would leak the plaintext distribution.

Parameters:

args (Any)
kwargs (Any)

impl¶: alias of LargeBinary

cache_ok: Optional[bool]¶

Indicate if statements using this ExternalType are “safe to cache”.

The default value None will emit a warning and then not allow caching of a statement which includes this type. Set to False to disable statements using this type from being cached at all without a warning. When set to True, the object’s class and selected elements from its state will be used as part of the cache key. For example, using a TypeDecorator:

class MyType(TypeDecorator):
    impl = String

    cache_ok = True

    def __init__(self, choices):
        self.choices = tuple(choices)
        self.internal_only = True

The cache key for the above type would be equivalent to:

>>> MyType(["a", "b", "c"])._static_cache_key
(<class '__main__.MyType'>, ('choices', ('a', 'b', 'c')))

The caching scheme will extract attributes from the type that correspond to the names of parameters in the __init__() method. Above, the “choices” attribute becomes part of the cache key but “internal_only” does not, because there is no parameter named “internal_only”.

The requirements for cacheable elements is that they are hashable and also that they indicate the same SQL rendered for expressions using this type every time for a given cache value.

To accommodate for datatypes that refer to unhashable structures such as dictionaries, sets and lists, these objects can be made “cacheable” by assigning hashable structures to the attributes whose names correspond with the names of the arguments. For example, a datatype which accepts a dictionary of lookup values may publish this as a sorted series of tuples. Given a previously un-cacheable type as:

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    this is the non-cacheable version, as "self.lookup" is not
    hashable.

    """

    def __init__(self, lookup):
        self.lookup = lookup

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self.lookup" ...

Where “lookup” is a dictionary. The type will not be able to generate a cache key:

>>> type_ = LookupType({"a": 10, "b": 20})
>>> type_._static_cache_key
<stdin>:1: SAWarning: UserDefinedType LookupType({'a': 10, 'b': 20}) will not
produce a cache key because the ``cache_ok`` flag is not set to True.
Set this flag to True if this type object's state is safe to use
in a cache key, or False to disable this warning.
symbol('no_cache')

If we did set up such a cache key, it wouldn’t be usable. We would get a tuple structure that contains a dictionary inside of it, which cannot itself be used as a key in a “cache dictionary” such as SQLAlchemy’s statement cache, since Python dictionaries aren’t hashable:

>>> # set cache_ok = True
>>> type_.cache_ok = True

>>> # this is the cache key it would generate
>>> key = type_._static_cache_key
>>> key
(<class '__main__.LookupType'>, ('lookup', {'a': 10, 'b': 20}))

>>> # however this key is not hashable, will fail when used with
>>> # SQLAlchemy statement cache
>>> some_cache = {key: "some sql value"}
Traceback (most recent call last): File "<stdin>", line 1,
in <module> TypeError: unhashable type: 'dict'

The type may be made cacheable by assigning a sorted tuple of tuples to the “.lookup” attribute:

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    The dictionary is stored both as itself in a private variable,
    and published in a public variable as a sorted tuple of tuples,
    which is hashable and will also return the same value for any
    two equivalent dictionaries.  Note it assumes the keys and
    values of the dictionary are themselves hashable.

    """

    cache_ok = True

    def __init__(self, lookup):
        self._lookup = lookup

        # assume keys/values of "lookup" are hashable; otherwise
        # they would also need to be converted in some way here
        self.lookup = tuple((key, lookup[key]) for key in sorted(lookup))

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self._lookup" ...

Where above, the cache key for LookupType({"a": 10, "b": 20}) will be:

>>> LookupType({"a": 10, "b": 20})._static_cache_key
(<class '__main__.LookupType'>, ('lookup', (('a', 10), ('b', 20))))

Added in version 1.4.14: - added the cache_ok flag to allow some configurability of caching for TypeDecorator classes.

Added in version 1.4.28: - added the ExternalType mixin which generalizes the cache_ok flag to both the TypeDecorator and UserDefinedType classes.