WG Working Group S. M. Smith Internet-Draft ProSapien LLC Intended status: Informational P. Feairheller Expires: 29 January 2024 GLEIF 28 July 2023 Issuance and Presentation Exchange Protocol draft-ssmith-ipex-00 Abstract The Issuance and Presentation Exchange (IPEX) Protocol provides a uniform mechanism for the issuance and presentation of ACDCs [ACDC-ID] in a securely attributable manner. A single protocol is able to work for both types of exchanges by recognizing that all exchanges (both issuance and presentation) may be modeled as the disclosure of information by a Discloser to a Disclosee. The difference between exchange types is the information disclosed not the mechanism for disclosure. Furthermore, the chaining mechanism of ACDCs and support for both targeted and untargeted ACDCs provide sufficient variability to accommodate the differences in applications or use cases without requiring a difference in the exchange protocol itself. This greatly simplifies the exchange protocol. This simplification has two primary advantages. The first is enhanced security. A well-delimited protocol can be designed and analyzed to minimize and mitigate attack mechanisms. The second is convenience. A standard simple protocol is easier to implement, support, update, understand, and adopt. The tooling is more consistent. This IPEX [IPEX-ID] protocol leverages important features of ACDCs and ancillary protocols such as CESR [CESR-ID], SAIDs [SAID-ID], and CESR-Proofs [Proof-ID] as well as Ricardian contracts [RC] and graduated disclosure (partial, selective, full) to enable contractually protected disclosure. Contractually protected disclosure includes both chain-link confidential [CLC] and contingent disclosure [ACDC-ID]. About This Document This note is to be removed before publishing as an RFC. The latest revision of this draft can be found at https://example.com/LATEST. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-ssmith-ipex/. Smith & Feairheller Expires 29 January 2024 [Page 1] Internet-Draft IPEX July 2023 Discussion of this document takes place on the WG Working Group mailing list (mailto:WG@example.com), which is archived at https://example.com/WG. Source for this draft and an issue tracker can be found at https://github.com/USER/REPO. 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 29 January 2024. 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 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.1. Chain-Link Confidentiality . . . . . . . . . . . . . . . 4 3. Exchange Protocol . . . . . . . . . . . . . . . . . . . . . . 4 3.1. Discussion . . . . . . . . . . . . . . . . . . . . . . . 5 3.2. IPEX Validation . . . . . . . . . . . . . . . . . . . . . 7 3.2.1. Issuer Signing Rules . . . . . . . . . . . . . . . . 7 4. Example Most Compact Variant . . . . . . . . . . . . . . . . 8 Smith & Feairheller Expires 29 January 2024 [Page 2] Internet-Draft IPEX July 2023 5. Conventions and Definitions . . . . . . . . . . . . . . . . . 14 6. Security Considerations . . . . . . . . . . . . . . . . . . . 14 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 8.1. Normative References . . . . . . . . . . . . . . . . . . 14 8.2. Informative References . . . . . . . . . . . . . . . . . 16 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 16 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16 1. Introduction TODO Introduction 2. Terminology Presentation Exchange An exchange that provides disclosure of one or more ACDCs between a _Discloser_ and a _Disclosee_. A presentation exchange is the process by which authenticatable information may be exchanged between two parties, namely, the _Discloser_ and _Disclosee_. ACDC Type of data as issuance concretely defined by the ACDC specification [ACDC-ID]. Discloser An ACDC in a disclosure is _disclosed by_ the _Discloser_. Disclosee An ACDC in a disclosure is _disclosed to_ the _Disclosee_. Issuer An _ACDC_ is _issued by_ the _Issuer_. The _Issuer_ identifier (AID) appears in the top level of the ACDC. Issuee An _ACDC_ is optionally _issued to_ the _Issuee_. When present, the _Issuee_ identifier (AID) appears at the top level of the attribute section or in the attribute list at the top level of the attribute aggregate section of the ACDC. Each _ACDC_ MUST have an _Issuer_ and MAY have an _Issuee_. The set of _ACDCs_ so disclosed in a _presentation exchange_ MUST be chained. This set of chained _ACDCs_ define a directed acyclic graph (DAG) that MUST have at least one vertex and MAY have zero or more edges pointing to other vertices. Smith & Feairheller Expires 29 January 2024 [Page 3] Internet-Draft IPEX July 2023 Each _ACDC_ itself defines a graph fragment consisting of one vertex and zero or more directed edges. Each directed edge contained in an _ACDC_ points to a vertex contained in another _ACDC_. The ACDC that contains the origin vertex of the DAG is called the _origin_ or _primary_ ACDC of the _presentation exchange_. The disclosure performed by a presentation exchange MAY be _graduated_ and MAY be _contractually protected_. Issuance Exchange A special case of a _presentation exchange_ where the _Discloser_ is the _Issuer_ of the _origin_ (Primary) _ACDC_ of the DAG formed by the set of chained ACDCs so disclosed. In an _issuance exchange_, when the _origin_ ACDC has an _Issuee_, the _Disclosee_ MAY also be the _origin_ ACDC's _Issuee_. 2.1. Chain-Link Confidentiality Disclosures via Presentations Exchanges may be contractually protected by Chain-Link Confidentiality (i.e a Chain-Link Confidential disclosure). The chaining in this case is different from the chaining described above between Issuances in a DAG of chained Issuances. Chain-link confidentiality, in contrast, chains together a sequence of Disclosees. Each Disclosee in the sequence in turn is the Discloser to the next Disclosee. The terms-of-use of the original disclosure as applied to the original Disclosee MUST be applied by each subsequent Discloser to each subsequent Disclosee via each of the subsequent disclosures (presentation exchanges). These terms-of-use typically constrain disclosure to only approved parties, i.e. imbue the chain of disclosures with some degree of confidentiality. These terms-of-use are meant to contractually protect the data rights of the original Issuer or Issuee of the data being disclosed. 3. Exchange Protocol +===========+===========+==========+=============+==================+ | Discloser | Disclosee | Initiate | Contents | Description | +===========+===========+==========+=============+==================+ | | apply | Y | schema or | schema SAID is | | | | | its SAID, | type of ACDC, | | | | | attribute | optional label | | | | | field label | list for | | | | | list, | selective | | | | | signature | disclosure, | | | | | on apply or | CESR-Proof | | | | | its SAID | signature | +-----------+-----------+----------+-------------+------------------+ Smith & Feairheller Expires 29 January 2024 [Page 4] Internet-Draft IPEX July 2023 | spurn | | N | | rejects apply | +-----------+-----------+----------+-------------+------------------+ | offer | | Y | metadata | includes schema | | | | | ACDC or its | or its SAID, | | | | | SAID, | other partial | | | | | signature | disclosures, | | | | | on offer or | selective | | | | | its SAID | disclosure | | | | | | label list, | | | | | | CESR-Proof | | | | | | signature | +-----------+-----------+----------+-------------+------------------+ | | spurn | N | | rejects offer | +-----------+-----------+----------+-------------+------------------+ | | agree | N | signature | CESR-Proof | | | | | on offer or | signature | | | | | its SAID | | +-----------+-----------+----------+-------------+------------------+ | spurn | | N | | rejects agree | +-----------+-----------+----------+-------------+------------------+ | grant | | Y | full or | includes | | | | | selective | attribute | | | | | disclosure | values, CESR- | | | | | ACDC, | Proof signature | | | | | signature | | | | | | on grant or | | | | | | its SAID | | +-----------+-----------+----------+-------------+------------------+ | | admit | N | signature | CESR-Proof | | | | | on grant or | signature | | | | | its SAID | | +-----------+-----------+----------+-------------+------------------+ Table 1 3.1. Discussion All the variants of an ACDC are various degrees of expansion of the compact variant. Therefore, an Issuer commitment via a signature to any variant of ACDC (compact, full, etc) makes a cryptographic commitment to the top-level section fields shared by all variants of that ACDC because the value of a top level section field is either the SAD or the SAID of the SAD of the associated section. Both a SAD and its SAID, when signed, each provide a verifiable commitment to the SAD. In the former the signature verification is directly agains the SAD itself. In the latter, the SAID as digest must first be verified against its SAD and then the signature on the SAID may be verified. This indirect verifiablity assumes that the cryptographic Smith & Feairheller Expires 29 January 2024 [Page 5] Internet-Draft IPEX July 2023 strength of the SAID digest is equivalent to the cryptographic strength of the signature used to sign it. To clarify, because all variants share the same top level structure as the compact variant, then a signature on any variant may be used to verify the Issuer's committment to any other variant either directly or indirectly, in whole or in part on a top-level section by top-level section basis. This cross-variant Issuer commitment verifiability is an essential property that supports graduated disclosure by the Disclosee of any or all variants wether it be full, compact, metadata, partial, selective, bulk issued, or contractually protected. To elaborate, the SAID of a given variant is useful even when it is not the SAID of the variant the Issuer signed because during graduated disclosure the Discloser MAY choose to sign that given variant to fullfill a given step in an IPEX graduated disclosure transaction. The Discloser thereby can make a verifiable disclosure in a given step of the SAD of a given variant that fulfills a commitment made in a prior step via its signature on merely the SAID of the SAD of the variant so disclosed. For example, the Metadata variant of an ACDC will have a different SAID than the Compact variant because some of the top-level field values may be empty in the Metadata variant. One can think of the The metadata variant as a partial manifest that only includes those top level sections that the Discloser is committing to disclose in order to induce the Disclosee to agree to the contractual terms of use when disclosed. The IPEX transaction is between the Discloser and Disclosee, who both may make non-repudiable commitments via signing to each other. Typically this means that the Discloser will eventually need to fulfull its commitment with a proof of disclosure to the Disclosee. This proof may be satisfied with either directly against the Discloser's signature on the the actual disclosed SAD or indirectly agaisnt the Discloser's signature on the SAID of the actual disclosed SAD. In addition, the Disclosee will typically require a proof of issuance via a non-repudiable signature by the Issuer on a variant of the disclosed SAD that is verifiable (directly or indirectly) against the variant that is the disclosed SAD. To summarize, when the Issuer commits to the composed schema of an ACDC it is committing to all the variants so composed. As described above, the top level field values in the compact variant enable verification against a disclosure of any of the other Issuer committed variants because they all share the same top level structure. This applies even to the metadata variant in spite of it only providing values for some top level sections and not others. The verifiablity of a top level section is separable. Smith & Feairheller Expires 29 January 2024 [Page 6] Internet-Draft IPEX July 2023 Consequently, the IPEX protocol must specify how a validator does validation of any variant in a graduated disclosure. To restate there are two proofs that a Discloser must provide. The first is proof of issuance and the second is proof of disclosure. In the former, the Discloser provide the variant via its SAD that was actually signed (as SAD or SAID of SAD) by the Issuer in order for the Disclosee to verify authentic issuance via the signature on that variant. In the latter, the Discloser must disclose any other Issuer enabled (via schema composition) variants that the Discloser offered to disclose as part of the graduated disclosure process. 3.2. IPEX Validation The goal is to define a validation process (set of rules) that works for all variants of an ACDC and for all types of graduated disclosure of that ACDC. For example, in the bulk issuance of an ACDC, the Issuer only signs the blinded SAID of the SAD that is the Compact variant of the ACDC not the SAD itself. This enable a Discloser to make a proof of inclusion of the ACDC in a bulk issuance set by unblinding the signature on the blinded SAID without leaking correlation to anything but the blinded SAID itself. To clarify, the Disclosee can verify the signature on the SAID without to prove set inclusion with needing the disclosure of any other information about the ACDC. Issuer signing of the SAID not the SAD also has the side benefit of minimizing the computation of large numbers of bulk issued signatures. 3.2.1. Issuer Signing Rules The Issuer MUST provide a signature on the SAID of the most compact variant defined by the schema of the ACDC. When more than one variant is defined by the schema via the oneOf composition operator for any top-level field, the most compact variant MUST appear as the first entry in the oneOf list. When only one variant of each top- level field is defined by the schema, that variant is therefore by defintion the most compact variant. Smith & Feairheller Expires 29 January 2024 [Page 7] Internet-Draft IPEX July 2023 The different variants of an ACDC form a hash tree (using SAIDs) that is analogous to a Merkle Tree. Signing the top-level SAID of the compact version of the ACDC is equivalent to signing the Merkle Root of a Merkle Tree. Different variants of an ACDC (SADs with SAIDs) correspond to different paths through a Merkle tree. The process of verifying that a SAD via its SAID of a section is included in a schema authorized variant down from the top-level SAID is equivalent to a Merkle Tree proof of inclusion along a path in the Merkel Tree down from its Root. This allows a single signature to provide proof of Issuance of the presentation of any schema authorized variants of the ACDC. An Issuer MAY provide signatures of the SAIDS of other variants, as well as signatures of the SADs of other variants. Proof of issuance is provided by disclosing the SAID of the most compact variant and the signature by the Issuer on that SAID. Proof of disclosure is provided by disclosing the SAD of the most compact variant and then recursively disclosing the nested SADs of each of the top level sections of the most compact variant as needed for the promised disclosure. Thus for any disclosed variant of an ACDC, the Disclosee need only verify only one proof of issuance as defined above and may need to verify a different proof of disclosure for each disclosed variant as defined above. 4. Example Most Compact Variant The following schema supports a compact variant { "$id": "E46jrVPTzlSkUPqGGeIZ8a8FWS7a6s4reAXRZOkogZ2A", "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Public ACDC", "description": "Example JSON Schema Public ACDC.", "credentialType": "PublicACDCExample", "type": "object", "required": [ "v", "d", "i", "ri", "s", "a", "e", Smith & Feairheller Expires 29 January 2024 [Page 8] Internet-Draft IPEX July 2023 "r" ], "properties": { "v": { "description": "ACDC version string", "type": "string" }, "d": { "description": "ACDC SAID", "type": "string" }, "i": { "description": "Issuer AID", "type": "string" }, "ri": { "description": "credential status registry AID", "type": "string" }, "s": { "description": "schema section", "oneOf": [ { "description": "schema section SAID", "type": "string" }, { "description": "schema detail", "type": "object" }, ] }, "a": { "description": "attribute section", "oneOf": [ { "description": "attribute section SAID", "type": "string" }, Smith & Feairheller Expires 29 January 2024 [Page 9] Internet-Draft IPEX July 2023 { "description": "attribute detail", "type": "object", "required": [ "d", "i", "score", "name" ], "properties": { "d": { "description": "attribute section SAID", "type": "string" }, "i": { "description": "Issuee AID", "type": "string" }, "score": { "description": "test score", "type": "integer" }, "name": { "description": "test taker full name", "type": "string" } }, "additionalProperties": false, } ] }, "e": { "description": "edge section", "oneOf": [ { "description": "edge section SAID", "type": "string" }, { "description": "edge detail", Smith & Feairheller Expires 29 January 2024 [Page 10] Internet-Draft IPEX July 2023 "type": "object", "required": [ "d", "boss" ], "properties": { "d": { "description": "edge section SAID", "type": "string" }, "boss": { "description": "boss edge", "type": "object", "required": [ "d", "n", 's', "w" ], "properties": { "d": { "description": "edge SAID", "type": "string" }, "n": { "description": "far node SAID", "type": "string" }, "s": { "description": "far node schema SAID", "type": "string", "const": ""EiheqcywJcnjtJtQIYPvAu6DZAIl3MORH3dCdoFOLe71" }, "w": { "description": "edge weight", "type": "string" }, "additionalProperties": false Smith & Feairheller Expires 29 January 2024 [Page 11] Internet-Draft IPEX July 2023 }, }, "additionalProperties": false } ] }, "r": { "description": "rule section", "oneOf": [ { "description": "rule section SAID", "type": "string" }, { "description": "rule detail", "type": "object", "required": [ "d", "warrantyDisclaimer", "liabilityDisclaimer" ], "properties": { "d": { "description": "edge section SAID", "type": "string" }, "warrantyDisclaimer": { "description": "warranty disclaimer clause", "type": "object", "required": [ "d", "l" ], "properties": { "d": { "description": "clause SAID", "type": "string" }, "l": Smith & Feairheller Expires 29 January 2024 [Page 12] Internet-Draft IPEX July 2023 { "description": "legal language", "type": "string" } }, "additionalProperties": false }, "liabilityDisclaimer": { "description": "liability disclaimer clause", "type": "object", "required": [ "d", "l" ], "properties": { "d": { "description": "clause SAID", "type": "string" }, "l": { "description": "legal language", "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } ] } }, "additionalProperties": false } The following JSON field map serialization satisfies the rules for most compact variant of the schema above. Smith & Feairheller Expires 29 January 2024 [Page 13] Internet-Draft IPEX July 2023 { "v": "ACDC10JSON00011c_", "d": "EBdXt3gIXOf2BBWNHdSXCJnFJL5OuQPyM5K0neuniccM", "i": "did:keri:EmkPreYpZfFk66jpf3uFv7vklXKhzBrAqjsKAn2EDIPM", "ri": "did:keri:EymRy7xMwsxUelUauaXtMxTfPAMPAI6FkekwlOjkggt", "s": "E46jrVPTzlSkUPqGGeIZ8a8FWS7a6s4reAXRZOkogZ2A", "a": "EgveY4-9XgOcLxUderzwLIr9Bf7V_NHwY1lkFrn9y2PY", "e": "ERH3dCdoFOLe71iheqcywJcnjtJtQIYPvAu6DZIl3MOA", "r": "Ee71iheqcywJcnjtJtQIYPvAu6DZIl3MORH3dCdoFOLB" } The Issuer signs the SAID, d field value of the field map above. 5. Conventions and Definitions 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. 6. Security Considerations TODO Security 7. IANA Considerations This document has no IANA actions. 8. References 8.1. Normative References [ACDC-ID] Smith, S., "IETF ACDC (Authentic Chained Data Containers) Internet Draft", 2022, . [CBOR] "CBOR Mapping Object Codes", n.d., . [CESR-ID] Smith, S., "IETF CESR (Composable Event Streaming Representation) Internet Draft", 2022, . [DIDK-ID] Feairheller, P., "IETF DID-KERI Internet Draft", 2022, . Smith & Feairheller Expires 29 January 2024 [Page 14] Internet-Draft IPEX July 2023 [IPEX-ID] Smith, S. and P. Feairheller, "IETF IPEX (Issuance and Presentation EXchange) Prototocol Internet Draft", 2022, . [JSch] "JSON Schema", n.d., . [JSch_202012] "JSON Schema 2020-12", n.d., . [JSON] "JavaScript Object Notation Delimeters", n.d., . [KERI-ID] Smith, S., "IETF KERI (Key Event Receipt Infrastructure) Internet Draft", 2022, . [MGPK] "Msgpack Mapping Object Codes", n.d., . [OOBI-ID] Smith, S., "IETF OOBI (Out-Of-Band-Introduction) Internet Draft", 2022, . [Proof-ID] Feairheller, P., "IETF CESR-Proof Internet Draft", 2022, . [PTEL-ID] Feairheller, P., "IETF PTEL (Public Transaction Event Log) Internet Draft", 2022, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC4627] "The application/json Media Type for JavaScript Object Notation (JSON)", n.d., . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8259] "JSON (JavaScript Object Notation)", n.d., . Smith & Feairheller Expires 29 January 2024 [Page 15] Internet-Draft IPEX July 2023 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", 4 December 2020, . [SAID-ID] Smith, S., "IETF SAID (Self-Addressing IDentifier) Internet Draft", 2022, . 8.2. Informative References [CLC] "Chain-Link Confidentiality", n.d., . [IDSys] "Identity System Essentials", n.d., . [KERI] Smith, S., "Key Event Receipt Infrastructure (KERI)", 2021, . [RC] "Ricardian Contract", n.d., . Acknowledgments TODO acknowledge. Authors' Addresses Samuel M. Smith ProSapien LLC Email: sam@prosapien.com Phil Feairheller GLEIF Email: Philip.Feairheller@gleif.org Smith & Feairheller Expires 29 January 2024 [Page 16]