The envelope and field-level encryption

Audience: developers · Read route: rebuild · Reflects specification v0.1

An envelope is the fixed shape every record takes on the wire, so that any two implementations read it identically. It is a versioned set of typed tiers, encoded with a deterministic canonical encoding (RFC 8949). Deterministic means that the same logical record produces the same bytes on any conforming implementation, which is what lets two parties compute identical commitments and identical proofs from it. If the encoding were not byte-exact, two honest implementations could disagree about what a record commits to.

The shape of a recorded action

Every change is a recorded action with a fixed shape. It carries an identifier, the name of the method it invokes, the arguments to that method, the actor that signed it, the time carried inside the action, and an anchor reference to its position on the public audit layer. That is enough for any party to reconstruct and replay the action even though it did not originate it. The exact rules for this shape are in the specification, Section 3.1; this page describes the shape, it does not restate the rules.

Per-field encryption and selective disclosure

Encryption is on by default and applied per field. Each field is encrypted independently and carries its own set of receivers, so different parties can be granted access to different fields of the same record. Selective disclosure is then simply a matter of granting a counterparty only the field keys it is entitled to, and nothing else. Whatever a field's placement, the record carries a cryptographic commitment to that field, so a party can confirm the field exists and has not changed even when it holds no key to read it.

Three tiers of access

Access to a field is not binary. The envelope supports three tiers, so a party can be given exactly the level it needs.

1. Hash-only: verify that the field exists and is unchanged, without seeing anything about it. Enough for an auditor confirming integrity.
2. Metadata: see the signatures and the surrounding metadata, who recorded the field and when, without the value.
3. Full: the actual value.

The three envelope layers

The envelope wraps a field three times, and each wrap is what makes a tier possible.

At Layer 0 the per-field content key is derived from the field's own content, so any party that legitimately holds the content can rederive the key and verify the field for itself; receivers are granted access by wrapping that key to their public key. Layer 1 signatures prove who recorded the action and can carry more than one signer. Layer 2 controls whether the metadata is visible at all. The determinism of the Layer 0 derivation has a deliberate cryptographic consequence, which is treated where it belongs, under the forward-secrecy trade-off on Keys and derivation.

The concrete parameters (the derivation contexts, the parameters of the key-stretching and authenticated-encryption primitives, and the byte-exact encoding profile) are not fixed in this prose. They are pinned by the docv2-envelope, cbor-det-v1, and placement test-vector suites named in the specification, Section 6. A rebuilder matches those vectors once they are published; only the interop-load-bearing shape is described here.

The placement descriptor

A field does not have to live inside the record. Each field carries a placement descriptor stating where its encrypted content lives, and the record carries the commitment either way.

• In-record: the encrypted bytes are part of the recorded action itself. Best for compact fields such as text, identifiers, and hashes.
• Overlay: the encrypted bytes go to a storage channel, and the action carries a reference plus the content hash. Best for medium fields such as images and attestations.
• External: the bytes never leave a party's own storage, and the action carries only the hash and the receivers' keys for a future fetch. Best for large or regulated content.

The overlay used for placement is a storage channel, which is a different role from the overlay used as a routing fabric for addressing and discovery. That distinction is drawn on Addressing and discovery.

A worked access matrix

One record can serve many parties at once. The example below extends the overview's table with a placement column and an access-tier column, so you can see how disclosure, placement, and tier combine. The roles are generic; read them as the shape of an access model, not a specific deployment.

Each party sees exactly the fields it is entitled to and nothing more, and the auditor confirms that no field has been altered without being able to read any of them.

Provisional item PROV-3 (placement-channel ownership), pending technical review. The placement descriptor semantics above (selecting whether a field's content sits in the record, in overlay storage, or in external storage) are normative. The ownership boundary of overlay-versus-external storage, and who operates each store, are operator-tier configuration and are out of scope for this reference. This boundary is subject to technical review; see the specification, Section 9, PROV-3. The consortium-membership half of PROV-3 is treated on Addressing and discovery.

The rules behind this page

The MUST rules for deterministic canonical encoding, the recorded-action shape, per-field independent encryption, the placement descriptor, and the per-field commitment are in the specification, Sections 3.1 and 3.3. This page explains the mechanism behind them.