The Gordian Envelope Structured Data Format
draft-mcnally-envelope-05
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft whose latest revision state is "Active".
|
|
|---|---|---|---|
| Authors | Wolf McNally , Christopher Allen | ||
| Last updated | 2023-08-20 (Latest revision 2023-08-19) | ||
| RFC stream | (None) | ||
| Formats | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-mcnally-envelope-05
Network Working Group W. McNally
Internet-Draft C. Allen
Intended status: Experimental Blockchain Commons
Expires: 21 February 2024 20 August 2023
The Gordian Envelope Structured Data Format
draft-mcnally-envelope-05
Abstract
Gordian Envelope specifies a structured format for hierarchical
binary data focused on the ability to transmit it in a privacy-
focused way, offering support for privacy as described in RFC 6973
and human rights as described in RFC 8280. Envelopes are designed to
facilitate "smart documents" and have a number of unique features
including: easy representation of a variety of semantic structures, a
built-in Merkle-like digest tree, deterministic representation using
CBOR, and the ability for the holder of a document to selectively
elide specific parts of a document without invalidating the digest
tree structure. This document specifies the base Envelope format,
which is designed to be extensible.
Discussion Venues
This note is to be removed before publishing as an RFC.
Source for this draft and an issue tracker can be found at
https://github.com/BlockchainCommons/envelope-internet-draft.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 21 February 2024.
McNally & Allen Expires 21 February 2024 [Page 1]
Internet-Draft Envelope August 2023
Copyright Notice
Copyright (c) 2023 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Elision Support . . . . . . . . . . . . . . . . . . . . . 4
1.2. Extensions . . . . . . . . . . . . . . . . . . . . . . . 4
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. Envelope Format Specification . . . . . . . . . . . . . . . . 5
3.1. Leaf Case Format . . . . . . . . . . . . . . . . . . . . 6
3.2. Elided Case Format . . . . . . . . . . . . . . . . . . . 7
3.3. Node Case Format . . . . . . . . . . . . . . . . . . . . 7
3.4. Assertion Case Format . . . . . . . . . . . . . . . . . . 8
3.5. Wrapped Case Format . . . . . . . . . . . . . . . . . . . 8
4. Computing the Digest Tree . . . . . . . . . . . . . . . . . . 8
4.1. Leaf Digest Calculation . . . . . . . . . . . . . . . . . 9
4.2. Elided Digest Calculation . . . . . . . . . . . . . . . . 9
4.3. Node Digest Calculation . . . . . . . . . . . . . . . . . 10
4.4. Assertion Digest Calculation . . . . . . . . . . . . . . 12
4.5. Wrapped Digest Calculation . . . . . . . . . . . . . . . 13
5. Envelope Hierarchy . . . . . . . . . . . . . . . . . . . . . 13
5.1. Leaf Case . . . . . . . . . . . . . . . . . . . . . . . . 16
5.2. Elided Case . . . . . . . . . . . . . . . . . . . . . . . 16
5.3. Node Case . . . . . . . . . . . . . . . . . . . . . . . . 17
5.4. Assertion Case . . . . . . . . . . . . . . . . . . . . . 18
5.5. Wrapped Case . . . . . . . . . . . . . . . . . . . . . . 19
6. Reference Implementations . . . . . . . . . . . . . . . . . . 19
7. Security Considerations . . . . . . . . . . . . . . . . . . . 19
7.1. CBOR Considerations . . . . . . . . . . . . . . . . . . . 20
7.2. Validation Requirements . . . . . . . . . . . . . . . . . 20
7.3. Choice of SHA-256 Hash Primitive . . . . . . . . . . . . 20
7.4. Correlated Digests . . . . . . . . . . . . . . . . . . . 20
7.5. RFC 6973 Considerations . . . . . . . . . . . . . . . . . 20
7.6. RFC 8280 Considerations . . . . . . . . . . . . . . . . . 21
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21
8.1. CBOR Tags . . . . . . . . . . . . . . . . . . . . . . . . 21
McNally & Allen Expires 21 February 2024 [Page 2]
Internet-Draft Envelope August 2023
8.2. Media Type . . . . . . . . . . . . . . . . . . . . . . . 21
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 22
9.1. Normative References . . . . . . . . . . . . . . . . . . 22
9.2. Informative References . . . . . . . . . . . . . . . . . 23
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 24
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24
1. Introduction
Gordian Envelope was designed with two key goals in mind: to be
_Structure-Ready_, allowing for the reliable and interoperable
encoding and storage of information; and to be _Privacy-Ready_,
ensuring that transmission of that data can occur in a privacy-
protecting manner.
* *Structure-Ready.* Gordian Envelope is designed as a "smart
document": a set of information about a subject. More than that,
it's a meta-document that can contain or refer to other documents.
It can support multiple data structures, from single data items,
to simple hierarchies, to labeled property graphs, semantic
triples, and other forms of structured graphs. Though its
fundamental structure is a tree, it can be used to create Directed
Acyclic Graphs (DAGs) through references within or between
Envelopes.
* *Privacy-Ready.* Gordian Envelope protects privacy by affording
progressive trust, allowing for holders (not just issuers) to
minimally disclose information by using elision, and then to
optionally increase that disclosure over time. Progressive trust
in Gordian Envelopes is accomplished through the hashing of all
elements, which also creates foundational support for signing and
encryption. This directly addresses the data minimization
suggested by "Privacy Considerations for Internet Protocols"
[RFC6973] and also addresses topics such as Privacy,
Accessibility, Censorship Resistance, Reliability, and Integrity,
which are listed as guidelines in "Research into Human Rights
Protocol Considerations" [RFC8280].
The following architectural decisions support these goals:
* *Structured Merkle Tree.* A variant of the Merkle Tree [MERKLE]
structure is created by hashing the elements in the Envelope into
a tree of digests. (In this "structured Merkle Tree", all nodes
contain both semantic content and digests, rather than semantic
content being limited to leaves.)
McNally & Allen Expires 21 February 2024 [Page 3]
Internet-Draft Envelope August 2023
* *Deterministic Representation.* There is only one way to encode
any semantic representation within a Gordian Envelope. This is
accomplished through the use of Deterministic CBOR [DCBOR] and the
sorting of the Envelope's assertions into a lexicographic order
(not to be confused with sorting a CBOR encoding's map keys). Any
Envelope that doesn't follow these strict rules will be rejected;
as a result, separate actors assembling envelopes from the same
information will converge on the same encoded structure.
1.1. Elision Support
* *Holder-initiated Elision.* Elision can be performed by the Holder
of a Gordian Envelope, not just the Issuer.
* *Granular Elision.* Elision can be performed on any data within an
Envelope including subjects, predicates and objects of assertions,
assertions as a whole, and envelopes as a whole. This allows each
entity to elide data as is appropriate for the management of their
personal or business risk.
* *Progressive Trust.* The elision mechanics in Gordian Envelopes
allow for progressive trust, where increasing amounts of data may
be revealed over time.
* *Consistent Hashing.* Even when elided, digests for those parts of
the Gordian Envelope remain the same. So constructs such as
signatures remain verifiable even for elided documents.
* *Reversible Elision.* Elision can be reversed by the Holder of a
Gordian Envelope, which means removed information can be
selectively replaced without changing the digest tree.
1.2. Extensions
This document is the base specification for Gordian Envelope, which
is stable and useful by itself. However it is also designed to
support optional extensions, to be specified in separate documents.
A few such extensions may require adding new Envelope cases: these
will extend the Envelope format itself, and will therefore need to be
supported by Envelope encoders. Examples include symmetric
encryption and compression which (like elision) allow for the
transformation of Envelope elements without changing the digest tree.
However, most extensions will be specified by defining the semantics
of new subjects, predicates, and objects. Such extensions do not
require extending the Envelope format but may be supported by tools.
Examples include signatures, public-key encryption, digest
McNally & Allen Expires 21 February 2024 [Page 4]
Internet-Draft Envelope August 2023
decorrelation, intra- and inter-Envelope references using digests,
expression evaluation and distributed function calls, diffing and
merging envelopes, and inclusion proofs.
Building on this base specification, we expect a robust ecosystem of
extensions to emerge, facilitating a wide variety of applications.
2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
This specification makes use of the following terminology:
byte Used in its now-customary sense as a synonym for "octet".
element Synonymous with "sub-Envelope". An Envelope is a tree of
elements.
image The source data from which a cryptographic digest is
calculated.
3. Envelope Format Specification
This section is normative and specifies the Gordian Envelope binary
format in terms of its CBOR components and their sequencing. The
formal language used is the Concise Data Definition Language (CDDL)
[RFC8610]. To be considered a well-formed Envelope, a sequence of
bytes MUST conform to the Gordian dCBOR deterministic CBOR profile
[DCBOR] and MUST conform to the specifications in this section.
An Envelope is a tagged enumerated type with five cases. Here is the
entire CDDL specification for the base Envelope format. Each case is
discussed in detail below:
McNally & Allen Expires 21 February 2024 [Page 5]
Internet-Draft Envelope August 2023
envelope = #6.200(envelope-content)
envelope-content =
leaf /
elided /
node /
assertion /
wrapped
leaf = #6.24(bytes .dcbor any)
elided = sha256-digest
sha256-digest = bytes .size 32
node = [subject, + assertion-element]
subject = envelope-content
assertion-element = assertion / elided-assertion
elided-assertion = elided ; MUST represent an assertion.
assertion = { predicate => object }
predicate = envelope-content
object = envelope-content
wrapped = envelope
Some of these cases create a hierarchical, recursive structure by
including children that are themselves Envelopes. Two of these cases
(leaf and elided) have no children. The node case adds one or more
assertions to the Envelope, each of which is a child. The assertion
case is a predicate/object pair, both of which are children. The
wrapped case is used to wrap an entire Envelope including its
assertions (its child), so that assertions can be made about the
wrapped Envelope as a whole.
3.1. Leaf Case Format
A leaf case is used when the Envelope contains only user-defined CBOR
content. It is tagged using #6.24, per [RFC8949] §3.4.5.1, "Encoded
CBOR Data Item". See §4 of [CCDE] for CDDL support for dCBOR.
leaf = #6.24(bytes .dcbor any)
The leaf case can be discriminated from other Envelope case arms by
the fact that it is the only one that is tagged using #6.24.
McNally & Allen Expires 21 February 2024 [Page 6]
Internet-Draft Envelope August 2023
To preserve deterministic encoding, authors of application-level data
formats based on Envelope MUST only encode CBOR that conforms to
dCBOR [DCBOR] in the leaf case. Care must be taken to ensure that
leaf dCBOR follows best practices for deterministic encoding, such as
clearly specifying when tags for nested structures MUST or MUST NOT
be used.
3.2. Elided Case Format
An elided case is used as a placeholder for an element that has been
elided. It consists solely of the elided Envelope's digest.
elided = sha256-digest
sha256-digest = bytes .size 32
The elided case can be discriminated from other Envelope case arms by
the fact that it is the only one that is a CBOR byte string and
always has a length of 32 bytes.
If the method of producing the digest ever changes, the top-level
Envelope tag #6.200 MUST be changed to a new value, and the new
method MUST be specified in a new document. This is to ensure that
the digest tree remains consistent.
3.3. Node Case Format
A node case is encoded as a CBOR array. A node case MUST be used
when one or more assertions are present on the Envelope. A node case
MUST NOT be present when there is not at least one assertion.
The first element of the array is the Envelope's subject, followed by
one or more assertion-elements, each of which MUST either be an
assertion or an elided-assertion.
The assertion-elements MUST appear in ascending lexicographic order
by their digest (not to be confused with sorting a CBOR map's keys).
The array MUST NOT contain any assertion-elements with identical
digests.
For an Envelope to be valid, any elided-assertion Envelopes in the
node assertions MUST, if and when unelided, be found to be actual
assertion case Envelopes having the same digest.
node = [subject, + assertion-element]
subject = envelope-content
assertion-element = assertion / elided-assertion
elided-assertion = elided ; MUST represent an assertion.
McNally & Allen Expires 21 February 2024 [Page 7]
Internet-Draft Envelope August 2023
The node case can be discriminated from other Envelope case arms by
the fact that it is the only one that is a CBOR array.
3.4. Assertion Case Format
An assertion case is used for each of the assertions on the subject
of an Envelope. It is encoded as a CBOR map with exactly one map
entry:
* The key of the map entry is the Envelope representing the
predicate of the assertion.
* The value of the map entry is the Envelope representing the object
of the assertion.
assertion = { predicate => object }
predicate = envelope-content
object = envelope-content
The assertion case can be discriminated from other Envelope case arms
by the fact that it is the only one that is a CBOR map.
3.5. Wrapped Case Format
Assertions make semantic statements about an Envelope's subject. A
wrapped case is used where an Envelope, including all its assertions,
should be treated as a single element, e.g. for the purpose of adding
assertions to an Envelope as a whole, including its assertions.
wrapped = envelope
The wrapped case can be discriminated from other Envelope case arms
by the fact that it is the only one that is top-level CBOR Envelope,
always tagged with #6.200.
4. Computing the Digest Tree
This section specifies how the digests for each of the Envelope cases
are computed and is normative. The examples in this section may be
used as test vectors.
Each of the five enumerated Envelope cases produces an image which is
used as input to a cryptographic hash function to produce the digest
of its contents.
The overall digest of an Envelope is the digest of its specific case.
In this section:
McNally & Allen Expires 21 February 2024 [Page 8]
Internet-Draft Envelope August 2023
* digest(image) is the 32-byte hash produced by running the SHA-256
hash function on the input image.
* The .digest attribute is the digest of the named element computed
as specified herein.
* The || operator represents the concatenation of byte sequences.
Note that in the examples below, hexadecimal is shown for
readability. All the hexadecimal you see is converted to binary
before being hashed.
4.1. Leaf Digest Calculation
The leaf case consists of any CBOR object conforming to dCBOR
[DCBOR]. The Envelope image is the CBOR serialization of that
object:
digest(cbor)
*Example*
The CBOR serialization of the plaintext string "Hello" (not including
the quotes) is:
65 # text(5)
48656C6C6F # "Hello"
The following command line calculates the SHA-256 sum of this
sequence:
$ echo "6548656C6C6F" | xxd -r -p | shasum --binary --algorithm 256 | \
awk '{ print $1 }'
4d303dac9eed63573f6190e9c4191be619e03a7b3c21e9bb3d27ac1a55971e6b
Using the envelope command line tool [ENVELOPE-CLI], we create an
Envelope with this string as the subject and display the Envelope's
digest. The digest below matches the one above.
$ envelope subject "Hello" | envelope digest --hex
4d303dac9eed63573f6190e9c4191be619e03a7b3c21e9bb3d27ac1a55971e6b
4.2. Elided Digest Calculation
The elided case declares its digest to be the digest of the Envelope
for which it is a placeholder.
*Example*
McNally & Allen Expires 21 February 2024 [Page 9]
Internet-Draft Envelope August 2023
If we create the Envelope from the leaf example above, elide it, and
then request its digest:
$ envelope subject "Hello" | envelope elide | envelope digest --hex
4d303dac9eed63573f6190e9c4191be619e03a7b3c21e9bb3d27ac1a55971e6b
...we see that its digest is the same as its unelided form:
$ envelope subject "Hello" | envelope digest --hex
4d303dac9eed63573f6190e9c4191be619e03a7b3c21e9bb3d27ac1a55971e6b
4.3. Node Digest Calculation
The Envelope image of the node case is the concatenation of the
digest of its subject and the digests of its assertions sorted in
ascending lexicographic order.
With a node case, there MUST always be at least one assertion.
digest(subject.digest || assertion-0.digest ||
assertion-1.digest || ... || assertion-n.digest)
*Example*
We create four separate Envelopes and display their digests:
$ SUBJECT=`envelope subject "Alice"`
$ envelope digest --hex $SUBJECT
13941b487c1ddebce827b6ec3f46d982938acdc7e3b6a140db36062d9519dd2f
$ ASSERTION_0=`envelope subject assertion "knows" "Bob"`
$ envelope digest --hex $ASSERTION_0
78d666eb8f4c0977a0425ab6aa21ea16934a6bc97c6f0c3abaefac951c1714a2
$ ASSERTION_1=`envelope subject assertion "knows" "Carol"`
$ envelope digest --hex $ASSERTION_1
4012caf2d96bf3962514bcfdcf8dd70c351735dec72c856ec5cdcf2ee35d6a91
$ ASSERTION_2=`envelope subject assertion "knows" "Edward"`
$ envelope digest --hex $ASSERTION_2
65c3ebc3f056151a6091e738563dab4af8da1778da5a02afcd104560b612ca17
We combine the Envelopes into a single Envelope with three
assertions:
McNally & Allen Expires 21 February 2024 [Page 10]
Internet-Draft Envelope August 2023
$ ENVELOPE=`envelope assertion add envelope $ASSERTION_0 $SUBJECT | \
envelope assertion add envelope $ASSERTION_1 | \
envelope assertion add envelope $ASSERTION_2`
$ envelope $ENVELOPE
"Alice" [
"knows": "Bob"
"knows": "Carol"
"knows": "Edward"
]
$ envelope digest --hex $ENVELOPE
6255e3b67ad935caf07b5dce5105d913dcfb82f0392d4d302f6d406e85ab4769
Note that in the Envelope notation representation above, the
assertions are sorted alphabetically, with "knows": "Edward" coming
last. But internally, the three assertions are ordered by digest in
ascending lexicographic order, with "Carol" coming first because its
digest starting with 4012caf2 is the lowest, as in the tree formatted
display below:
$ envelope --tree $ENVELOPE
6255e3b6 NODE
13941b48 subj "Alice"
4012caf2 ASSERTION
db7dd21c pred "knows"
afb8122e obj "Carol"
65c3ebc3 ASSERTION
db7dd21c pred "knows"
e9af7883 obj "Edward"
78d666eb ASSERTION
db7dd21c pred "knows"
13b74194 obj "Bob"
To replicate this, we make a list of digests, starting with the
subject, and then sort each assertion's digest in ascending
lexicographic order:
13941b487c1ddebce827b6ec3f46d982938acdc7e3b6a140db36062d9519dd2f
4012caf2d96bf3962514bcfdcf8dd70c351735dec72c856ec5cdcf2ee35d6a91
65c3ebc3f056151a6091e738563dab4af8da1778da5a02afcd104560b612ca17
78d666eb8f4c0977a0425ab6aa21ea16934a6bc97c6f0c3abaefac951c1714a2
We then calculate the SHA-256 digest of the concatenation of these
four digests. Note that this is the same digest as the composite
Envelope's digest:
McNally & Allen Expires 21 February 2024 [Page 11]
Internet-Draft Envelope August 2023
echo "13941b487c1ddebce827b6ec3f46d982938acdc7e3b6a140db36062d9519dd2f\
4012caf2d96bf3962514bcfdcf8dd70c351735dec72c856ec5cdcf2ee35d6a91\
65c3ebc3f056151a6091e738563dab4af8da1778da5a02afcd104560b612ca17\
78d666eb8f4c0977a0425ab6aa21ea16934a6bc97c6f0c3abaefac951c1714a2" | \
xxd -r -p | shasum --binary --algorithm 256 | awk '{ print $1 }'
6255e3b67ad935caf07b5dce5105d913dcfb82f0392d4d302f6d406e85ab4769
$ envelope digest --hex $ENVELOPE
6255e3b67ad935caf07b5dce5105d913dcfb82f0392d4d302f6d406e85ab4769
4.4. Assertion Digest Calculation
The Envelope image of the assertion case is the concatenation of the
digests of the assertion's predicate and object, in that order:
digest(predicate.digest || object.digest)
*Example*
We create an assertion from two separate Envelopes and display their
digests:
$ PREDICATE=`envelope subject "knows"`
$ envelope digest --hex $PREDICATE
db7dd21c5169b4848d2a1bcb0a651c9617cdd90bae29156baaefbb2a8abef5ba
$ OBJECT=`envelope subject "Bob"`
$ envelope digest --hex $OBJECT
13b741949c37b8e09cc3daa3194c58e4fd6b2f14d4b1d0f035a46d6d5a1d3f11
$ ASSERTION=`envelope subject assertion "knows" "Bob"`
$ envelope digest --hex $ASSERTION
78d666eb8f4c0977a0425ab6aa21ea16934a6bc97c6f0c3abaefac951c1714a2
To replicate this, we make a list of the predicate digest and the
object digest, in that order:
db7dd21c5169b4848d2a1bcb0a651c9617cdd90bae29156baaefbb2a8abef5ba
13b741949c37b8e09cc3daa3194c58e4fd6b2f14d4b1d0f035a46d6d5a1d3f11
We then calculate the SHA-256 digest of the concatenation of these
two digests. Note that this is the same digest as the composite
Envelope's digest:
McNally & Allen Expires 21 February 2024 [Page 12]
Internet-Draft Envelope August 2023
echo "db7dd21c5169b4848d2a1bcb0a651c9617cdd90bae29156baaefbb2a8abef5ba\
13b741949c37b8e09cc3daa3194c58e4fd6b2f14d4b1d0f035a46d6d5a1d3f11" | \
xxd -r -p | shasum --binary --algorithm 256 | awk '{ print $1 }'
78d666eb8f4c0977a0425ab6aa21ea16934a6bc97c6f0c3abaefac951c1714a2
$ envelope digest --hex $ASSERTION
78d666eb8f4c0977a0425ab6aa21ea16934a6bc97c6f0c3abaefac951c1714a2
4.5. Wrapped Digest Calculation
The Envelope image of the wrapped case is the digest of the wrapped
Envelope:
digest(envelope.digest)
*Example*
As above, we note the digest of a leaf Envelope is the digest of its
CBOR:
$ envelope subject "Hello" | envelope digest --hex
4d303dac9eed63573f6190e9c4191be619e03a7b3c21e9bb3d27ac1a55971e6b
$ echo "6548656C6C6F" | xxd -r -p | shasum --binary --algorithm 256 | \
awk '{ print $1 }'
4d303dac9eed63573f6190e9c4191be619e03a7b3c21e9bb3d27ac1a55971e6b
Now we note that the digest of a wrapped Envelope is the digest of
the wrapped Envelope's digest:
$ envelope subject "Hello" | \
envelope subject --wrapped | \
envelope digest --hex
743a86a9f411b1441215fbbd3ece3de5206810e8a3dd8239182e123802677bd7
$ echo "4d303dac9eed63573f6190e9c4191be619e03a7b3c21e9bb\
3d27ac1a55971e6b" \
| xxd -r -p | shasum --binary --algorithm 256 | awk '{ print $1 }'
743a86a9f411b1441215fbbd3ece3de5206810e8a3dd8239182e123802677bd7
5. Envelope Hierarchy
This section is informative, and describes Envelopes from the
perspective of their hierarchical structure and the various ways they
can be formatted.
Notionally an Envelope can be thought of as a subject and one or more
predicate-object pairs called assertions.
McNally & Allen Expires 21 February 2024 [Page 13]
Internet-Draft Envelope August 2023
Note that the following example is _not_ CDDL or CBOR diagnostic
notation, but "Envelope notation," which is a convenient way to
describe the structure of an Envelope:
subject [
predicate0: object0
predicate1: object1
...
predicateN: objectN
]
A concrete example of this might be:
"Alice" [
"knows": "Bob"
"knows": "Carol"
"knows": "Edward"
]
The notional concept of Envelope is helpful, but not technically
accurate because Envelope is implemented structurally as an
enumerated type consisting of five cases. This allows actual
Envelope instances to be more flexible, for example a "bare
assertion" consisting of a predicate-object pair with no subject,
which is useful in some situations:
"knows": "Bob"
More common is the opposite case: a subject with no assertions:
"Alice"
In Envelopes, there are five distinct "positions" of elements, each
of which is itself an Envelope and which therefore produces its own
digest:
1. Envelope
2. Subject
3. Assertion
4. Predicate
5. Object
McNally & Allen Expires 21 February 2024 [Page 14]
Internet-Draft Envelope August 2023
The examples above are printed in Envelope notation, which is
designed to make the semantic content of Envelopes human-readable,
but it doesn't show the actual digests associated with each of the
positions. To see the structure more completely, we can display
every element of the Envelope in "Tree Format":
6255e3b6 NODE
13941b48 subj "Alice"
4012caf2 ASSERTION
db7dd21c pred "knows"
afb8122e obj "Carol"
65c3ebc3 ASSERTION
db7dd21c pred "knows"
e9af7883 obj "Edward"
78d666eb ASSERTION
db7dd21c pred "knows"
13b74194 obj "Bob"
For easy recognition, Envelope trees only show the first four bytes
of each digest, but internally all digests are 32 bytes.
From the above Envelope and its tree, we make the following
observations:
* The Envelope is a node case, which has the overall Envelope
digest.
* The subject "Alice" has its own digest.
* Each of the three assertions have their own digests
* The predicate and object of each assertion each have their own
digests.
* The assertions appear in the structure in ascending lexicographic
order by digest, which is the actual order in which they are
serialized, and which is distinct from Envelope notation, where
they appear sorted alphabetically.
The following subsections present each of the five enumerated
Envelope cases in four different output formats:
* Envelope Notation
* Envelope Tree
* CBOR Diagnostic Notation
McNally & Allen Expires 21 February 2024 [Page 15]
Internet-Draft Envelope August 2023
* CBOR hex
These examples may be used as test vectors. In addition, each
subsection starts with the envelope command line [ENVELOPE-CLI]
needed to generate the Envelope being formatted.
5.1. Leaf Case
*Envelope CLI Command Line*
envelope subject "Alice"
*Envelope Notation*
"Alice"
*Tree*
13941b48 "Alice"
*CBOR Diagnostic Notation*
200( / envelope /
24("Alice") / leaf /
)
*CBOR Hex*
D8 C8 # tag(200) envelope
D8 18 # tag(24) leaf
65 # text(5)
416C696365 # "Alice"
5.2. Elided Case
*Envelope CLI Command Line*
envelope subject "Alice" | envelope elide
*Envelope Notation*
ELIDED
*Tree*
13941b48 ELIDED
*CBOR Diagnostic Notation*
McNally & Allen Expires 21 February 2024 [Page 16]
Internet-Draft Envelope August 2023
200( / envelope /
h'13941b487c1ddebce827b6ec3f46d982938acdc7e3b6a140db36062d9519dd2f'
)
*CBOR Hex*
D8 C8 # tag(200) envelope
58 20 # bytes(32)
13941B487C1DDEBCE827B6EC3F46D982938ACDC7E3B6A140DB36062D9519DD2F
5.3. Node Case
*Envelope CLI Command Line*
envelope subject "Alice" | envelope assertion "knows" "Bob"
*Envelope Notation*
"Alice" [
"knows": "Bob"
]
*Tree*
8955db5e NODE
13941b48 subj "Alice"
78d666eb ASSERTION
db7dd21c pred "knows"
13b74194 obj "Bob"
*CBOR Diagnostic Notation*
200( / envelope /
[
24("Alice"), / leaf /
{
24("knows"): / leaf /
24("Bob") / leaf /
}
]
)
*CBOR Hex*
McNally & Allen Expires 21 February 2024 [Page 17]
Internet-Draft Envelope August 2023
D8 C8 # tag(200) envelope
82 # array(2)
D8 18 # tag(24) leaf
65 # text(5)
416C696365 # "Alice"
A1 # map(1)
D8 18 # tag(24) leaf
65 # text(5)
6B6E6F7773 # "knows"
D8 18 # tag(24) leaf
63 # text(3)
426F62 # "Bob"
5.4. Assertion Case
*Envelope CLI Command Line*
envelope subject assertion "knows" "Bob"
*Envelope Notation*
"knows": "Bob"
*Tree*
78d666eb ASSERTION
db7dd21c pred "knows"
13b74194 obj "Bob"
*CBOR Diagnostic Notation*
200( / envelope /
{
24("knows"): / leaf /
24("Bob") / leaf /
}
)
*CBOR Hex*
D8 C8 # tag(200) envelope
A1 # map(1)
D8 18 # tag(24) leaf
65 # text(5)
6B6E6F7773 # "knows"
D8 18 # tag(24) leaf
63 # text(3)
426F62 # "Bob"
McNally & Allen Expires 21 February 2024 [Page 18]
Internet-Draft Envelope August 2023
5.5. Wrapped Case
*Envelope CLI Command Line*
envelope subject "Alice" | envelope subject --wrapped
*Envelope Notation*
{
"Alice"
}
*Tree*
2bc17c65 WRAPPED
13941b48 subj "Alice"
*CBOR Diagnostic Notation*
200( / envelope /
200( / envelope /
24("Alice") / leaf /
)
)
*CBOR Hex*
D8 C8 # tag(200) envelope
D8 C8 # tag(200) envelope
D8 18 # tag(24) leaf
65 # text(5)
416C696365 # "Alice"
6. Reference Implementations
This section is informative.
The current reference implementations of Envelope are written in
Swift [ENVELOPE-SWIFT] and Rust [ENVELOPE-RUST].
The envelope command line tool [ENVELOPE-CLI] is also written in
Swift.
7. Security Considerations
This section is informative unless noted otherwise.
McNally & Allen Expires 21 February 2024 [Page 19]
Internet-Draft Envelope August 2023
7.1. CBOR Considerations
Generally, this document inherits the security considerations of CBOR
[RFC8949]. Though CBOR has limited web usage, it has received strong
usage in hardware, resulting in a mature specification. It also
inherits the security considerations of Gordian dCBOR [DCBOR].
7.2. Validation Requirements
Unlike HTML, Envelope is intended to be conservative in both what it
encodes _and_ what it accepts as valid. This means that receivers of
Envelope-based documents should carefully validate them. Any
deviation from the validation requirements of this specification MUST
result in the rejection of the entire Envelope. Even after
validation, Envelope contents should be treated with due skepticism
at the application level.
7.3. Choice of SHA-256 Hash Primitive
Envelope uses the SHA-256 digest algorithm [RFC6234], which is
regarded as reliable and widely supported by many implementations in
both software and hardware.
7.4. Correlated Digests
Elided Envelopes may in some cases inadvertently reveal information
by transmitting digests that may be correlated to known information.
In many cases this is of no consequence, but when necessary Envelopes
can (when constructed) be "salted" by adding assertions that contain
random data. This results in perturbing the digest tree, hence
decorrelating it (after elision) from digests whose unelided contents
are known.
7.5. RFC 6973 Considerations
"Privacy Considerations for Internet Protocols" [RFC6973] lists
threats and guidelines related to privacy in internet protocols.
Envelope is intended to help internet protocols easily adopt these
considerations. It explicitly addresses the privacy-specific threats
of correlation, secondary use, and disclosure by supporting the
suggested guideline of Data Minimization.
McNally & Allen Expires 21 February 2024 [Page 20]
Internet-Draft Envelope August 2023
7.6. RFC 8280 Considerations
"Research into Human Rights Protocol Considerations" [RFC8280] lists
guidelines for human rights considerations in internet protocols.
Envelope similarly adopts many of the guidelines there, improving
privacy and censorship resistance through its hashed elision; and
accessibility, heterogeneity support, reliability, and integrity
through its fundamental data structures.
8. IANA Considerations
8.1. CBOR Tags
This document requests that IANA [IANA-CBOR-TAGS] assign the
following tag:
+=====+===========+==================+===============+
| Tag | Data Item | Semantics | Specification |
+=====+===========+==================+===============+
| 200 | multiple | Gordian Envelope | This document |
+-----+-----------+------------------+---------------+
Table 1
Points of contact:
* Christopher Allen christophera@blockchaincommons.com
(mailto:christophera@blockchaincommons.com)
* Wolf McNally wolf@wolfmcnally.com (mailto:wolf@wolfmcnally.com)
8.2. Media Type
The proposed media type [RFC6838] for Envelope is application/
envelope+cbor. The authors understand that this will require this
document to become an RFC before the media type can be registered.
* Type name: application
* Subtype name: envelope+cbor
* Required parameters: n/a
* Optional parameters: n/a
* Encoding considerations: binary
* Security considerations: See the previous section of this document
McNally & Allen Expires 21 February 2024 [Page 21]
Internet-Draft Envelope August 2023
* Interoperability considerations: n/a
* Published specification: This document
* Applications that use this media type: None yet, but it is
expected that this format will be deployed in protocols and
applications.
* Additional information:
- Magic number(s): n/a
- File extension(s): .envelope
- Macintosh file type code(s): n/a
* Person & email address to contact for further information:
- Christopher Allen christophera@blockchaincommons.com
(mailto:christophera@blockchaincommons.com)
- Wolf McNally wolf@wolfmcnally.com (mailto:wolf@wolfmcnally.com)
* Intended usage: COMMON
* Restrictions on usage: none
* Author:
- Wolf McNally wolf@wolfmcnally.com (mailto:wolf@wolfmcnally.com)
* Change controller:
- The IESG iesg@ietf.org (mailto:iesg@ietf.org)
9. References
9.1. Normative References
[CCDE] "Common CBOR Deterministic Encoding and Application
Profiles", n.d., <https://www.ietf.org/archive/id/draft-
bormann-cbor-dcbor-02.html>.
[DCBOR] "Gordian dCBOR: A Deterministic CBOR Application Profile",
n.d., <https://datatracker.ietf.org/doc/draft-mcnally-
deterministic-cbor/>.
McNally & Allen Expires 21 February 2024 [Page 22]
Internet-Draft Envelope August 2023
[ENVELOPE-CLI]
"Envelope Command Line Tool", n.d.,
<https://github.com/BlockchainCommons/envelope-cli-swift>.
[ENVELOPE-RUST]
"Blockchain Commons Gordian Envelope for Rust", n.d.,
<https://github.com/blockchaincommons/bc-envelope-rust>.
[ENVELOPE-SWIFT]
"Blockchain Commons Gordian Envelope for Swift", n.d.,
<https://github.com/blockchaincommons/BCSwiftEnvelope>.
[IANA-CBOR-TAGS]
"IANA, Concise Binary Object Representation (CBOR) Tags",
n.d., <https://www.iana.org/assignments/cbor-tags/cbor-
tags.xhtml>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/rfc/rfc2119>.
[RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms
(SHA and SHA-based HMAC and HKDF)", RFC 6234,
DOI 10.17487/RFC6234, May 2011,
<https://www.rfc-editor.org/rfc/rfc6234>.
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
Specifications and Registration Procedures", BCP 13,
RFC 6838, DOI 10.17487/RFC6838, January 2013,
<https://www.rfc-editor.org/rfc/rfc6838>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.
[RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data
Definition Language (CDDL): A Notational Convention to
Express Concise Binary Object Representation (CBOR) and
JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610,
June 2019, <https://www.rfc-editor.org/rfc/rfc8610>.
[RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", STD 94, RFC 8949,
DOI 10.17487/RFC8949, December 2020,
<https://www.rfc-editor.org/rfc/rfc8949>.
9.2. Informative References
McNally & Allen Expires 21 February 2024 [Page 23]
Internet-Draft Envelope August 2023
[MERKLE] "Merkle Tree", n.d.,
<https://en.wikipedia.org/wiki/Merkle_tree>.
[RFC6973] Cooper, A., Tschofenig, H., Aboba, B., Peterson, J.,
Morris, J., Hansen, M., and R. Smith, "Privacy
Considerations for Internet Protocols", RFC 6973,
DOI 10.17487/RFC6973, July 2013,
<https://www.rfc-editor.org/rfc/rfc6973>.
[RFC8280] ten Oever, N. and C. Cath, "Research into Human Rights
Protocol Considerations", RFC 8280, DOI 10.17487/RFC8280,
October 2017, <https://www.rfc-editor.org/rfc/rfc8280>.
Acknowledgments
The authors are grateful to Carsten Bormann for his review and
helpful feedback.
Authors' Addresses
Wolf McNally
Blockchain Commons
Email: wolf@wolfmcnally.com
Christopher Allen
Blockchain Commons
Email: christophera@lifewithalacrity.com
McNally & Allen Expires 21 February 2024 [Page 24]