JSON Web Proof

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 24 April 2025.¶

Copyright Notice

Copyright (c) 2024 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

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 or COSE. 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.¶

There are a growing number of these cryptographic primitives that support selective disclosure while protecting privacy across multiple presentations. Examples used in the context of Verifiable Credentials are:¶

• CL Signatures¶
• IDEMIX¶
• BBS signatures, described in [I-D.irtf-cfrg-bbs-signatures]¶
• MerkleDisclosureProof2021¶
• Mercurial Signatures¶
• PS Signatures¶
• U-Prove¶
• Spartan¶

All of these follow the same pattern of taking multiple claims (a.k.a., "attributes" or "messages" in the literature) and binding them together into a single issued token. These are then later securely one-way transformed into a presentation that reveals potentially only a subset of the original claims, predicate proofs about the claim values, or proofs of knowledge of the claims.¶

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/ietf-wg-jose/json-web-proof.¶

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

3. Background

A JSON Web Proof (JWP) is very similar to a JWS [RFC7515] or COSE Signed Message [RFC8152], 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 Proof 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.¶

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

The four principal interactions used by JWP are issue, confirm, present, and verify.¶

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

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

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

4. JWP Header

A JWP Header is a set of Header Parameters that apply to the JWP. These Header Parameters may be specific to the proof applied to the JWP, they may identify the party issuing the proof, and they may describe the application purpose and format of the JWP, as well as provide other potential metadata.¶

A Header Parameter may be represented as JSON or as CBOR. When represented using JSON, each Header Parameter has a string label and has a JSON-structured value within a JSON Object. When described using CBOR, each parameter has either an integer (int) or string (tstr) label, and has a CBOR-structured value within a CBOR map.¶

The Header Parameter labels within the JWP Header MUST be unique. CBOR processing MUST reject messages if two headers with the same parameter label are encountered. JSON processing SHOULD reject messages received with the same parameter label, but MAY instead represent only the lexically last member with that label, as specified in Section 15.12 ("The JSON Object") of ECMAScript 5.1 [ECMAScript]. JSON processing MUST take one of these two approaches with regards to encountering duplicate header parameter labels.¶

Implementations are required to understand the specific Header Parameters defined by this specification that are designated as "MUST be understood" and process them in the manner defined in this specification. All other Header Parameters defined by this specification that are not so designated MUST be ignored when not understood. Unless listed as a critical Header Parameter, per Section 4.2.4, all Header Parameters not defined by this specification MUST be ignored when not understood.¶

5. JWP Forms

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

The JWP proof value is one or more octet strings that are only meant to be generated from and processed by the underlying JPA. Internally, the proof value may contain one or more cryptographic statements that are used to check the integrity protection of the header(s) and all payloads. Each of these statements may be a ZKP or a traditional cryptographic signature. The algorithm is responsible for how these statements are serialized into a single proof value.¶

{
  "alg": "BBS"
}

6. Serializations

Each disclosed payload MUST be base64url encoded when preparing it to be serialized. The headers and proof are also individually base64url encoded.¶

Like JWS, JWP supports both a Compact Serialization and a JSON Serialization. These serializations both represent the same JSON-based Protected Header, payloads and proof, and are thus interchangeable without breaking the proof value.¶

A CBOR-based serialization is also defined, which uses the CBOR for describing Header Parameters. While this supports the same data model and algorithms, the difference in header representations does not allow interchangeability with the Compact Serialization and JSON Serializations.¶

eyJhbGciOiJCQlMiLCJhdWQiOiJodHRwczovL3JlY2lwaWVudC5leGFtcGxlLmNvbSIsI
m5vbmNlIjoid3JtQlJrS3RYalEifQ.eyJraWQiOiJIamZjcHlqdVpRLU84WWUyaFFuTmJ
UOVJiYm5yb2JwdGRuRXhSMERValU4IiwiYWxnIjoiQkJTIn0.MTcxNDUyMTYwMA~MTcxN
zE5OTk5OQ~IkRvZSI~IkpheSI~~~.iJG8Vt5P9LYtHStXxWF9lbxGi5x3lJ19MsGdrek-
66i5ycvEFm1amYe5kjIaZHhgiO0H2I1uQlhsyp88-lNLpGOM_XDzZwYqf4HTkLzorpGR5
UVJrYLzP4HYAbdPChG8tfv9VxWarRRstGlNleoIf8qkUjvhbHWevX14Hjj102lif5aG4j
Eh71pYkifmUxARJARKboAv2YWO8rCuzSy4NejsK81X6W93KJW8A_Om9z9myaqflqRP0Jp
70z4r2tYDBVDaOLCMd5DadMR6cfFkKDQMx-qCtb6rqxWRXwupEfie3PmRGHtOtJFN7RZA
v-TcQFREFqMnc80VYJFJhsbzaPjsSDcfyP-omMbr9bIg4F4wTFHrAtlFVYY_YdG_07Dcz
JcTv35A6EdIaTpy9q_NCGlTj_wdRh0p3uNjZAKDG7as9dyQCzRALwiheQL03gtiTx4USV
8yo2UXdsG-5hba4EYMs3YN2iwStQh91ZfzXRw

{
  "presentation": "eyJhbGciOiJCQlMiLCJhdWQiOiJodHRwczovL3JlY2lwaWVudC
       5leGFtcGxlLmNvbSIsIm5vbmNlIjoid3JtQlJrS3RYalEifQ",
  "issuer": "eyJraWQiOiJIamZjcHlqdVpRLU84WWUyaFFuTmJUOVJiYm5yb2JwdGRu
       RXhSMERValU4IiwiYWxnIjoiQkJTIn0",
  "payloads": [
    "MTcxNDUyMTYwMA",
    "MTcxNzE5OTk5OQ",
    "IkRvZSI",
    "IkpheSI",
    null,
    null,
    null
  ],
  "proof": [
    "iJG8Vt5P9LYtHStXxWF9lbxGi5x3lJ19MsGdrek-66i5ycvEFm1amYe5kjIaZHhg
       iO0H2I1uQlhsyp88-lNLpGOM_XDzZwYqf4HTkLzorpGR5UVJrYLzP4HYAbdPCh
       G8tfv9VxWarRRstGlNleoIf8qkUjvhbHWevX14Hjj102lif5aG4jEh71pYkifm
       UxARJARKboAv2YWO8rCuzSy4NejsK81X6W93KJW8A_Om9z9myaqflqRP0Jp70z
       4r2tYDBVDaOLCMd5DadMR6cfFkKDQMx-qCtb6rqxWRXwupEfie3PmRGHtOtJFN
       7RZAv-TcQFREFqMnc80VYJFJhsbzaPjsSDcfyP-omMbr9bIg4F4wTFHrAtlFVY
       Y_YdG_07DczJcTv35A6EdIaTpy9q_NCGlTj_wdRh0p3uNjZAKDG7as9dyQCzRA
       LwiheQL03gtiTx4USV8yo2UXdsG-5hba4EYMs3YN2iwStQh91ZfzXRw"
  ]
}

CBOR_JWP_Issued = [
       IssuerHeader : serialized_map,
       payloads : [payload] / nil,
       proofs : [bstr]
   ]

CBOR_JWP_Presented = [
      PresenterHeader : serialized_map,
      IssuerHeaders : serialized_map,
      payloads : [payload] / nil,
      proofs : [bstr]
   ]

empty_or_serialized_map = bstr .cbor header_map

payload = bstr / nil

Tagged_CBOR_JWP_Issued = #6.xxx (CBOR_JWP_Issued)

Tagged_CBOR_JWP_Presented = #6.yyy (CBOR_JWP_Presented)

7. Encrypted JSON Web Proofs

Access to JWPs containing non-public material by parties without legitimate access to the non-public information MUST be prevented. This can be accomplished by encrypting the JWP when potentially observable by such parties to prevent the disclosure of private information. The use of an Encrypted JWP is recommended for this purpose. The processing of Encrypted JWPs is identical to the processing of other JWEs.¶

For a JWP with JSON-formatted headers, an Encrypted JWP is a JWE [RFC7516] with a JWP in Compact Serialization as its plaintext value. For a JWP with CBOR-formatted headers, an Encrypted JWP should use COSE_Encrypt0 or COSE_Encrypt [RFC9052] with the CBOR Serialization as its plaintext.¶

The cty (content type) JWE/COSE Header Parameter is used to indicate that the content of the JWE is a JWP. The cty value of the JWE/COSE message SHOULD be the same as the typ (type) JWP Header Parameter value of the unencrypted JWP to be encrypted. If the JWP has no typ value, then the following JWE Header Parameter cty (content type) values SHOULD be used:¶

• jwp is used to indicate that the content of the JWE is a JWP using the JWP Compact Serialization.¶
• jwp+json is used to indicate that the content of the JWE is the UTF-8 encoding of a JWP using the JWP JSON Serialization.¶
• jwp+cbor is used to indicate that the plaintext of the COSE message is a JWP in CBOR Serialization.¶

The cty (content type) Header Parameter MUST be present unless the application knows that the encrypted content is a JWP by another means or convention, in which case the cty value MAY be omitted.¶

8. Detached Payloads

In some contexts, it is useful to make statements about payloads which are not themselves contained within the JWP, similar to "Detached Content" in JWS [RFC7515].¶

For this purpose, the compact, JSON and CBOR serializations allow for all payloads to be omitted from a serialized form. While this is a legal serialization, it is not on its own able to be verified.¶

The recipient is expected to perform some sequence of steps defined by the application to recreate the array of payloads, including order and optionality. This effectively recreates the fully specified serialization of the JWP.¶

9. Security Considerations

Notes to be expanded:¶

• Requirements for supporting algorithms, see JPA¶
• Application interface for verification¶
• Data minimization of the protected header¶
• 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.¶

10. IANA Considerations

The following registration procedure is used for all the registries established by this specification.¶

Values are registered on a Specification Required [RFC5226] basis after a three-week review period on the [email protected] mailing list, on the advice of one or more Designated Experts. However, to allow for the allocation of values prior to publication, the Designated Experts may approve registration once they are satisfied that such a specification will be published.¶

Registration requests sent to the mailing list for review should use an appropriate subject (e.g., "Request to register JWP header parameter: example").¶

Within the review period, the Designated Experts will either approve or deny the registration request, communicating this decision to the review list and IANA. Denials should include an explanation and, if applicable, suggestions as to how to make the request successful. Registration requests that are undetermined for a period longer than 21 days can be brought to the IESG's attention (using the [email protected] mailing list) for resolution.¶

Criteria that should be applied by the Designated Experts includes determining whether the proposed registration duplicates existing functionality, whether it is likely to be of general applicability or useful only for a single application, and whether the registration description is clear.¶

IANA must only accept registry updates from the Designated Experts and should direct all requests for registration to the review mailing list.¶

It is suggested that multiple Designated Experts be appointed who are able to represent the perspectives of different applications using this specification, in order to enable broadly informed review of registration decisions. In cases where a registration decision could be perceived as creating a conflict of interest for a particular Expert, that Expert should defer to the judgment of the other Experts.¶

Appendix A. Acknowledgements

This work was incubated in the DIF Applied Cryptography Working Group.¶

We would like to thank Brent Zundel for his valuable contributions to this specification.¶

Appendix B. Document History

[[ To be removed from the final specification ]]¶

-07¶

• Changing primary editor¶
• Broad changes to define a CBOR serialization, which leverage new CBOR Protected Headers¶
• Deemphasis of JSON in some parts of the document to represent CBOR alternatives¶
• Rewrite Header Parameter parsing requirements for JSON to emphasize preference to fail on duplicate headers (to match CBOR behavior). Last-encountered remains as an option to match ECMA definition.¶
• Add option to use CoAP Formats for typ in CBOR mode to match COSE, as a compact indirection over full media types.¶
• Modify IANA registry template to account for CBOR Labels in header parameters¶
• Add application/jwp+cbor media type¶
• Modify example generation to use proof_key and presentation_key names¶
• Change proof_jwk to proof_key and presentation_jwk to presentation_key to better represent that the key may be JSON or CBOR-formatted.¶
• Moved the registry for proof_key and presentation_key to JWP where they are defined. Consolidated usage, purpose and requirements from algorith musage under these definitions.¶
• Clarified that proof_key and presentation_key are required by particular algorithms and are not more generally required for issued and presented JWPs.¶
• Move claims to JPT to live beside cid, and renumber CBOR labels so that they may be adjacent¶

-06¶

• Update reference to new repository home.¶
• Fixed #83: Added encrypted JWPs.¶
• Added additional clarification around the compact and JSON serializations¶
• Added text around fully detached payloads¶

-05¶

• Clarify the use of multiple octet strings in presentation proofs.¶
• Update BBS algorithm example in JSON serialization to show the proof as an array with a single octet string.¶
• Move single-use example appendix from JWP to JPA.¶
• Registered +jwp structured syntax suffix.¶

-04¶

• Refactoring figures and examples to be built from a common set across all three documents.¶

-03¶

• Improvements resulting from a full proofreading.¶
• Populated IANA Considerations section.¶
• Specified JWP Header Parameters.¶
• Specified representation of zero-length disclosed payloads for the compact serialization.¶
• Specified that algorithms may supply multiple octet strings for the proof, which are separated by ~ characters in the compact serialization.¶
• Updated to use BBS draft -05.¶
• Added Terminology Section.¶

-02¶

• Update reference to current BBS algorithm¶

-01¶

• Correct cross-references within group.¶

-00¶

• Created initial working group draft based on draft-jmiller-jose-json-web-proof-01¶

Authors' Addresses