| Internet-Draft | sd-cwt | August 2023 |
| Prorock & Steele | Expires 3 March 2024 | [Page] |
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.¶
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 3 March 2024.¶
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.¶
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].¶
The following terminology is used throughout this document:¶
CBOR claims are cpommonly signed using COSE Sign1 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 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 whenever possible.¶
Figure 1: SD-CWT Issuance and Presentation Flow¶
+------------+
| |
| Issuer |
| |
+------------+
|
Issues
SD-CWT
|
v
+------------+
| |
| Holder |
| |
+------------+
|
Presents
SD-CWT
|
v
+-------------+
| |+
| Verifiers ||+
| |||
+-------------+||
+-------------+|
+-------------+
¶
An SD-CWT is a CWT containing the hash digests of the claim values combined with unique random salts and additional metadata for disclosed values. The SD-CWT 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 an object where claim names are mapped to hash digests of the claim values combined with unique random salts:¶
CWT-CLAIMS = (
CLAIM-NAME: HASH(SALT | CLAIM-VALUE)
)*
¶
In a case where an SD-CWT is sent with all information disclosed, 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 "disclosures" field in the unprotected header contains the mapping, the salt values, and any additional metadata that might be present in the unprotected header.¶
In a case where an SD-CWT is sent with only selected information disclosed, only the disclosed claims, mappings, and salts are added to the disclosure.¶
Disclosures are structured as a "claim-pair" with a 32 bit salt, and the byte string of the disclosed value.¶
claim-pair = {
1 => uint .size 4, ; 32-bit salt
2 => bstr ; disclosed value
}
¶
The CDDL fragment that represents the above text for COSE_Sign1 is provided below:¶
SD-CWT = [
protected,
unprotected: {
? disclosures: [* claim-pair] / nil
},
payload : bstr / nil,
signature : bstr,
]
¶
The issuer SHOULD take appropriate percautions to verify that the salts are unique random values to prevent vulnerability to rainbow table attacks against the hashes.¶
To verify an SD-CWT, the recipient extracts the protected CWT claims from the payload. These CWT claims contain hash digests of the original claim values combined with unique random salts.¶
The recipient MUST validate that the protected header values such as issuer, audience, and expiration match the expected values for this SD-CWT per the guidelines set forward in [RFC8392]. If any items do not match the expected or allowed values per [RFC8392] the SD-CWT MUST be rejected.¶
The payload and other protected claims MUST then be validated according to the section "Validating a CWT" in [RFC8392]. If the CWT is not a COSE_Sign or COSE_Sign1 the CWT MUST be rejected. If any validations according [RFC9052] instructions for validating a COSE_Sign/COSE_Sign1 object fail, the CWT MUST be rejected.¶
The recipient that checks for any disclosures in the unprotected header. If they are present, the the claim values and salts MUST be extracted from the unprotected header.¶
For each disclosed claim, the hash digest MUST be recomputed from the value and salt in the unprotected header. If the hash digest does not equal the corresponding digest in the payload the SD-CWT MUST be rejected.¶
By performing these steps, the recipient can cryptographically verify the integrity of the protected claims and verify they have not been tampered with or substituted after issuance by the trusted issuer. The disclosures provide the plaintext claim values for utilization by the recipient.¶
Holder binding links an SD-CWT to its intended recipient. It prevents misuse if the token is intercepted or stolen. Binding mechanisms include cryptographic key confirmation, biometric data inclusion, or embedding holder-specific claims. The description of exact mechanisms for holder binding are outside the scope of this document at the present time.¶
While optional, holder binding enhances SD-CWT security. It enables accountability by auditing actions to specific entities. For sensitive data, it augments trust by proving the claimant owns the token.¶
Issuers should assess their use case when considering holder binding. Where accountability and non-repudiation are critical, binding provides assurance the token reaches the intended holder. With thoughtful implementation, binding can customize SD-CWT without compromising user privacy. Proportional use of holder binding balances security, privacy and flexibility for SD-CWT applications.¶
Counter signatures allow an SD-CWT to be endorsed by additional entities beyond the original issuer. The counter signature is applied in the unprotected header, attesting to the validity of the primary SD-CWT signature over the protected claims.¶
Counter signatures provide multiple benefits for SD-CWT:¶
To utilize a counter signature, the primary SD-CWT is constructed and signed as normal. Then an additional signer computes the counter signature over the entire SD-CWT, including the original signature. This counter signature is placed in the unprotected header when transmitting the SD-CWT.¶
Recipients validate the counter signature after verifying the primary signature, ensuring endorsements by all involved entities. Care should be taken to ensure robust trust in both signature authorities when relying on counter signatures.¶
TBD - Describe common data structures in CDDL¶
All security considerations from COSE [RFC9052] 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.¶
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.¶
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.¶