Macro derive_deftly_template_NetdocParseableSignatures 

macro_rules! derive_deftly_template_NetdocParseableSignatures {
    ({ $($driver:tt)* } [$($aoptions:tt)*] ($($future:tt)*) $($tpassthrough:tt)*) => { ... };
    ($($wrong:tt)*) => { ... };
}

Derive NetdocParseable for the signatures section of a network document

This type is the signatures section of another document. Signature sections have no separate intro keyword: every field is structural and they are recognised in any order.

This signatures sub-document will typically be included in a FooUnverified struct derived with NetdocUnverified, rather than included anywhere manually.

Expected input structure

Should be applied named-field struct, where each field implements SignatureItemParseable, or is a SignatureItemParseable in Vec or BTreeSet or Option.

Attributes

• The following top-level attributes are supported: #[deftly(netdoc(debug))]

• The following field-level attributes are supported: #[deftly(netdoc(keyword = STR))] #[deftly(netdoc(default))] #[deftly(netdoc(single_arg))] #[deftly(netdoc(with = MODULE))] #[deftly(netdoc(flatten))] #[deftly(netdoc(skip))]

Signature item ordering, and signatures covering signatures

The derived code does not impose any mutual ordering of signatures. If signatures are independent, hashing can be done with SignedDocumentBody (from SignatureHashInputs::body).

In sane netdoc signature scheme, no signatures would cover other signatures, and there would be no ordering requirement on signatures on the same document. A relying party would verify the signatures that they are proposing to rely on (which would generally include signatures for one algorithm, not several) and ignore the others.

(Such a signature, which also does not include any of its own item encoding in its hash, is called Orderly. See SignedDocumentBody.)

Unfortunately, many Tor netdocs have signature schemes which are not sane (by this definition).

When signatures are specified to cover other signatures, the signature item implementation must contain ad-hoc code in SignatureItemParseable::from_unparsed_and_body. to hash not only the body, but also the prior signatures. Methods on SignatureHashInputs are available to get the relevant parts of the input document text (eg, document_sofar).

When the spec states a required ordering on signature items, this should be enforced by ad-hoc code in implementation(s) of SignatureItemParseable. The implementation should use HashAccu to store any necessary state. Usually, this can be achieved by using the same Rust struct for the HashAccu of each of the signature items: that will make the signature hashes computed so far, for items seen so far, visible to subsequent items; the subsequent items can check that the prior items filled in the hash, thus imposing an ordering.

Alternatively, the ordering could be enforced in the user-supplied ad-hoc verify function(s) on FooUUnverified.

Note that this enforcement should be done for protocol compliance and availability reasons, but is not a security issue. There is not a security risk from accepting documents some of whose signatures aren’t covered by other signatures even though the protocol specifies they should be: relying parties verify the signatures but do not treat them as trusted data. So there is no engineered safeguard against failing to implement signature item ordering checks.

This is a derive_deftly template. Do not invoke it directly. To use it, write: #[derive(Deftly)] #[derive_deftly(NetdocParseableSignatures)].