Module envelope 

Keys and the encryption that protects every stored body.

Structs

Key

A 256-bit key. Its bytes live only in a page of their own that is locked in memory, so they never reach swap, and that core dumps leave out; they are zeroed when the key is dropped. A key cannot be copied, and Debug shows only its id.

OpenError

A sealed body or wrapped key did not open. It carries no detail, so a caller cannot tell which part was wrong.

Enums

Context

What a sealed or wrapped value belongs to. It is bound into the encryption, so a value moved to another tenant, uuid or version does not open.

KeyError

Why a key could not be made.

WrapLimit

Whether a key that has already wrapped wraps keys may wrap another.

Functions

catalog_key

The key of the catalog that parent protects: the master key’s for server.sqlite, a tenant key’s for that tenant’s catalog. It is HKDF-SHA256 of the parent with no salt and the info vcon-server/v1 catalog, made in a locked page of its own and never stored.

disable_core_dumps

Stops this process from writing core dumps: the core size limit is set to zero and the process is marked not dumpable, which also stops other processes of the same user from reading its memory. Neither is enough on its own: the limit is not enforced when core dumps are piped to a program, and a host with suid_dumpable set to 2 still dumps processes that are not dumpable. Each key’s page is left out of core dumps as well.

lock_all_memory

Locks every page of this process in memory, now and as it grows, so nothing it holds can reach swap: not AWS-LC’s expanded keys, which live in its own allocations for the length of one call, and not plaintext bodies. It fails if the lock limit is too low; the operator then raises it (for example LimitMEMLOCK=infinity under systemd).

open

Decrypts a blob made by seal with the same key and context. Any change to the blob, the context or the key is an error, never partial plaintext.

rewrap

Moves a wrapped key from old to new, keeping its context: the rotation step. The plain key exists only in its own locked page in between, and what it protects is never re-encrypted.

seal

Encrypts plaintext under data_key, bound to ctx, with a random nonce. The blob is the format byte, the nonce, the ciphertext and the tag.

unwrap

Unwraps a key made by wrap with the same wrapping key and context. It is opened straight into the new key’s own locked page, so the plain key is never anywhere else; on any error that page is dropped, and so zeroed.

wrap

Wraps key under wrapping, bound to ctx: a blob like seal’s, whose plaintext is the key.

wrap_limit

The wrap-count limit for one wrapping key. Each wrap uses a random nonce, and NIST SP 800-38D 8.3 allows at most 2^32 such encryptions under one key, so a key that has made 2^32 wraps makes no more. The warning starts at half that.