]> Blockchain Commons

wolf@wolfmcnally.com

Blockchain Commons

christophera@lifewithalacrity.com

Applications and Real-Time Network Working Group Internet-Draft 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 Source for this draft and an issue tracker can be found at .

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" 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" .

The following architectural decisions support these goals:

• Structured Merkle Tree. A variant of the Merkle Tree 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.)
• 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 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.

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.

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 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.

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 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.

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) . To be considered a well-formed Envelope, a sequence of bytes MUST conform to the Gordian dCBOR deterministic CBOR profile 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: 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.

Leaf Case Format A leaf case is used when the Envelope contains only user-defined CBOR content. It is tagged using #6.201, "encapsulated dCBOR", per . 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.201. To preserve deterministic encoding, authors of application-level data formats based on Envelope MUST only encode CBOR that conforms to 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.

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. 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.

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. 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.

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.

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.

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. 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.

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:

• 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.

Leaf Digest Calculation The leaf case consists of any CBOR object conforming to dCBOR . The Envelope image is the CBOR serialization of that object: Example The CBOR serialization of the plaintext string "Hello" (not including the quotes) is: The following command line calculates the SHA-256 sum of this sequence: Using the envelope command line tool , we create an Envelope with this string as the subject and display the Envelope's digest. The digest below matches the one above.

Elided Digest Calculation The elided case declares its digest to be the digest of the Envelope for which it is a placeholder. Example If we create the Envelope from the leaf example above, elide it, and then request its digest: ...we see that its digest is the same as its unelided form:

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. Example We create four separate Envelopes and display their digests: We combine the Envelopes into a single Envelope with three assertions: 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: To replicate this, we make a list of digests, starting with the subject, and then sort each assertion's digest in ascending lexicographic order: 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:

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: Example We create an assertion from two separate Envelopes and display their digests: To replicate this, we make a list of the predicate digest and the object digest, in that order: 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:

Wrapped Digest Calculation The Envelope image of the wrapped case is the digest of the wrapped Envelope: Example As above, we note the digest of a leaf Envelope is the digest of its CBOR: Now we note that the digest of a wrapped Envelope is the digest of the wrapped Envelope's digest:

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. 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: A concrete example of this might be: 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: More common is the opposite case, a subject with no assertions: 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

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": 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
• CBOR hex

These examples may be used as test vectors. In addition, each subsection starts with the envelope command line needed to generate the Envelope being formatted.

Leaf Case Envelope CLI Command Line Envelope Notation Tree CBOR Diagnostic Notation CBOR Hex

Elided Case Envelope CLI Command Line Envelope Notation Tree CBOR Diagnostic Notation CBOR Hex

Node Case Envelope CLI Command Line Envelope Notation Tree CBOR Diagnostic Notation CBOR Hex

Assertion Case Envelope CLI Command Line Envelope Notation Tree CBOR Diagnostic Notation CBOR Hex

Wrapped Case Envelope CLI Command Line Envelope Notation Tree CBOR Diagnostic Notation CBOR Hex

Reference Implementations This section is informative. The current reference implementations of Envelope are written in Swift and Rust . The envelope command line tool is also written in Rust.

Security Considerations This section is informative unless noted otherwise.

CBOR Considerations Generally, this document inherits the security considerations of CBOR . 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 .

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.

Choice of SHA-256 Hash Primitive Envelope uses the SHA-256 digest algorithm , which is regarded as reliable and widely supported by many implementations in both software and hardware.

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.

RFC 6973 Considerations "Privacy Considerations for Internet Protocols" 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.

RFC 8280 Considerations "Research into Human Rights Protocol Considerations" 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.

IANA Considerations

CBOR Tags RFC Editor: please replace RFCXXXX with the RFC number of this RFC and remove this note. IANA has assigned the following tag: CBOR Tag for Envelope

Tag	Data Item	Semantics	Specification
200	multiple	Gordian Envelope	[RFCXXXX]

This document uses the tag #6.201 for encapsulated dCBOR, which is defined in . Points of contact:

• Christopher Allen christophera@blockchaincommons.com
• Wolf McNally wolf@wolfmcnally.com

Media Type The proposed media type 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
• 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
  • Wolf McNally wolf@wolfmcnally.com
• Intended usage: COMMON
• Restrictions on usage: none
• Author:
  • Wolf McNally wolf@wolfmcnally.com
• Change controller:
  • The IESG iesg@ietf.org

References Normative References The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. These design goals make it different from earlier binary serializations such as ASN.1 and MessagePack. This document obsoletes RFC 7049, providing editorial improvements, new details, and errata fixes while keeping full compatibility with the interchange format of RFC 7049. It does not create a new version of the format. This document proposes a notational convention to express Concise Binary Object Representation (CBOR) data structures (RFC 7049). Its main goal is to provide an easy and unambiguous way to express structures for protocol messages and data formats that use CBOR or JSON. This document defines procedures for the specification and registration of media types for use in HTTP, MIME, and other Internet protocols. This memo documents an Internet Best Current Practice. IANA n.d. Federal Information Processing Standard, FIPS n.d. n.d. n.d. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References n.d. This document offers guidance for developing privacy considerations for inclusion in protocol specifications. It aims to make designers, implementers, and users of Internet protocols aware of privacy-related design choices. It suggests that whether any individual RFC warrants a specific privacy considerations section will depend on the document's content. This document aims to propose guidelines for human rights considerations, similar to the work done on the guidelines for privacy considerations (RFC 6973). The other parts of this document explain the background of the guidelines and how they were developed. This document is the first milestone in a longer-term research effort. It has been reviewed by the Human Rights Protocol Considerations (HRPC) Research Group and also by individuals from outside the research group.

Acknowledgments The authors are grateful to Carsten Bormann for his review and helpful feedback.