macula_signed_object (macula v11.4.0)
View SourceThe signed objects of the post-quantum records and frames, as DESIGN_PQ_SIGNED_FRAMES_AND_RECORDS.md lays them out.
A signed object is {key, tbs, signature} when the signer's key travels with it, and {tbs, signature} when the verifier already holds the key. Either way the signature covers Label || 0x00 || SHA-384(key as carried) || tbs, so each signature is bound to its key, also when the key does not travel, and to the label of the structure it signs.
A verifier reads an object in order: the object holds exactly the keys of its shape, each a byte string; a carried key is in the carried form of the verifier's profile; the signature verifies over tbs as received, with the profile's algorithm; only then is tbs decoded under the decoding rule, and it must be a map whose alg names the profile's algorithm. alg is checked and never selects an algorithm. Nothing is re-encoded.
Summary
Functions
The alg a profile's signed objects name.
Read an object from its CBOR map under the decoding rule: exactly the keys of one shape, each a byte string.
The CBOR map of an object, with text keys.
Sign fields under a label with a key. The fields gain alg for the key's profile, and the object carries the key as carried.
Sign fields under a label with a key, for a verifier that already holds the key. The signature still covers the key's hash.
Verify an object that carries its key, under a label and the verifier's profile. Returns the key, the tbs bytes as received and the decoded fields. Malformed input is refused, never raised on.
Verify an object whose key the verifier holds, under a label, that key and the verifier's profile. Returns the tbs bytes as received and the decoded fields.
Types
Functions
-spec alg(macula_crypto_profile:profile()) -> binary().
The alg a profile's signed objects name.
-spec decode(binary()) -> {ok, object() | held_object()} | {error, malformed}.
Read an object from its CBOR map under the decoding rule: exactly the keys of one shape, each a byte string.
-spec encode(object() | held_object()) -> binary().
The CBOR map of an object, with text keys.
-spec sign(binary(), map(), macula_node_keys:node_key()) -> object().
Sign fields under a label with a key. The fields gain alg for the key's profile, and the object carries the key as carried.
-spec sign_held(binary(), map(), macula_node_keys:node_key()) -> held_object().
Sign fields under a label with a key, for a verifier that already holds the key. The signature still covers the key's hash.
-spec verify(binary(), term(), macula_crypto_profile:profile()) -> {ok, #{key := binary(), tbs := binary(), fields := map()}} | {error, refusal()}.
Verify an object that carries its key, under a label and the verifier's profile. Returns the key, the tbs bytes as received and the decoded fields. Malformed input is refused, never raised on.
-spec verify_held(binary(), term(), binary(), macula_crypto_profile:profile()) -> {ok, #{tbs := binary(), fields := map()}} | {error, refusal()}.
Verify an object whose key the verifier holds, under a label, that key and the verifier's profile. Returns the tbs bytes as received and the decoded fields.