macula_group_event (macula v13.3.0)

View Source

An event sealed under a sealed group's epoch (plans/DESIGN_E2E_SEALED_PUBSUB.md §7, test/vectors/E2E_SEAL_V1.md).

A publisher seals under its own subkey of the epoch key, k_pub = event_key(k_g, publisher), so no two publishers ever share a key, with a fresh 96-bit random nonce, bound by the AAD to the publication's routing fields (realm, topic, publisher, seq, published_at). The plaintext is the payload's deterministic CBOR, as the tbs would carry it in the clear. The sealed map names the epoch by its id (key_id) and carries the nonce; a PUBLISH carries it in place of payload (macula_frame:publish/2).

Both functions are pure: which epoch to seal under, or to open with, is the keyring's (macula_group_keyring).

Summary

Types

fields/0

What opening reads of a publication: the fields it was sealed with, and its seal. A verified publication is one.

sealed_event/0

Functions

open(Epoch, Publication)

The payload of a verified publication sealed under Epoch, in the shape a clear payload arrives in. tag_invalid when it does not open: another epoch's key, a routing field that is not the one it was sealed with, or a byte of it changed. not_sealed for a publication in the clear.

seal(_, Fields, Payload)

The sealed map of an event carrying Payload, for a publication with Fields, under Epoch.

Types

fields/0

-type fields() ::
          #{publisher := <<_:256>>,
            realm := <<_:256>>,
            topic := binary(),
            seq := non_neg_integer(),
            published_at := non_neg_integer()}.

What opening reads of a publication: the fields it was sealed with, and its seal. A verified publication is one.

sealed_event/0

-type sealed_event() ::
          #{publisher := <<_:256>>,
            realm := <<_:256>>,
            topic := binary(),
            seq := non_neg_integer(),
            published_at := non_neg_integer(),
            sealed => macula_frame:sealed(),
            atom() => term()}.

Functions

open(Epoch, Publication)

-spec open(macula_group_epoch:epoch(), sealed_event()) ->
              {ok, term()} | {error, tag_invalid | not_sealed}.

The payload of a verified publication sealed under Epoch, in the shape a clear payload arrives in. tag_invalid when it does not open: another epoch's key, a routing field that is not the one it was sealed with, or a byte of it changed. not_sealed for a publication in the clear.

seal(_, Fields, Payload)

-spec seal(macula_group_epoch:epoch(), fields(), term()) ->
              {ok, macula_frame:sealed()} | {error, {unsupported_payload_type, atom(), [term()]}}.

The sealed map of an event carrying Payload, for a publication with Fields, under Epoch.