None M. Prorock Internet-Draft mesur.io Intended status: Standards Track O. Steele Expires: 5 February 2024 Transmute 4 August 2023 Selective Disclosure CWTs (SD-CWT) draft-prorock-cose-sd-cwt-00 Abstract This document describes how to perform selective disclosure of claims withing a CBOR Web Token (CWT) [RFC8392] as well as how to create and verify those tokens. This document does not define any new cryptography. 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 5 February 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. Prorock & Steele Expires 5 February 2024 [Page 1] Internet-Draft sd-cwt August 2023 Table of Contents 1. Notational Conventions . . . . . . . . . . . . . . . . . . . 2 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 3. Selective disclosure of claims within a CWT . . . . . . . . . 2 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 2 3.2. Flow Diagram . . . . . . . . . . . . . . . . . . . . . . 3 3.3. Creating an SD-CWT . . . . . . . . . . . . . . . . . . . 4 3.4. Verifying an SD-CWT . . . . . . . . . . . . . . . . . . . 4 3.5. Holder Binding and other common scenarios . . . . . . . . 4 3.5.1. Holder Binding . . . . . . . . . . . . . . . . . . . 4 3.5.2. Counter Signatures . . . . . . . . . . . . . . . . . 5 3.6. Data Structures . . . . . . . . . . . . . . . . . . . . . 5 3.7. Examples . . . . . . . . . . . . . . . . . . . . . . . . 5 4. Security Considerations . . . . . . . . . . . . . . . . . . . 5 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 5.1. Media Type Registration . . . . . . . . . . . . . . . . . 5 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 6 7. Normative References . . . . . . . . . . . . . . . . . . . . 6 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 6 1. Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. 2. Terminology The following terminology is used throughout this document: signature The digital signature output. Claim Name The human-readable name used to identify a claim. Claim Key The CBOR map key used to identify a claim. Claim Value The CBOR map value representing the value of the claim. CWT Claims Set The CBOR map that contains the claims conveyed by the CWT. 3. Selective disclosure of claims within a CWT 3.1. Overview CBOR claims are cpommonly signed using COSE Sign1 (https://www.rfc- editor.org/rfc/rfc9052#section-4.2) where only one signature is placed on a particular message. There are many cases where a signer may wish to ensure that the authenticity of a message has not been compromised via a digital signature, but where they only wish to reveal some values of the original signed message. This document Prorock & Steele Expires 5 February 2024 [Page 2] Internet-Draft sd-cwt August 2023 outlines a precise method for formulating and transmitting these messages, encompassing elements such as claims, claim keys, and necessary data structures. This kind of signed information exchange proves particularly beneficial in scenarios where a CBOR Web Token (CWT) might transit via an intermediary before undergoing third-party verification. Frequently, such a third party might necessitate, or be permitted to access only a subset of the information encapsulated in the CWT. This proposed model facilitates selective data disclosure, while still preserving the ability to validate the original signature. This representation relies on claims registered in the IANA CBOR Web Token (CWT) Claims Registry (https://www.iana.org/assignments/cwt/ cwt.xhtml) whenever possible. 3.2. Flow Diagram Figure 1: SD-CWT Issuance and Presentation Flow +------------+ | | | Issuer | | | +------------+ | Issues SD-CWT | v +------------+ | | | Holder | | | +------------+ | Presents SD-CWT | v +-------------+ | |+ | Verifiers ||+ | ||| +-------------+|| +-------------+| +-------------+ Prorock & Steele Expires 5 February 2024 [Page 3] Internet-Draft sd-cwt August 2023 3.3. Creating an SD-CWT An SD-CWT is a CWT of the hash digests of the claim values with unique random salts and other metadata. It MUST be digitally signed using the issuer's private key. SD-CWT-CLAIMS = (METADATA, CWT-CLAIMS) SD-CWT = SD-CWT-CLAIMS | SIG(SD-CWT-CLAIMS, ISSUER-PRIV-KEY) CWT-CLAIMS is a simple object with claim names mapped to hash digests over the claim values with unique random salts: CWT-CLAIMS = ( CLAIM-NAME: HASH(SALT | CLAIM-VALUE) )* In a case where an SD-CWT is sent with all information disclose, the SD-CWT is sent together with the mapping of the plain-text claim values, the salt values, and potentially some other information. In this case, the the payload contains the CWT-CLAIMS, and the field "disclosures" contains the mapping, the salt values, and other metadata. In a case where an SD-CWT is sent with only some information discosed, only the desired claims, mappings, and salts are added to the disclosure. The CDDL fragment that represents the above text for COSE_Sign1 follows. SD-CWT = [ Headers, payload : bstr / nil, signature : bstr, disclosures: bstr / nil ] 3.4. Verifying an SD-CWT TBD - Describe verifiacation process 3.5. Holder Binding and other common scenarios 3.5.1. Holder Binding TBD - Discuss optioinality, mechanism, and value Prorock & Steele Expires 5 February 2024 [Page 4] Internet-Draft sd-cwt August 2023 3.5.2. Counter Signatures TBD- Discuss use with countersignatures in the unprotected header 3.6. Data Structures TBD - Describe common data structures in CDDL 3.7. Examples TBD - Provide examples 4. Security Considerations All security considerations from COSE [RFC8152] and CWT [RFC8392] SHOULD be followed. To maintain the integrity of the issued claims, the Selective Disclosure-CBOR Web Token (SD-CWT) MUST be signed by the issuer. Absence of this signature leaves the SD-CWT vulnerable to attackers, who can alter or append claims (for instance, modifying the "email" attribute to hijack the victim's account or inserting a fabricated academic qualification). The verifier is required to verify the signature on the SD-CWT to guarantee its authenticity and that no tampering has occurred post issuance. If the signature on the SD-CWT fails the verification process, the SD-CWT MUST be unequivocally rejected. 5. IANA Considerations 5.1. Media Type Registration This section will register the "application/sd-cwt" media type [RFC2046] in the "Media Types" registry [IANA.MediaTypes] in the manner described in RFC 6838 [RFC6838], which can be used to indicate that the content is a CWT. * Type name: application * Subtype name: sd-cwt * Required parameters: n/a * Optional parameters: n/a * Encoding considerations: binary * Security considerations: See the Security Considerations section of [RFC8392] * Interoperability considerations: n/a * Published specification: This Specification * Applications that use this media type: mesur.io, transmute Prorock & Steele Expires 5 February 2024 [Page 5] Internet-Draft sd-cwt August 2023 * Fragment identifier considerations: n/a * Additional information: Magic number(s): n/a File extension(s): n/ a Macintosh file type code(s): n/a * Person & email address to contact for further information: Michael Prorock, mprorock@mesur.io * Intended usage: COMMON * Restrictions on usage: none * Author: Michael Prorock, mprorock@mesur.io * Change controller: IESG * Provisional registration? Yes 6. Acknowledgements The authors would like to thank those that have worked on similar items for providing selective disclosure mechanisms in JSON, especially: Tobias Looker, Kristina Yasuda, Daniel Fett, Oliver Terbu, and Michael Jones. 7. Normative References [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types", RFC 2046, DOI 10.17487/RFC2046, November 1996, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, January 2013, . [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", RFC 8152, DOI 10.17487/RFC8152, July 2017, . [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, May 2018, . Authors' Addresses Michael Prorock mesur.io Email: mprorock@mesur.io Prorock & Steele Expires 5 February 2024 [Page 6] Internet-Draft sd-cwt August 2023 Orie Steele Transmute Email: orie@transmute.industries Prorock & Steele Expires 5 February 2024 [Page 7]