SPICE SD-CWT

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 23 February 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

This document updates RFC8392, enabling the holder of a CWT to disclose or redact special claims marked disclosable by the issuer of a CWT. The approach is modeled after SD-JWT, with changes to align with conventions from CBOR Object Signing and Encryption (COSE). The ability to minimize disclosure of sensitive identity attributes, while demonstrating possession of key material and enabling a verifier to confirm the attributes have been unaltered by the issuer, is an important building block for many digital credential use cases. This specification brings selective disclosure capabilities to CWT, enabling application profiles to impose additional security criteria beyond the minimum security requirements this specification requires. Specific use cases are out of scope for this document. However, feedback has been gathered from a wide range of stakeholders, some of which is reflected in the examples provided in the appendix.¶

2. Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

The terminology used in this document is inherited from RFC8392, RFC9052 and RFC9053.¶

This document defines the following new terms related to concepts originally described in SD-JWT.¶

Selective Disclosure CBOR Web Token (SD-CWT)

A CWT with claims enabling selective disclosure with key binding.¶

Selective Disclosure Key Binding Token (SD-CWT-KBT)

A CWT used to demonstrate possession of a confirmation method, associated to an SD-CWT.¶

Salted Disclosed Claims

The salted claims disclosed via an SD-CWT.¶

Digested Salted Disclosed Claim

A hash digest of a Salted Disclosed Claims.¶

Redacted keys

The hashes of claims redacted from a map data structure.¶

Redacted elements

The hashes of elements redacted from an array data structure.¶

Presented Disclosed Claimset

The CBOR map containing zero or more Redacted keys or Redacted elements.¶

Validated Disclosed Claimset

The CBOR map containing all mandatory to disclose claims signed by the issuer, all selectively disclosed claims presented by the holder, and ommiting all instances of redacted_keys and redacted_element claims that are present in the original sd_cwt.¶

Issuer

An entity that produces a Selective Disclosure CBOR Web Token.¶

Holder

An entity that presents a Selective Disclosure CBOR Web Token which includes a Selective Disclosure Key Binding Token.¶

Partial Disclosure

When a subset of the original claims protected by the Issuer, are disclosed by the Holder.¶

Full Disclosure

When the full set of claims protected by the Issuer, is disclosed by the Holder.¶

Verifier

An entity that validates a Partial or Full Disclosure by a holder.¶

3. SD-CWT Issuance

SD-CWT is modeled after SD-JWT, with adjustments to align with conventions in CBOR and COSE.¶

An SD-CWT is a CWT containing the hash digest (the "blinded claim hash") of each blinded claim in redacted_values in the payload, and optionally the salted claim values (and often claim names) for the values that are actually disclosed in the sd_claims claim in the unprotected header. When blinding an individual item in an array, the value of the item is replaced with a dict containing only the special key "...".¶

redacted_element = { "...": bstr }

A Holder key binding CWT (#kbt) MUST be present in a sd_kbt claim in the unprotected header when presenting an SD-CWT to a Verifier. The sd_kbt claim can only be absent when the Issuer is providing the SD-CWT to the Holder.¶

An SD-CWT is a CWT containing zero or more Digested Salted Disclosed Claim, and zero or more Salted Disclosed Claims. The salt acts as a blinding factor, preventing a Verifier of an SD-CWT from learning claims that were not intentionally disclosed by a Holder.¶

The following informative CDDL is provided to explain the syntax for an SD-CWT presentation. A complete CDDL schema is in (#cddl).¶

Please note this example contains claims for demonstration of the disclosure syntax, such as swversion, address, and ``.¶

sd-cwt-presentation = #6.18([
   protected: bstr .cbor sd-protected,
   unprotected-presentation,
   payload: bstr .cbor sd-payload,
   signature: bstr
])

sd-protected = {
   &(typ: 16) ^ => "application/sd+cwt",
   &(alg: 1) ^ => int,
   * key => any
}

unprotected-presentation = {
   &(sd_kbt: TBD2) ^ => bstr .cbor kbt-cwt,
   ? &(sd_claims: TBD1) ^ => bstr .cbor [ + bstr .cbor salted ],
   * key => any
}

sd-payload = {
    ; standard claims
      &(iss: 1) ^ => tstr, ; "https://issuer.example"
      &(sub: 2) ^ => tstr, ; "https://device.example"
      &(aud: 3) ^ => tstr, ; "https://verifier.example"
    ? &(exp: 4) ^ => int,  ; 1883000000
    ? &(nbf: 5) ^ => int,  ; 1683000000
      &(iat: 6) ^ => int,  ; 1683000000
      &(cnf: 8) ^ => { * key => any }, ; key confirmation
    ? &(cnonce: 39) ^ => bstr,
    ;
    ; sd-cwt new claims
      &(sd_alg: TBD4) ^ => int,            ; -16 for sha-256
    ? &(redacted_values: TBD5) ^ => [ * bstr ],
    * key => any
}

Disclosures for named claims are structured as a 32 bit salt, the name of the redacted element, and the disclosed value. For disclosures of items in an array, the name is ommitted.¶

salted = salted-claim / salted-element
salted-claim = [
  bstr ;.size 16,     ; 128-bit salt
  (int / text),      ; claim name
  any                ; claim value
]
salted-element = [
  bstr ;.size 16,     ; 128-bit salt
  any                ; claim value
]

digested-salted-disclosed-claim = bstr;
salted-disclosed-claim = salted-claim / salted-element
salted-claim = [
  bstr .size 16,  ; 128-bit salt
  (int / text),   ; claim name
  any             ; claim value
]
salted-element = [
  bstr .size 16, ; 128-bit salt
  any            ; claim value
]
sd-cwt-cnf = COSE_Key / Encrypted_COSE_Key / kid
sd-cwt = [
  protected,
  unprotected: {
    ?(sd_claims: TBD1): bstr .cbor [ + salted-disclosed-claim ],
    ?(sd_kbt: TBD2): bstr .cbor sd-cwt-kbt,
  },
  payload :  bstr .cbor {
    ?(iss: 1) => tstr, ; "https://issuer.example"
    ?(sub: 2) => tstr, ; "https://device.example"
    ?(aud: 3) => tstr, ; "https://verifier.example"
    ?(exp: 4) => int,  ; 1883000000
    ?(nbf: 5) => int,  ; 1683000000
    ?(iat: 6) => int,  ; 1683000000
    &(cnf: 8) => sd-cwt-cnf,  ; 1683000000

    ?(sd_alg: TBD4) => int,             ; -16 for sha-256
    ?(redacted_keys: TBD5) => [         ; redacted map keys
      digested-salted-disclosed-claim
    ],

    ; redaction in an example map value that is an array
    &(example-array-key: -65537) => [
      123,
      { ; redacted array element
        &(redacted_element: TBD6) =>
        digested-salted-disclosed-claim
      },
      789,
      { ; redacted array element
        &(redacted_element: TBD6) =>
        digested-salted-disclosed-claim
      },
    ]
  }
  signature : bstr,
]

4. SD-CWT Presentation

Presentations of an SD-CWT by a Holder to a Verifier require the Holder to issue an SD-CWT-KBT.¶

The SD-CWT-KBT is essential to assuring the Verifier:¶

• a) the Holder of the SD-CWT controls the confirmation method chosen by the Issuer.¶

• b) the Holder's disclosures have not been tampered with since confirmation occured.¶

The SD-CWT-KBT prevents an attacker from copying and pasting disclosures, or from adding or removing disclosures without detection. Confirmation is established according to RFC 8747, using the cnf claim in the payload of the SD-CWT. The Digested Salted Disclosed Claim are included in the sd_hash claim in the payload of the SD-CWT-KBT.¶

The proof of possession associated with the confirmation claim in an SD-CWT is called the SD-CWT-KBT. As noted above, SD-CWT Issuance, sd_kbt SHALL be present in every presentation of an SD-CWT by a Holder to a Verifier.¶

kbt-cwt = #6.18([
   protected: bstr .cbor kbt-protected,
   kbt-unprotected,
   payload: bstr .cbor kbt-payload,
   signature: bstr
])

kbt-protected = {
   &(typ: 16)^ => "application/kb+cwt",
   &(alg: 1)^ => int,
   * key => any
}

kbt-unprotected = {
   * key => any
}

kbt-payload = {
      &(aud: 3) ^ => tstr, ; "https://verifier.example"
    ? &(exp: 4) ^ => int,  ; 1883000000
    ? &(nbf: 5) ^ => int,  ; 1683000000
      &(iat: 6) ^ => int,  ; 1683000000
      &(cnonce: 39) ^ => bstr,
      ; matches the hash of sd_claims in the presentation token
      &(sd_hash: TBD3) ^ => bstr,
    * key => any
}

Note that sd_hash is the digest using sd_alg of the sd_claims which are either Partially or Fully Redacted in the Presented SD-CWT.¶

The cnonce and audience are essential to assure the Verifier that the Holder is currently in control of the associated confirmation method, and that the holder intended to disclose the SD-CWT to the Verifier.¶

Note that cnonce is a bstr and MUST be treated as opaque to the Holder.¶

The details associated with these protocol parameters are out of scope for this document.¶

5. SD-CWT Validation

The exact order of the following steps MAY be changed, as long as all checks are performed before deciding if an SD-CWT is valid.¶

First the Verifier must validate the SD-CWT as described in Section 7.2 of [RFC8392].¶

After validation, the SD-CWT-KBT MUST be extracted from the unprotected header, and validated as described in Section 7.2 of [RFC8392].¶

The Verifier MUST confirm the sd_hash claim of the validated SD-CWT-KBT matches the hash of the sd_claims member of the unprotected header, using the hash algorithm obtained from the validated sd_alg claim of the SD-CWT.¶

Next, the Verifier MUST extract and decode the disclosed claims from the sd_claims in the unprotected header.¶

The decoded sd_claims are converted to an intermediate data structure called a Digest To Disclosed Claim Map which is used to transform the Presented Disclosed Claimset, into a Validated Disclosed Claimset.¶

The Verifier MUST compute the hash of each salted-disclosed-claim, in order to match each disclosed value to each entry of the Presented Disclosed Claimset.¶

One possible concrete representation of the intermediate data structure for the Digest To Disclosed Claim Map could be:¶

{
  &(digested-salted-disclosed-claim) => salted-disclosed-claim
}

The Verifier constructs an empty cbor map called the Validated Disclosed Claimset, and initializes it with all mandatory to disclose claims from the verified Presented Disclosed Claimset.¶

Next the Verifier performs a breadth first or depth first traversal of the Presented Disclosed Claimset, Validated Disclosed Claimset, using the Digest To Disclosed Claim Map to insert claims into the Validated Disclosed Claimset when they appear in the Presented Disclosed Claimset. By performing these steps, the recipient can cryptographically verify the integrity of the protected claims and verify they have not been tampered with. If there remain unused Digest To Disclosed Claim Map at the end of this procedure the SD-CWT MUST be considered invalid, as if the siganture had failed to verify. Otherwise the SD-CWT is considered valid, and the Validated Disclosed Claimset is now a CWT Claimset with no claims marked for redaction. Further validation logic can be applied to the Validated Disclosed Claimset, as it might normally be applied to a validated CWT claimset.¶

6. Examples

TBD - Provide more examples¶

/ cose-sign1 / 18([
  / protected / << {
    / alg / 1  : -35, / ES384 /
    / typ / 16 : "application/sd+cwt",
    / kid / 4  : 'https://issuer.example/cwt-key3'
  } >>,
  / unprotected / {
    / sd_claims / 17 : <<[  /these are the three disclosures/
        <<[
            /salt/   h'c93c7ff572c71e26',
            /claim/  "age_over_18",
            /value/  true
        ]>>,
        <<[
            /salt/   h'399c641e2aa18c1e',
            /claim/  "region",
            /value/  "ca" /California/
        ]>>,
        <<[
            /salt/   h'82501bb46c655f32',
            /value/  "4.1.7"
        ]>>
    ]>>,
    / sd_kbt    / 18 : << 18([
      / protected / << {
          / alg / 1 : -35 / ES384 /,
          / typ / 16 : "application/kb+cwt"
      } >>,
      / unprotected / {},
      / payload / << {
        / cnonce / 39    : h'e0a156bb3f',
        / aud     / 3    : "https://verifier.example",
        / iat     / 6    : 1783000000,
        / sd_alg  / 12 : -16,  /SHA-256/
        / sd_hash / 11 : h'c341bb4a5f3f'  /hash of sd_claims   /
                                            /using hash in sd_alg/
      } >>,
      / signature / h'1237af2e678945'
    ]) >>
  },
  / payload / << {
    / iss / 1   : "https://issuer.example",
    / sub / 2   : "https://device.example",
    / aud / 3   : "https://verifier.example",
    / exp / 4   : 1883000000,
    / iat / 6   : 1683000000,
    / cnf / 8   : {
      / cose key / 1 : {
        / alg: ES256 /  3: 35,
        / kty: EC2   /  1: 2,
        / crv: P-256 / -1: 1,
        / x / -2: h'768ed88626',
        / y / -3: h'6a48ccfd5d'
      }
    },
    / cnonce / 39 : h'12345678',
    / sd_hash / 11       : h'abcdef12',
    / sd_alg /  12       : -16, / SHA-256 /
    / redacted_keys / 13 : [
        h'abbdefef',  / redacted age_over_18 /
        h'132d75e7'  / redacted age_over_21 /
    ],
    / swversion / 271 : [
      "3.5.5",
      { "...": h'45dd87af'  /redacted version element/ }
    ],
    "address": {
        "country" : "us",            / United States /
        /redacted_keys/ 13 : [
            h'adb7060403da225b',  / redacted region /
            h'e04bdfc44d3d40bc'   / redacted post_code /
        ]
    }
  } >>,
  / signature / h'3337af2e66959614'
])

7. Security Considerations

Security considerations from COSE {RFC9052} and CWT {RFC8392} apply to this specificaton.¶

8. IANA Considerations

9. References

Appendix A. Complete CDDL Schema

sd-cwt-types = sd-cwt-presentation / sd-cwt-issued / kbt-cwt

sd-cwt-presentation = #6.18([
   protected: bstr .cbor sd-protected,
   unprotected-presentation,
   payload: bstr .cbor sd-payload,
   signature: bstr
])

sd-cwt-issued = #6.18([
   protected: bstr .cbor sd-protected,
   unprotected-issued,
   payload: bstr .cbor sd-payload,
   signature: bstr
])

kbt-cwt = #6.18([
   protected: bstr .cbor kbt-protected,
   kbt-unprotected,
   payload: bstr .cbor kbt-payload,
   signature: bstr
])

sd-protected = {
   &(typ: 16) ^ => "application/sd+cwt",
   &(alg: 1) ^ => int,
   * key => any
}

kbt-protected = {
   &(typ: 16)^ => "application/kb+cwt",
   &(alg: 1)^ => int,
   * key => any
}

unprotected-presentation = {
   &(sd_kbt: TBD2) ^ => bstr .cbor kbt-cwt,
   ? &(sd_claims: TBD1) ^ => [ +bstr .cbor salted ],
   * key => any
}

unprotected-issued = {
   ? &(sd_claims: TBD1) ^ => [ +bstr .cbor salted ],
   * key => any
}

kbt-unprotected = {
   * key => any
}

sd-payload = {
    ; standard claims
      &(iss: 1) ^ => tstr, ; "https://issuer.example"
      &(sub: 2) ^ => tstr, ; "https://device.example"
      &(aud: 3) ^ => tstr, ; "https://verifier.example"
    ? &(exp: 4) ^ => int,  ; 1883000000
    ? &(nbf: 5) ^ => int,  ; 1683000000
      &(iat: 6) ^ => int,  ; 1683000000
      &(cnf: 8) ^ => { * key => any }, ; key confirmation
    ? &(cnonce: 39) ^ => bstr,
    ;
    ; sd-cwt new claims
      &(sd_hash: TBD3) ^ => bstr,
      &(sd_alg: TBD4) ^ => int,            ; -16 for sha-256
    ? &(redacted_keys: TBD5) ^ => [ * bstr ],
    * key => any
}

kbt-payload = {
      &(aud: 3) ^ => tstr, ; "https://verifier.example"
    ? &(exp: 4) ^ => int,  ; 1883000000
    ? &(nbf: 5) ^ => int,  ; 1683000000
      &(iat: 6) ^ => int,  ; 1683000000
      &(cnonce: 39) ^ => bstr,
      &(sd_hash: TBD3) ^ => bstr,
    * key => any
}

;redacted_element = { "...": bstr }
salted = salted-claim / salted-element
salted-claim = [
  bstr ;.size 16,     ; 128-bit salt
  (int / text),      ; claim name
  any                ; claim value
]
salted-element = [
  bstr ;.size 16,     ; 128-bit salt
  any                ; claim value
]

key = int / text
TBD1 = 17
TBD2 = 18
TBD3 = 11
TBD4 = 12
TBD5 = 13

Appendix B. Comparison to SD-JWT

SD-CWT is modeled after SD-JWT, with adjustments to align with conventions in CBOR and COSE.¶

Appendix C. Implementation Status

Note to RFC Editor: Please remove this section as well as references to [BCP205] before AUTH48.¶

This section records the status of known implementations of the protocol defined by this specification at the time of posting of this Internet-Draft, and is based on a proposal described in [BCP205]. The description of implementations in this section is intended to assist the IETF in its decision processes in progressing drafts to RFCs. Please note that the listing of any individual implementation here does not imply endorsement by the IETF. Furthermore, no effort has been spent to verify the information presented here that was supplied by IETF contributors. This is not intended as, and must not be construed to be, a catalog of available implementations or their features. Readers are advised to note that other implementations may exist.¶

According to [BCP205], "this will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature. It is up to the individual working groups to use this information as they see fit".¶

Acknowledgments

The authors would like to thank those that have worked on similar items for providing selective disclosure mechanisms in JSON, especially: Brent Zundel, Roy Williams, Tobias Looker, Kristina Yasuda, Daniel Fett, Oliver Terbu, and Michael Jones.¶

Authors' Addresses