From 3745e16303ba260a85a208f1104521e09f242eba Mon Sep 17 00:00:00 2001 From: Michael Jones Date: Mon, 1 Jan 2024 12:40:04 -0800 Subject: [PATCH] Mike's New Years Eve 2023 Proofread --- draft-ietf-jose-json-proof-algorithms.md | 96 +++++++++++++++--------- draft-ietf-jose-json-proof-token.md | 20 +++-- draft-ietf-jose-json-web-proof.md | 68 ++++++++++++----- 3 files changed, 124 insertions(+), 60 deletions(-) diff --git a/draft-ietf-jose-json-proof-algorithms.md b/draft-ietf-jose-json-proof-algorithms.md index 3c2af8b..16e5f53 100644 --- a/draft-ietf-jose-json-proof-algorithms.md +++ b/draft-ietf-jose-json-proof-algorithms.md @@ -44,7 +44,7 @@ organization = "Ping Identity" .# Abstract -The JSON Proof Algorithms (JPA) specification registers cryptographic algorithms and identifiers to be used with the JSON Web Proof and JSON Web Key (JWK) specifications. It defines several IANA registries for these identifiers. +The JSON Proof Algorithms (JPA) specification registers cryptographic algorithms and identifiers to be used with the JSON Web Proof and JSON Web Key (JWK) specifications. It defines IANA registries for these identifiers. {mainmatter} @@ -52,31 +52,31 @@ The JSON Proof Algorithms (JPA) specification registers cryptographic algorithms The JSON Web Proof (JWP) [@!I-D.ietf-jose-json-web-proof] draft establishes a new secure container format that supports selective disclosure and unlinkability using Zero-Knowledge Proofs (ZKPs) or other cryptographic algorithms. -> Editor's Note: This draft is still early and incomplete, there will be significant changes to the algorithms as currently defined here. Please do not use any of these definitions or examples for anything except personal experimentation and learning. Contributions and feedback are welcome at https://github.com/json-web-proofs/json-web-proofs. +> Editor's Note: This draft is still early and incomplete. There will be significant changes to the algorithms as currently defined here. Please do not use any of these definitions or examples for anything except personal experimentation and learning. Contributions and feedback are welcomed at https://github.com/json-web-proofs/json-web-proofs. # 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. -The roles of "issuer", "holder", and "verifier" are used as defined by the [Verifiable Credentials Data Model v1.1](https://www.w3.org/TR/2021/REC-vc-data-model-20211109/). The term "presentation" is also used as defined by this source, but the term "credential" is avoided in this specification in order to minimize confusion with other definitions. +The roles of "issuer", "holder", and "verifier" are used as defined by the VC Data Model [@VC-DATA-MODEL-2.0]. The term "presentation" is also used as defined by this source, but the term "credential" is avoided in this specification to minimize confusion with other definitions. # Terminology The terms "JSON Web Signature (JWS)", "Base64url Encoding", "Header Parameter", "JOSE Header", "JWS Payload", "JWS Signature", and "JWS Protected Header" are defined by [@RFC7515]. -The terms "JSON Web Proof (JWP)", "JWP Payload", "JWP Proof", and "JWP Protected Header" are defined by the JWP draft. +The terms "JSON Web Proof (JWP)", "JWP Payload", "JWP Proof", and "JWP Protected Header" are defined by [@!I-D.ietf-jose-json-web-proof]. These terms are defined by this specification: -Stable Key - An asymmetric key-pair used by an issuer that is also shared via an out-of-band mechanism to a verifier in order to validate the signature. +Stable Key: +: An asymmetric key-pair used by an issuer that is also shared via an out-of-band mechanism to a verifier to validate the signature. -Ephemeral Key - An asymmetric key-pair that is generated for one-time use by an issuer and never stored or used again outside of the creation of a single JWP. +Ephemeral Key: +: An asymmetric key-pair that is generated for one-time use by an issuer and never stored or used again outside of the creation of a single JWP. -Presentation Key - An asymmetric key-pair that is generated by a holder and used to ensure that a presentation is not able to be replayed by any other party. +Presentation Key: +: An asymmetric key-pair that is generated by a holder and used to ensure that a presentation is not able to be replayed by any other party. # Background @@ -99,17 +99,17 @@ All algorithms MUST provide integrity protection for the issuer header and all p ## Confirm -Performed by the holder to validate the issued JWP is correctly formed and protected. +Performed by the holder to validate that the issued JWP is correctly formed and protected. -Each algorithm MAY support using additional input items options such as those sent to the issuer for issuance. After confirmation, an algorithm MAY return a modified JWP for serialized storage without the local state (such as with blinded payloads now unblinded). +Each algorithm MAY support using additional input items options, such as those sent to the issuer for issuance. After confirmation, an algorithm MAY return a modified JWP for serialized storage without the local state (such as with blinded payloads now unblinded). -The algorithm MUST fully verify the issued proof value against the issuer protected header and all payloads. If given a presented JWP instead of an issued one the confirm process MUST return an error. +The algorithm MUST fully verify the issued proof value against the issuer protected header and all payloads. If given a presented JWP instead of an issued one, the confirm process MUST return an error. ## Present Used to apply any selective disclosure choices and perform any unlinkability transformations. -An algorithm MAY support additional input options from the requesting party such as for predicate proofs and verifiable computation requests. +An algorithm MAY support additional input options from the requesting party, such as for predicate proofs and verifiable computation requests. Every algorithm MUST support the ability to hide any or all payloads. It MUST always include the issuer protected header unmodified in the presentation. @@ -122,7 +122,7 @@ Performed by the verifier to verify the protected headers along with any disclos The algorithm MUST verify the integrity of all disclosed payloads and MUST also verify the integrity of both the issuer and presentation protected headers. If the presented proof contains any assertions about the hidden payloads, the algorithm MUST also verify all of those assertions. -It MAY support additional options such as those sent to the holder to generate the presentation. +It MAY support additional options, such as those sent to the holder to generate the presentation. If given an issued JWP for verification, the algorithm MUST return an error. @@ -132,7 +132,7 @@ This section defines how to use specific algorithms for JWPs. ## Single Use -> Editor's Note: This algorithm is going to be renamed and slightly refactored; the new name is still TBD. +> Editor's Note: This algorithm may be renamed and slightly refactored. The Single Use (SU) algorithm is based on composing multiple traditional JWS values into a single JWP proof value. It enables a very simple form of selective disclosure without requiring any advanced cryptographic techniques. @@ -152,7 +152,7 @@ The issuer MUST verify that the holder has possession of this key. The holder-i ### Issuer Setup -To create a Single Use JWP the issuer first generates a unique Ephemeral Key using the selected JWS algorithm. This key-pair will be used to sign each of the payloads of a single JWP and then discarded. +To create a Single Use JWP, the issuer first generates a unique Ephemeral Key using the selected JWS algorithm. This key-pair will be used to sign each of the payloads of a single JWP and then discarded. ### Using JWS @@ -170,7 +170,7 @@ The holder's Presentation Key JWK MUST be included in issuer protected header us The final issuer protected header is then used directly as the body of a JWS and signed using the issuer's Stable Key. The resulting JWS signature value unencoded octet string is the first value in the JWP proof. -In various examples in this specification the octet string serialized issuer header is referenced as `issuer_header`. +In various examples in this specification, the octet string serialized issuer header is referenced as `issuer_header`. ### Payloads @@ -180,13 +180,13 @@ The proof value as an octet string will have a total length that is the sum of t ### Presentation Protected Header -In order to generate a new presentation, the holder first creates a presentation protected header that is specific to the verifier being presented to. This header MUST contain a claim that both the holder and verifier trust as being unique and non-replayable. +To generate a new presentation, the holder first creates a presentation protected header that is specific to the verifier being presented to. This header MUST contain a claim that both the holder and verifier trust as being unique and non-replayable. This specification registers a `nonce` claim for the presentation protected header that contains a string value either generated by the verifier or derived from values provided by the verifier. When present, the verifier MUST ensure the nonce value matches during verification. The presentation protected header MAY contain other claims that are either provided by the verifier or by the holder. These presentation claims SHOULD NOT contain values that are common across multiple presentations and SHOULD be unique to a single presentation and verifier. -In various examples in this specification the octet string serialized presentation header is referenced as `presentation_header`. +In various examples in this specification, the octet string serialized presentation header is referenced as `presentation_header`. ### Presentation @@ -208,16 +208,16 @@ With the headers verified, the issuer's Ephemeral Key as given in the issuer pro ### JPA Registration -Proposed JWP `alg` value is of the format "SU-" appended with the relevant JWS `alg` value for the chosen public and ephemeral key-pair algorithm, for example "SU-ES256". +The proposed JWP `alg` value is of the format "SU-" appended with the relevant JWS `alg` value for the chosen public and ephemeral key-pair algorithm, for example "SU-ES256". ### Example -See the example in the appendix of the JSON Web Proof draft. +See the example in the appendix of [@!I-D.ietf-jose-json-web-proof]. ## BBS -The BBS Signature Scheme [@!I-D.irtf-cfrg-bbs-signatures] is under active development within the CRFG. Prior to this effort work was done under the DIF [Applied Cryptography Working Group](https://identity.foundation/working-groups/crypto.html), an effort to clarify and bring best practices to early prototypes leveraged by multiple early stage decentralized identity projects. +The BBS Signature Scheme [@!I-D.irtf-cfrg-bbs-signatures] is under active development within the CRFG. This algorithm supports both selective disclosure and unlinkability, enabling the holder to generate multiple presentations from one issued JWP without a verifier being able to correlate those presentations together based on the proof. @@ -231,18 +231,18 @@ The `BBS-PROOF-DRAFT-3` `alg` parameter value in the presentation protected head The key used for the `BBS-DRAFT-3` algorithm is an elliptic curve-based key pair, specifically against the G_2 subgroup of a pairing friendly curve. Additional details on key generation can be found in [@!I-D.irtf-cfrg-bbs-signatures, Section 3.3] -The JWK form of this key is an `OKP` type with a curve of `BLs12381G2`, with `x` being the BASE64URL-encoded form of the output of `point_to_octets_g2`. The use of this curve is described in [@!I-D.looker-cose-bls-key-representations]. +The JWK form of this key is an `OKP` type with a curve of `BLs12381G2`, with `x` being the BASE64URL-encoded form of the output of `point_to_octets_g2`. The use of this curve is described in [@!I-D.ietf-cose-bls-key-representations]. <{{./fixtures/build/private-key.jwk.wrapped}} Figure: BBS private key in JWK format -There is no additional prover key necessary for presentation proofs. +There is no additional holder key necessary for presentation proofs. ### Issuance Issuance is performed using the `Sign` operation from [@!I-D.irtf-cfrg-bbs-signatures, section 3.4.1]. This operation utilizes the issuer's BLS12-381 G2 key pair as `SK` and `PK`, along with desired protected header and payloads as the octets header and the octets array messages. -The octets result of this operation forms the issuance proof, to be used along with the protected header and payloads to serialize the JWP. +The octets resulting from this operation form the issuance proof, to be used along with the protected header and payloads to serialize the JWP. As an example, consider following protected header and array of payloads: @@ -283,7 +283,7 @@ For example, given the following presentation header: <{{./fixtures/template/bbs-prover-presentation-header.json}} Figure: Holder Presentation Header -The prover decides to share all information other than the email address, and generates a proof. That proof is represented in the following serializations: +The holder decides to share all information other than the email address, and generates a proof. That proof is represented in the following serializations: <{{./fixtures/build/bbs-prover.json.jwp.wrapped}} Figure: Presentation JWP (JSON serialization) @@ -309,15 +309,15 @@ The design is intentionally minimal and only involves using a single standardize ### Holder Setup -Prior to the issuer creating a new JWP it must have presentation binding information provided by the holder. This enables the holder to perform replay prevention while presenting the JWP. +Prior to the issuer creating a new JWP, it must have presentation binding information provided by the holder. This enables the holder to perform replay prevention while presenting the JWP. -The presentation key used by the holder must be transferred to the issuer and verified, likely through a challenge and self-signing mechanism. If the holder requires unlinkability it must also generate a new key that is verified and bound to each new JWP. +The presentation key used by the holder must be transferred to the issuer and verified, likely through a challenge and self-signing mechanism. If the holder requires unlinkability, it must also generate a new key that is verified and bound to each new JWP. -How these holder presentation keys are transferred and verified is out of scope of this specification, protocols such as OpenID Connect can be used to accomplish this. What is required by this definition is that the holder's presentation key MUST be included in the issuer's protected header using the `pjwk` claim with a JWK as the value. +How these holder presentation keys are transferred and verified is out of scope of this specification. Protocols such as OpenID Connect can be used to accomplish this. What is required by this definition is that the holder's presentation key MUST be included in the issuer's protected header using the `pjwk` claim with a JWK as the value. ### Issuer Setup -To use the MAC algorithm the issuer must have a stable public key pair to perform signing. To start the issuance process, a single 32-byte random Shared Secret must first be generated. This value will be shared privately to the holder as part of the issuer's JWP proof value. +To use the MAC algorithm, the issuer must have a stable public key pair to perform signing. To start the issuance process, a single 32-byte random Shared Secret must first be generated. This value will be shared privately to the holder as part of the issuer's JWP proof value. The Shared Secret is used by both the issuer and holder as the MAC method's key to generate a new set of unique ephemeral keys. These keys are then used as the input to generate a MAC that protects each payload. @@ -335,7 +335,7 @@ Each payload is serialized using UTF-8 and encoded with base64url into an octet ### Issuer Proof -The issuer proof consists of two items appended together, the issuer's signature of the appended array of MACs, and the Shared Secret used to generate the set of payload keys. +The issuer proof consists of two items appended together: the issuer's signature of the appended array of MACs and the Shared Secret used to generate the set of payload keys. To generate the signature, the array containing the final MAC of the issuer protected header followed by all of the payload MACs appended in order is used as the input to a new JWS. @@ -361,7 +361,7 @@ See the JWS [Presentation Protected Header](#presentation-protected-header) sect The presentation proof is constructed as a large octet array containing multiple appended items similar to the issuer proof value. The first item is the JWS decoded signature value generated when the holder uses the presentation key to sign the presentation header. The second item is the issuer signature from the issuer's proof value. -These two signatures are then followed by a MAC value for each payload. The MAC values used will depend on if that payload has been disclosed or is hidden. Disclosed payloads will include the MAC key input, and hidden payloads will include only their final MAC value. +These two signatures are then followed by a MAC value for each payload. The MAC values used will depend on whether that payload has been disclosed or is hidden. Disclosed payloads will include the MAC key input, and hidden payloads will include only their final MAC value. ``` presentation_proof = [presentation_signature, issuer_signature, @@ -373,7 +373,7 @@ The size of this value will depend on the underlying cryptographic algorithms. ### Verifier Setup -In order to verify that the presentation was protected from replay attacks, the verifier must be able to validate the presentation protected header. This involves the following steps: +To verify that the presentation was protected from replay attacks, the verifier must be able to validate the presentation protected header. This involves the following steps: 1. JSON parse the presentation header 2. Validate the contained `nonce` claim @@ -668,8 +668,32 @@ TBD {backmatter} + + + Verifiable Credentials Data Model 2.0 + + Digital Bazaar + + + OpenLink Software + + + W3C + + + Invited Expert + + + Block + + + + + # Acknowledgements +This work was incubated in the DIF [Applied Cryptography Working Group](https://identity.foundation/working-groups/crypto.html). + We would like to thank Alberto Solavagione for his valuable contributions to this specification. @@ -680,6 +704,10 @@ The BBS examples were generated using the library at https://github.com/mattrglo [[ To be removed from the final specification ]] + -03 + + * Improvements resulting from a full proofreading. + -02 * Add new `BBS-DRAFT-3` and `BBS-PROOF-DRAFT-3` algorithms based on [@!I-D.irtf-cfrg-bbs-signatures], Draft 3. diff --git a/draft-ietf-jose-json-proof-token.md b/draft-ietf-jose-json-proof-token.md index db30ee6..8e9ee03 100644 --- a/draft-ietf-jose-json-proof-token.md +++ b/draft-ietf-jose-json-proof-token.md @@ -52,7 +52,7 @@ JSON Proof Token (JPT) is a compact, URL-safe, privacy-preserving representation JSON Proof Token (JPT) is a compact claims representation format intended to be used in the same ways as a JSON Web Token (JWT), but with additional support for selective disclosure and unlinkability. JPTs encode claim values to be transmitted as payloads of a JSON Web Proof (JWP) [@!I-D.ietf-jose-json-web-proof]. JPTs are always represented using the JWP Compact Serialization. The corresponding claim names are not transmitted in the payloads and are stored in a separate structure that can be externalized and shared across multiple JPTs. -> Editor's Note: This draft is still early and incomplete, there will be significant changes to the algorithms as currently defined here. Please do not use any of these definitions or examples for anything except personal experimentation and learning. Contributions and feedback are welcome at https://github.com/json-web-proofs/json-web-proofs. +> Editor's Note: This draft is still early and incomplete. There will be significant changes to the algorithms as currently defined here. Please do not use any of these definitions or examples for anything except personal experimentation and learning. Contributions and feedback are welcomed at https://github.com/json-web-proofs/json-web-proofs. # Conventions and Definitions @@ -65,7 +65,7 @@ JWP defines a container binding together a protected header, one or more payload # Design Considerations -The rationale behind the design for JSON Proof Tokens is important when considering how it is structured. These sections detail the underlying reasoning for the approach defined by JPTs. +The rationale behind the design for JSON Proof Tokens is important when considering how it is structured. These sections detail the underlying reasoning informing the JPT design. ## Unlinkability @@ -81,7 +81,7 @@ While JWPs provide the underling structure for easily supporting selective discl ## Familiarity -JPTs are intended to be as close to a JWT as possible in order to provide the simplest transition for any JWT-based system to add support for a JPT. +JPTs are intended to be as close to a JWT as possible in order to provide the simplest transition for any JWT-based system to add support for JPTs. Although there are some stark differences in the lifecycle of a JPT, from the application's perspective, the interface to a JPT can be made fairly similar: a JSON object containing a mix of required and optional claims with well-understood values. @@ -89,7 +89,7 @@ The most significant divergence required by JPTs is that of supporting values th ## Proofs -In order to generate a variety of efficient ZKPs of knowledge, range, membership, or other predicates, it is essential that each individual payload is only a single claim value. This greatly simplifies the task of linking a derived proof of a given claim to the specific payload that was also signed by the issuer. While JPTs support claims that have complex object or array compound values, they also allow for simple claim values such as JSON strings, numbers, and booleans that can be used directly in generating predicate proofs. +To generate a variety of efficient ZKPs of knowledge, range, membership, or other predicates, it is essential that each individual payload is only a single claim value. This greatly simplifies the task of linking a derived proof of a given claim to the specific payload that was also signed by the issuer. While JPTs support claims that have complex object or array compound values, they also allow for simple claim values such as JSON strings, numbers, and booleans that can be used directly in generating predicate proofs. # Claim Names @@ -101,7 +101,7 @@ Using a JSON Proof Token requires combining information from two sources: the cl When the claims array is stored in the header, any variations of it are disclosed to the verifier and can be used to correlate and link usages. Given the privacy design considerations around linkability it is recommended that the claims are defined external to an individual JPT and either referenced or known by the application context. -In order to facilitate this external definition of the claim names, an additional `cid` key is defined with a required digest value calculated as defined here. This `cid` can be used similar to a `kid` in order to ensure that is it possible to externally resolve and then verify that the correct list of claim names is being used when processing the payloads containing the claim values. +To facilitate this external definition of the claim names, an additional `cid` key is defined with a required digest value calculated as defined here. This `cid` can be used similar to a `kid` in order to ensure that is it possible to externally resolve and then verify that the correct list of claim names is being used when processing the payloads containing the claim values. If there is an associated JWK containing the signing key information, the `claims` key is also registered there as a convenient location for the claim names. @@ -133,7 +133,7 @@ The following is an example JWP Protected Header that includes a `cid`: # Payloads -> Editor's Note: This section is significantly incomplete, use it only as an indicator of the intended direction. +> Editor's Note: This section is incomplete. Use it only as an indicator of the intended direction. Application resolves each claim as required when processing the JPT. Resolution can result in one of three things: 1. A disclosed JSON value @@ -158,7 +158,7 @@ Always an octet string of valid JSON text. # Example JPT -See the JSON Web Proof draft appendix. +See the [@!I-D.ietf-jose-json-web-proof] appendix. # Security Considerations @@ -172,6 +172,8 @@ This document has no IANA actions. # Acknowledgements +This work was incubated in the DIF [Applied Cryptography Working Group](https://identity.foundation/working-groups/crypto.html). + We would like to thank Brent Zundel for his valuable contributions to this specification. @@ -180,6 +182,10 @@ for his valuable contributions to this specification. [[ To be removed from the final specification ]] + -03 + + * Improvements resulting from a full proofreading. + -02 * Update example to use the current BBS algorithm diff --git a/draft-ietf-jose-json-web-proof.md b/draft-ietf-jose-json-web-proof.md index 2a630bd..bdb3045 100644 --- a/draft-ietf-jose-json-web-proof.md +++ b/draft-ietf-jose-json-web-proof.md @@ -44,7 +44,7 @@ organization = "Self-Issued Consulting" .# Abstract -The JOSE set of standards established JSON-based container formats for [Keys](https://datatracker.ietf.org/doc/rfc7517/), [Signatures](https://datatracker.ietf.org/doc/rfc7515/), and [Encryption](https://datatracker.ietf.org/doc/rfc7516/). They also established [IANA registries](https://www.iana.org/assignments/jose/jose.xhtml) to enable the algorithms and representations used for them to be extended. Since those were created, newer cryptographic algorithms that support selective disclosure and unlinkability have matured and started seeing early market adoption. +The JOSE set of standards established JSON-based container formats for Keys, Signatures, and Encryption. They also established IANA registries to enable the algorithms and representations used for them to be extended. Since those were created, newer cryptographic algorithms that support selective disclosure and unlinkability have matured and started seeing early market adoption. This document defines a new container format similar in purpose and design to JSON Web Signature (JWS) called a _JSON Web Proof (JWP)_. Unlike JWS, which integrity-protects only a single payload, JWP can integrity-protect multiple payloads in one message. It also specifies a new presentation form that supports selective disclosure of individual payloads, enables additional proof computation, and adds a protected header to prevent replay and support binding mechanisms. @@ -52,7 +52,7 @@ This document defines a new container format similar in purpose and design to JS # Introduction -The JOSE specifications are very widely deployed and well supported, enabling use of cryptographic primitives with a JSON representation. JWTs [@RFC7519] are one of the most common representations for identity and access claims. For instance, they are used by the OpenID Connect and Secure Telephony Identity Revisited (STIR) standards. Also, JWTs are used by W3C's Verifiable Credentials and are used in many Decentralized Identity systems. +The JOSE specifications are very widely deployed and well supported, enabling use of cryptographic primitives with a JSON representation. JWTs [@RFC7519] are one of the most common representations for identity and access claims. For instance, they are used by the OpenID Connect and Secure Telephony Identity Revisited (STIR) standards. Also, JWTs are used by W3C's Verifiable Credentials and are used in many decentralized identity systems. With these new use cases, there is an increased focus on adopting privacy-protecting cryptographic primitives. While such primitives are still an active area of academic and applied research, the leading candidates introduce new patterns that are not currently supported by JOSE. These new patterns are largely focused on two areas: supporting selective disclosure when presenting information and minimizing correlation through the use of Zero-Knowledge Proofs (ZKPs) in addition to traditional signatures. @@ -75,7 +75,7 @@ All of these follow the same pattern of taking multiple claims (a.k.a., "attribu 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. -The roles of "issuer", "holder", and "verifier" are used as defined by the [Verifiable Credentials Data Model v1.1](https://www.w3.org/TR/2021/REC-vc-data-model-20211109/). The term "presentation" is also used as defined by this source, but the term "credential" is avoided in this specification in order to minimize confusion with other definitions. +The roles of "issuer", "holder", and "verifier" are used as defined by the VC Data Model [@VC-DATA-MODEL-2.0]. The term "presentation" is also used as defined by this source, but the term "credential" is avoided in this specification to minimize confusion with other definitions. ## Abbreviations @@ -86,23 +86,25 @@ The roles of "issuer", "holder", and "verifier" are used as defined by the [Veri # Background -A _JSON Web Proof (JWP)_ is very similar to a JWS [@RFC7515], with the addition that it can contain multiple individual secured payloads instead of a singular one. JWP-supporting algorithms are then able to separate and act on the individual payloads contained within. +A _JSON Web Proof (JWP)_ is very similar to a JWS [@RFC7515], with the addition that it can contain multiple individual secured payloads instead of a single one. JWP-supporting algorithms are then able to separate and act on the individual payloads contained within. The intent of JSON Web Proofs is to establish a common container format for multiple payloads that can be integrity-verified against a cryptographic proof value also in the container. It does not create or specify any cryptographic protocols, multi-party protocols, or detail any algorithm-specific capabilities. -In order to fully support the newer privacy primitives, JWP introduces the three roles of issuer, holder, and verifier as defined by the VC Data Model. There are also two forms of a JWP: the issued form created by an issuer for a holder, and the presented form created by a holder for a verifier. +To fully support the newer privacy primitives, JWP utilizes the three roles of issuer, holder, and verifier, as defined by the VC Data Model [@VC-DATA-MODEL-2.0]. There are also two forms of a JWP: the issued form created by an issuer for a holder, and the presented form created by a holder for a verifier. -A JWP is initially created by the issuer using the `issue` interaction with an implementation. A successful result is an issued JWP that has a single issuer-protected header, one or more payloads, and an initial proof value that contains the issuing algorithm output. The holder, upon receiving an issued JWP, then uses `confirm` to check the integrity protection of the header and all payloads using the given proof value. +The four principal interactions used by JWP are `issue`, `confirm`, `present`, and `verify`. -After validation, the holder uses `present` to apply any selective disclosure choices, perform privacy-preserving transformations for unlinkability, and add a presentation-protected header that ensures the resulting presented JWP cannot be replayed. The verifier then uses `verify` to ensure the integrity protection of the protected headers and any disclosed payloads, along with verifying any additional ZKPs covering non-disclosed payloads. +A JWP is initially created by the issuer using the `issue` interaction. A successful result is an issued JWP that has a single issuer-protected header, one or more payloads, and an initial proof value that contains the issuing algorithm output. The holder, upon receiving an issued JWP, then uses the `confirm` interaction to check the integrity protection of the header and all payloads using the proof value. -While `issue` and `confirm` only occur when a JWP is initially created by the issuer, the `present` and `verify` steps may be safely repeated by a holder on an issued JWP. The unlinkability of the resulting presented JWP is only provided when supported by the underlying algorithm. +After validation, the holder uses the `present` interaction to apply any selective disclosure choices, perform privacy-preserving transformations for unlinkability, and add a presentation-protected header that ensures the resulting presented JWP cannot be replayed. The verifier then uses the `verify` interaction to ensure the integrity protection of the protected headers and any disclosed payloads, along with verifying any additional ZKPs covering non-disclosed payloads. -Algorithm definitions that support JWPs are being done in separate companion specifications - just as the JSON Web Algorithms [@RFC7518] specification does for JWS and JWE [@RFC7516]. The JSON Proof Algorithms (JPA) [@!I-D.ietf-jose-json-proof-algorithms] specification defines how an initial set of algorithms are used with JWP. +While `issue` and `confirm` only occur when a JWP is initially created by the issuer, the `present` and `verify` steps may be safely repeated by a holder on an issued JWP. He resulting presented JWP is only unlinkable when supported by the underlying algorithm. + +Algorithm definitions that support JWPs are in separate companion specifications - just as the JSON Web Algorithms [@RFC7518] specification does for JWS and JWE [@RFC7516]. The JSON Proof Algorithms (JPA) [@!I-D.ietf-jose-json-proof-algorithms] specification defines how an initial set of algorithms are used with JWP. # JWP Forms -A JWP is always in one of two forms: the issued form or the presented form. The significant difference between the two forms is the number of protected headers. An issued JWP has only one issuer protected header, while a presented JWP will have both the issuer protected header and an additional presentation protected header. Each protected header is a JSON object that is serialized as a UTF-8 encoded octet string. +A JWP is always in one of two forms: the issued form or the presented form. A structural difference between the two forms is the number of protected headers. An issued JWP has only one issuer protected header, while a presented JWP will have both the issuer protected header and an additional presentation protected header. Each protected header is a JSON object that is serialized as a UTF-8 encoded octet string. All JWP forms have one or more payloads; each payload is an octet string. The payloads are arranged in an array for which the ordering is preserved in all serializations. @@ -112,13 +114,13 @@ The JWP proof value is a single octet string that is only generated from and pro When a JWP is first created, it is always in the issued form. It will contain the issuer protected header along with all of the payloads. -The issued form can only be confirmed by a holder as being correctly formed and protected, it is NOT to be verified directly or presented as-is to a verifier. The holder SHOULD treat an issued JWP as private and use appropriately protected storage. +The issued form can only be confirmed by a holder as being correctly formed and protected. It is NOT to be verified directly or presented as-is to a verifier. The holder SHOULD treat an issued JWP as private and use appropriately protected storage. ### Issuer Protected Header The issuer protected header applies to all of the payloads equally. It is recommended that any payload-specific information not be included in this header and instead be handled outside of the cryptographic envelope. This is to minimize any correlatable signals in the metadata, to reduce a verifier's ability to group different presentations based on small header variations from the same issuer. -Every issuer protected header MUST have, at minimum, an `alg` value that identifies a valid JPA. +Every issuer protected header MUST have an `alg` value that identifies a valid JSON Proof Algorithm (JPA). For example: ```json @@ -145,7 +147,7 @@ When an issued JWP is presented, it undergoes a transformation that adds a prese When supported by the underling JPA, a single issued JWP can be used to safely generate multiple presented JWPs without becoming correlatable. -A JWP may also be single use, where an issued JWP can only be used once to generate a presented form, any additional presentations would be inherently correlatable. These are still useful for applications needing only selective disclosure or where new unique issued JWPs can be retrieved easily. +A JWP may also be single use, where an issued JWP can only be used once to generate a presented form. In this case, any additional presentations would be inherently correlatable. These are still useful for applications needing only selective disclosure or where new unique issued JWPs can be retrieved easily. ### Presentation Protected Header @@ -165,11 +167,11 @@ Algorithms MAY support including a proof about a payload in the presentation. A ### Presentation Proof -The proof value of a presented JWP will always be different than the issued proof. At a minimum it MUST be updated to include protection of the added presentation header. +The proof value of a presented JWP will always be different than the issued proof. At a minimum, it MUST be updated to include protection of the added presentation header. Algorithms SHOULD generate an un-correlatable presentation proof in order to support multiple presentations from a single issued JWP. -Any payload specific proofs are included in the single proof value for the presented JWP, the JPA is responsible for internally encoding multiple proof values into one and cryptographically binding them to a specific payload from the issuer. +Any payload specific proofs are included in the single proof value for the presented JWP. The JPA is responsible for internally encoding multiple proof values into one and cryptographically binding them to a specific payload from the issuer. # Serializations @@ -187,7 +189,7 @@ The headers, concatenated payloads, and proof value are then concatenated with a Non-disclosed payloads in the JSON serialization are represented with a `null` value in the `payloads` array. -Example flattened JSON serialization showing the presentation form with both the issuer and presentation headers along with the first and third payloads hidden. +This example flattened JSON serialization shows the presentation form with both the issuer and presentation headers, and with the first and third payloads hidden. ```json { @@ -226,7 +228,7 @@ Notes to be expanded: * Requirements for supporting algorithms, see JPA * Application interface for verification * Data minimization of the protected header -* In order to prevent accidentally introducing linkability, when an issuer uses the same key with the same grouping of payload types, they SHOULD also use the same issuer protected header. Each of these headers SHOULD have the same base64url-serialized value to avoid any non-deterministic JSON serialization. +* To prevent accidentally introducing linkability, when an issuer uses the same key with the same grouping of payload types, they SHOULD also use the same issuer protected header. Each of these headers SHOULD have the same base64url-serialized value to avoid any non-deterministic JSON serialization. # IANA Considerations @@ -235,6 +237,28 @@ This document has no IANA actions. {backmatter} + + + Verifiable Credentials Data Model 2.0 + + Digital Bazaar + + + OpenLink Software + + + W3C + + + Invited Expert + + + Block + + + + + # Example JWPs The following examples use algorithms defined in JSON Proof Algorithms and also contain the keys used, so that implementations can validate these samples. @@ -363,7 +387,7 @@ The third payload is the string `"jaydoe@example.org"` with the octet sequence o The fourth payload is the string `42` with the octet sequence of `[52, 50]` and base64url-encoded as `NDI`. -The Single Use algorithm utilizes multiple individual JWS Signatures. Each signature value is generated by creating a JWS with a single Protected Header with the associated `alg` value, in this example the fixed header used for each JWS is the serialized JSON Object `{"alg":"ES256"}`. The JWS payload for each varies and the resulting signature value is used in its unencoded form (the octet string, not the base64url-encoded form). +The Single Use algorithm utilizes multiple individual JWS Signatures. Each signature value is generated by creating a JWS with a single Protected Header with the associated `alg` value. In this example, the fixed header used for each JWS is the serialized JSON Object `{"alg":"ES256"}`. The JWS payload for each varies and the resulting signature value is used in its unencoded form (the octet string, not the base64url-encoded form). The first signature is generated by creating a JWS using the fixed header with the payload set to the octet string of the JPT protected header from earlier. The resulting JWS signature using the Signer's *stable key* is the octet string of: ```json @@ -417,7 +441,7 @@ The fourth payload signature is: ``` Figure: jwp-payload-3-signature -Each payload's individual signature is concatenated in order, resulting in a larger octet string with a length of an individual signature (64 octets for ES256) multiplied by the number of payloads (4 for this example). These payload ephemeral signatures are then appended to the initial protected header stable signature. Using the above examples, the resulting octet string is 320 in length (`5 * 64`): +Each payload's individual signature is concatenated in order, resulting in a larger octet string with a length of an individual signature (64 octets for ES256) multiplied by the number of payloads (4 for this example). These payload ephemeral signatures are then appended to the initial protected header stable signature. Using the above examples, the resulting octet string is 320 bytes in length (`5 * 64`): ```json [44, 147, 34, 55, 167, 26, 18, 164, 161, 48, 158, 99, 60, 219, 108, @@ -609,6 +633,8 @@ See JPA BBS-DRAFT-3 example. # Acknowledgements +This work was incubated in the DIF [Applied Cryptography Working Group](https://identity.foundation/working-groups/crypto.html). + We would like to thank Brent Zundel for his valuable contributions to this specification. @@ -622,6 +648,10 @@ for his valuable contributions to this specification. [[ To be removed from the final specification ]] + -03 + + * Improvements resulting from a full proofreading. + -02 * Update reference to current BBS algorithm