Web Authorization Protocol D. Fett Internet-Draft Authlete Inc. Intended status: Standards Track 14 February 2024 Expires: 17 August 2024 SD-JWT VC Type Metadata draft-fett-oauth-sd-jwt-vc-types-latest Abstract This specification describes metadata for SD-JWT based Verifiable Credentials. Discussion Venues This note is to be removed before publishing as an RFC. Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (oauth@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/oauth/. Source for this draft and an issue tracker can be found at https://github.com/vcstuff/sd-jwt-vc-types. 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 17 August 2024. 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 2. Example 3. Retrieving Metadata 3.1. From a URL in the vct Claim 3.2. From a Registry 3.3. Using a Defined Retrieval Method 3.4. From a Local Cache 3.5. From Type Metadata Glue Documents 4. Document Integrity 5. Metadata Format 6. Extending Metadata 7. Display Metadata 7.1. Rendering Metadata 7.1.1. Rendering Method "simple" 7.1.2. Rendering Method "svg_template" 8. Claim Metadata 8.1. Claim Display Metadata 8.2. Claim Verification Metadata 8.3. Claim Selective Disclosure Metadata 9. Schema 10. Security Considerations 10.1. Circular "extends" Dependencies 10.2. Robust Retrieval of Metadata 11. Privacy Considerations 11.1. Undescribed Claims 11.2. Privacy-Preserving Retrieval of Type Metadata 12. Normative References Appendix A. Acknowledgements Appendix B. Document History Author's Address 1. Introduction The SD-JWT VC specification [I-D.ietf-oauth-sd-jwt-vc] defines the JWT claim vct (for verifiable credential type). The vct value serves as an identifier for the type of the SD-JWT VC. A type is associated with rules defining which claims may or must appear in the SD-JWT VC and whether they may, must, or must not be selectively disclosable. This specification defines metadata that can be associated with a type as well as a method for retrieving the metadata and processing rules. This metadata is intended to be used, among other things, for the following purposes: * Developers of Issuers and Verifiers can use the metadata to understand the semantics of the type and the associated rules. While in some cases, Issuers are the parties that define types (credential formats), this is not always the case. For example, a type can be defined by a standardization body or a community. * Verifiers can use the metadata to determine whether a credential is valid according to the rules of the type. For example, a Verifier can check whether a credential contains all required claims and whether the claims are selectively disclosable. * Wallets can use the metadata to display the credential in a way that is consistent with the Issuer's intent. Applications using this specification are called "consuming applications" in the following. This typically includes Issuers, Verifiers, and Wallets. 2. Example All examples in this section are non-normative. In an SD-JWT VC, vct can be used to express a type. Metadata can be retrieved as described in Section 3. { "vct": "https://betelgeuse.example.com/education_credential", "vct#integrity": "sha256-WRL5ca_xGgX3c1VLmXfh-9cLlJNXN-TsMk-PmKjZ5t0", ... } Here, the type is https://betelgeuse.example.com/ education_credential. The metadata is retrieved from the URL https://betelgeuse.example.com/.well-known/vct/education_credential. The following is an example for a metadata document: { "vct":"https://betelgeuse.example.com/education_credential", "name":"Betelgeuse Education Credential - Preliminary Version", "description":"This is our development version of the education credential. Don't panic.", "extends":"https://galaxy.example.com/galactic-education-credential-0.9", "extends#integrity":"sha256-9cLlJNXN-TsMk-PmKjZ5t0WRL5ca_xGgX3c1VLmXfh-WRL5", "display":[ { "en-US":{ "name":"Betelgeuse Education Credential", "rendering":{ "simple":{ "logo":{ "uri":"https://betelgeuse.example.com/public/education-logo.png", "uri#integrity":"sha256-LmXfh-9cLlJNXN-TsMk-PmKjZ5t0WRL5ca_xGgX3c1V", "alt_text":"Betelgeuse Ministry of Education logo" }, "background_color":"#12107c", "text_color":"#FFFFFF" }, "svg_templates":[ { "uri":"https://betelgeuse.example.com/public/credential-english.svg", "uri#integrity":"sha256-8cLlJNXN-TsMk-PmKjZ5t0WRL5ca_xGgX3c1VLmXfh-9c", "properties":{ "orientation":"landscape", "color_scheme":"light", "contrast":"high" } } ] } }, "de-DE":{ "name":"Betelgeuse-Bildungsnachweis", "rendering":{ "simple":{ "logo":{ "uri":"https://betelgeuse.example.com/public/education-logo-de.png", "uri#integrity":"sha256-LmXfh-9cLlJNXN-TsMk-PmKjZ5t0WRL5ca_xGgX3c1V", "alt_text":"Logo des Betelgeusischen Bildungsministeriums" }, "background_color":"#12107c", "text_color":"#FFFFFF" }, "svg_templates":[ { "uri":"https://betelgeuse.example.com/public/credential-german.svg", "uri#integrity":"sha256-8cLlJNXN-TsMk-PmKjZ5t0WRL5ca_xGgX3c1VLmXfh-9c", "properties":{ "orientation":"landscape", "color_scheme":"light", "contrast":"high" } } ] } } } ], "claims":{ "/name":{ "display":{ "de-DE":{ "label":"Vor- und Nachname", "description":"Der Name des Studenten" }, "en-US":{ "label":"Name", "description":"The name of the student" } }, "verification":"verified", "sd":"allowed" }, "/degree":{ "display":{ "de-DE":{ "label":"Abschluss", "description":"Der Abschluss des Studenten" }, "en-US":{ "label":"Degree", "description":"Degree earned by the student" } }, "verification":"authoritative", "sd":"allowed" }, "/address":{ "display":{ "de-DE":{ "label":"Adresse", "description":"Adresse zum Zeitpunkt des Abschlusses" }, "en-US":{ "label":"Address", "description":"Address at the time of graduation" } }, "verification":"self-attested", "sd":"always" }, "/address/street_address":{ "display":{ "de-DE":{ "label":"Straße" }, "en-US":{ "label":"Street Address" } }, "verification":"self-attested", "sd":"always" } }, "schema_url":"https://exampleuniversity.com/public/credential-schema-0.9", "schema_url#integrity":"sha256-o984vn819a48ui1llkwPmKjZ5t0WRL5ca_xGgX3c1VLmXfh" } 3. Retrieving Metadata 3.1. From a URL in the vct Claim In an SD-JWT VC, a URI in the vct claim can be used to express a type. If the type is a URL, metadata can be retrieved from the URL https:///.well-known/vct/, i.e., by inserting /.well-known/vct after the authority part of the URL. The metadata is retrieved using the HTTP GET method. The response MUST be a JSON object as defined in Section 5. If the claim vct#integrity is present in the SD-JWT VC, its value vct#integrity MUST be an "integrity metadata" string as defined in Section Section 4. 3.2. From a Registry A consuming application MAY use a registry to retrieve metadata for a type, e.g., if the type is not a URL or if the consuming application does not have access to the URL. The registry MUST be a trusted registry, i.e., the consuming application MUST trust the registry to provide correct metadata for the type. The registry MUST provide the metadata in the same format as described in Section 5. 3.3. Using a Defined Retrieval Method Ecosystems MAY define additional methods for retrieving metadata. For example, a standardization body or a community MAY define a service which has to be used to retrieve metadata based on a URN in the vct claim. 3.4. From a Local Cache A consuming application MAY cache metadata for a type. If a hash for integrity protection is present in the metadata as defined in Section 4, the consuming application MAY assume that the metadata is static and can be cached indefinitely. Otherwise, the consuming application MUST use the Cache-Control header of the HTTP response to determine how long the metadata can be cached. 3.5. From Type Metadata Glue Documents Credentials MAY encode type metadata directly, providing it as "glue information" to the consumer. For JSON-serialized JWS-based credentials, such type metadata documents MAY be included in the unprotected header of the JWS. In this case, the key vctm MUST be used in the unprotected header and its value MUST be an array of base64url-encoded Type Metadata documents as defined in this specification. Multiple documents MAY be included for providing a whole chain of types to the consuming application (see Section 6). A consuming application of a credential MAY use the documents in the vctm array instead of retrieving the respective metadata elsewhere as follows: * When resolving a vct in a credential, the consuming application MUST ensure that the vct claim in the credential matches the one in the metadata document, and it MUST verify the integrity of the metadata document as defined in Section 4. The consuming application MUST NOT use the metadata if no hash for integrity protection was provided in vct#integrity. * When resolving an extends property in a metadata document, the consuming application MUST ensure that the value of the extends property in the metadata document matches that of the vct in the metadata document, and it MUST verify the integrity of the metadata document as defined in Section 4. The consuming application MUST NOT use the metadata if no hash for integrity protection was provided. 4. Document Integrity Both the vct claim in the SD-JWT VC and various URIs in the metadata document MAY be accompanied by a respective claim suffixed with #integrity, in particular: * vct, * extends, * schema_url, * uri in the logo property. The value MUST be an "integrity metadata" string as defined in Section 3 of [W3C.SRI]. A consuming application of the respective documents MUST verify the integrity of the retrieved document as defined in Section 3.3.5 of [W3C.SRI]. 5. Metadata Format The metadata document MUST be a JSON object. The following properties are defined: * name: A human-readable name for the type, intended for developers reading the JSON document. This property is OPTIONAL. * description: A human-readable description for the type, intended for developers reading the JSON document. This property is OPTIONAL. * extends: A URI of another type that this type extends, as described in Section 6. This property is OPTIONAL. * display: An object containing display information for the type, as described in Section 7. This property is OPTIONAL. * claims: An object containing claim information for the type, as described in Section 8. This property is OPTIONAL. * schema: An embedded JSON Schema document describing the structure of the credential as described in Section 9. This property is OPTIONAL. MUST NOT be used if schema_url is present. * schema_url: A URL pointing to a JSON Schema document describing the structure of the credential as described in Section 9. This property is OPTIONAL. MUST NOT be used if schema is present. 6. Extending Metadata A type can extend another type. The extended type is identified by the URI in the extends property. The consuming application MUST retrieve and process metadata for the extended type before processing the metadata for the extending type. The extended type MAY itself extend another type. This can be used to create a chain or hierarchy of types. The security considerations described in Section 10.1 apply in order to avoid problems with circular dependencies. The following processing rules apply for extending types (recursively for all extended types): * The display property of the extending type MUST be used for display purposes. If there is no such property, the display property of the extended type MAY be used. * For any particular claim, the respective property in claims of the extending type MUST be used for validation purposes if it exists. If there is no such property, the respective property of the extended type MUST be used. * The schema or schema_url property of the extending type MUST be evaluated for validation purposes if it exists. Afterwards, or if there is no such property, the schema property of the extended type MUST evaluated. This means that all schemas in the chain of extended types MUST be evaluated for a particular credential. 7. Display Metadata The display property is an object containing display information for the type. The object MUST contain a property for each language that is supported by the type. The property name MUST be a language tag as defined in Section 2 of [RFC5646]. The property value MUST be an object containing the following properties: * name: A human-readable name for the type, intended for end users. This property is OPTIONAL. * description: A human-readable description for the type, intended for end users. This property is OPTIONAL. * rendering: An object containing rendering information for the type, as described in Section 7.1. This property is OPTIONAL. 7.1. Rendering Metadata The rendering property is an object containing rendering information for the type. The object MUST contain a property for each rendering method that is supported by the type. The property name MUST be a rendering method identifier and the property value MUST be an object containing the properties defined for the rendering method. 7.1.1. Rendering Method "simple" The simple rendering method is intended for use in applications that do not support SVG rendering. The object MUST contain the following properties: * logo: An object containing information about the logo to be displayed for the type, as described in Section 7.1.1.1. This property is OPTIONAL. * background_color: A CSS color value for the background of the credential. This property is OPTIONAL. * text_color: A CSS color value for the text of the credential. This property is OPTIONAL. 7.1.1.1. Logo Metadata The logo property is an object containing information about the logo to be displayed for the type. The object contains the following properties: * uri: A URI pointing to the logo image. This property is REQUIRED. * uri#integrity: An "integrity metadata" string as described in Section 4. This property is OPTIONAL. * alt_text: A string containing alternative text for the logo image. This property is OPTIONAL. 7.1.2. Rendering Method "svg_template" The svg_template rendering method is intended for use in applications that support SVG rendering. The object MUST contain an array of objects containing information about the SVG templates available for the type. Each object contains the following properties: * uri: A URI pointing to the SVG template. This property is REQUIRED. * uri#integrity: An "integrity metadata" string as described in Section 4. This property is OPTIONAL. * properties: An object containing properties for the SVG template, as described in Section 7.1.2.1. This property is REQUIRED if more than one SVG template is present, otherwise it is OPTIONAL. 7.1.2.1. SVG Template Properties The properties property is an object containing properties for the SVG template. Consuming applications MUST use these properties to find the best SVG template available for display to the user based on the display properties (landscape/portrait) and user preferences (color scheme, contrast). The object MUST contain at least one of the following properties: * orientation: The orientation for which the SVG template is optimized, with valid values being portrait and landscape. This property is OPTIONAL. * color_scheme: The color scheme for which the SVG template is optimized, with valid values being light and dark. This property is OPTIONAL. * contrast: The contrast for which the SVG template is optimized, with valid values being normal and high. This property is OPTIONAL. 8. Claim Metadata The claims property is an object containing information about particular claims for displaying and validating the claims. The object MAY contain a property for each claim that is supported by the type. The property name MUST be a JSON Pointer [RFC6901] pointing to the claim in the credential. The property value MUST be an object containing the following properties: * display: An object containing display information for the claim, as described in Section 8.1. This property is OPTIONAL. * verification: A string indicating how the claim is verified, as described in Section 8.2. This property is OPTIONAL. * sd: A string indicating whether the claim is selectively disclosable, as described in Section 8.3. This property is OPTIONAL. Note: The JSON Pointer MUST point to the respective claim as if all selectively disclosable claims were disclosed to the Verifier. That means that a consuming application which does not have access to all disclosures may not be able to validate the claim. 8.1. Claim Display Metadata The display property is an object containing display information for the claim. The object MUST contain a property for each language that is supported by the type. The property name MUST be a language tag as defined in Section 2 of [RFC5646]. The consuming application MUST use the language tag it considers most appropriate for the user. The property value MUST be an object containing the following properties: * label: A human-readable label for the claim, intended for end users. This property is OPTIONAL. * description: A human-readable description for the claim, intended for end users. This property is OPTIONAL. 8.2. Claim Verification Metadata The verification property is a string indicating how the claim is verified. The following values are defined: * self-attested: The claim's value was self-attested by the End-User towards the Issuer. The Issuer did not verify the claim. For example, in a diploma, the residential address of the student may be self-attested. * verified: The claim's value was verified by the Issuer. The Issuer may have used a third party to verify the claim. For example, in a diploma, the birth date of the student may have been verified by the university using the student's passport. * authoritative: The Issuer claims to be the authority to make a statement about the claim's value. For example, in a diploma, the degree earned by the student may be authoritative if the Issuer is the university that issued the degree. 8.3. Claim Selective Disclosure Metadata The sd property is a string indicating whether the claim is selectively disclosable. The following values are defined: * always: The Issuer MUST make the claim selectively disclosable. * allowed: The Issuer MAY make the claim selectively disclosable. * never: The Issuer MUST NOT make the claim selectively disclosable. 9. Schema If a schema or schema_url property is present, a consuming application that intends to validate the credential (in particular, Verifiers) MUST validate the credential against the provided JSON Schema document. 10. Security Considerations 10.1. Circular "extends" Dependencies A type MUST NOT extend another type that extends (either directly or with steps in-between) the first type. This would result in a circular dependency that could lead to infinite recursion when retrieving and processing the metadata. Consuming applications MUST detect such circular dependencies and reject the credential. 10.2. Robust Retrieval of Metadata In Section 3, various methods for distributing and retrieving metadata are described. Methods relying on a network connection may fail due to network issues or unavailability of a network connection due to offline usage of credentials, temporary server outages, or denial of service attacks on the metadata server. Consuming applications SHOULD therefore implement a local cache as described in Section 3.4 if possible. Such a cache MAY be populated with metadata before the credential is used. Issuers MAY provide glue documents as described in Section 3.5 to provide metadata directly with the credential and avoid the need for network requests. These measures allow the consuming application to continue to function even if the metadata server is temporarily unavailable and avoid privacy issues as described in Section 11.2. 11. Privacy Considerations 11.1. Undescribed Claims A Wallet MUST always ensure that all claims that are disclosed to a Verifier are also displayed to the user as appropriate for the use case. If there is no information about the claim in the claims section of the metadata, the Wallet MUST either fall back to show the user the 'raw' claim value or MUST NOT disclose the claim to the Verifier. 11.2. Privacy-Preserving Retrieval of Type Metadata In Section 3, various methods for distributing and retrieving metadata are described. For methods which rely on a network connection to a URL (e.g., provided by an Issuer), third parties (like the Issuer) may be able to track the usage of a credential by observing requests to the metadata URL. Consuming applications SHOULD prefer methods for retrieving metadata that do not leak information about the usage of a credential to third parties. The recommendations in Section 10.2 apply. 12. Normative References [I-D.ietf-oauth-sd-jwt-vc] Terbu, O. and D. Fett, "SD-JWT-based Verifiable Credentials (SD-JWT VC)", Work in Progress, Internet- Draft, draft-ietf-oauth-sd-jwt-vc-01, 23 October 2023, . [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, September 2009, . [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., "JavaScript Object Notation (JSON) Pointer", RFC 6901, DOI 10.17487/RFC6901, April 2013, . [W3C.SRI] Akhawe, D., Braun, F., Marier, F., and J. Weinberger, "Subresource Integrity", 23 June 2016, . Appendix A. Acknowledgements The SVG rendering method is based on work of the W3C CCG: https://w3c-ccg.github.io/vc-render-method/ (https://w3c- ccg.github.io/vc-render-method/) The authors would like to thank the following people for their contributions to this document and the discussions around it: Giuseppe De Marco, Paul Bastian, Alen Horvat, Oliver Terbu, Torsten Lodderstedt, Kristina Yasuda Appendix B. Document History Individual draft -00 * Initial version * Added three new retrieval methods to Section 3 * Added security and privacy considerations * Added vct claim to Section 2 * Added Kristina and Alen to Acknowledgements Author's Address Daniel Fett Authlete Inc. Email: mail@danielfett.de