The stored form of a personal value: a JSON object, never a string.
{"$pf": 1, "k": "<key_id>", "s": "<subject_id>", "n": "<nonce>", "c": "<ciphertext+tag>"}An object can never be confused with the string a field held before, which a prefixed string
could be for a field a person types into. $pf is the format version, and its presence is
the shape test. A deserialized event body has atom keys and metadata string keys, so the test
takes both. k names the data key, and s the subject, so that a read never has to work out
the subject again. Both stay in clear, as a read needs them to find the key.
The primitive
AES-256-GCM through :crypto.crypto_one_time_aead/7, with a 16-byte tag. Each encryption
takes a fresh random 12-byte nonce from :crypto.strong_rand_bytes/1. n and c are base64,
and c is the ciphertext followed by the tag.
The plaintext is the value's JSON, so a value that is not a string keeps its type.
What the additional data binds
The additional data is "pf1", the key id, the stream, the event type and the field, joined
with a NUL byte. So a value does not decrypt under another key, in another stream, in another
event type, or in another field:
The stream is the source stream,
RecordedEvent.stream_id, on every read.The event type is the stored string,
EventData.event_typeandRecordedEvent.event_type, so it is unchanged by an upcaster. A snapshot's is the literal"snapshot".The field is the field's name. A metadata entry's is
"metadata.<key>", so a value can't move between body and metadata. A snapshot's is"<state_field>.<entry_key>"for a list entry and"<state_field>"for a scalar.
It does not bind the event id. Someone with write access to the store can copy a value between two events of the same type, stream and field, and it will decrypt.
It does not bind the subject either: s is checked by the key it leads to, whose id must
equal k.
Summary
Types
Where a value is stored: its stream, its event type and its field.
An envelope's parts, decoded.
Functions
Decrypts an envelope, answering :error when the key, the location or the bytes do not match.
Encrypts a value under key for the given location, with a fresh nonce.
Does this value have the envelope's shape? A map with $pf does, well formed or not.
The key id an envelope names.
Reads an envelope's parts. A map that has the shape and not the parts is :error, never a
value: exactly $pf at this version, k, s, n and c, each decoding to its size.
The subject an envelope names.
Types
Functions
Decrypts an envelope, answering :error when the key, the location or the bytes do not match.
@spec encrypt(term(), {String.t(), binary()}, String.t(), location()) :: {:ok, map()} | {:error, :personal_field_not_encodable}
Encrypts a value under key for the given location, with a fresh nonce.
Answers {:error, :personal_field_not_encodable} for a value with no JSON form, never a raise
that could carry it.
Does this value have the envelope's shape? A map with $pf does, well formed or not.
The key id an envelope names.
Reads an envelope's parts. A map that has the shape and not the parts is :error, never a
value: exactly $pf at this version, k, s, n and c, each decoding to its size.
The subject an envelope names.