Secure Patterns for Internet CrEdentials O. Steele Internet-Draft Transmute Intended status: Informational 9 June 2024 Expires: 11 December 2024 Credential Type Assertions draft-steele-spice-cta-00 Abstract Requirements for physical supply chain credentials are subject to frequent changes due to regulatory, logistic and market pressures. Preventing fraud and counterfeiting requires strong cryptographic assurance and binding to identities for people, organizations, vehicles and devices. New information regarding a credential subject needs to be conveyed by holders to verifier, after credential issuance. This specification describes the role of credential types or schemas in supporting changing requirements and realtime information regarding digital credentials. About This Document This note is to be removed before publishing as an RFC. The latest revision of this draft can be found at https://OR13.github.io/draft-steele-spice-cta/draft-steele-spice- cta.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-steele-spice-cta/. Discussion of this document takes place on the Secure Patterns for Internet CrEdentials Working Group mailing list (mailto:spice@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/spice/. Subscribe at https://www.ietf.org/mailman/listinfo/spice/. Source for this draft and an issue tracker can be found at https://github.com/OR13/draft-steele-spice-cta. 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/. Steele Expires 11 December 2024 [Page 1] Internet-Draft Credential Type Assertions June 2024 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 11 December 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 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5 4. Entity Identifiers . . . . . . . . . . . . . . . . . . . . . 6 5. Credential & Token Types . . . . . . . . . . . . . . . . . . 7 5.1. Schemas . . . . . . . . . . . . . . . . . . . . . . . . . 8 6. Confirmation . . . . . . . . . . . . . . . . . . . . . . . . 9 7. Status . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 8. Verifier Policies . . . . . . . . . . . . . . . . . . . . . . 10 9. Security Considerations . . . . . . . . . . . . . . . . . . . 11 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 11.1. Normative References . . . . . . . . . . . . . . . . . . 11 11.2. Informative References . . . . . . . . . . . . . . . . . 12 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 12 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12 1. Introduction Requirements for physical supply chain credentials are subject to frequent changes due to regulatory, logistic and market pressures. Preventing fraud and counterfeiting requires strong cryptographic assurance and binding to identities for people, organizations, vehicles and devices. New information regarding a credential subject needs to be conveyed by holders to verifier, after credential Steele Expires 11 December 2024 [Page 2] Internet-Draft Credential Type Assertions June 2024 issuance. This specification describes the role of credential types or schemas in supporting changing requirements and realtime information regarding digital credentials. When products in a physical supply chain are produced, it is common for certain required information to become available over time, sometimes as a result or tranformation processes which can be performed in different locations. When creating a digital twin or product passport for a marketable product, the issuer needs to balance the need to create identifiers as soon as possible, so that claims can be associated to them, with the need to wait for sufficient claims to be available to justify a credential issuance. A credential type or credential schema, is a set of mandatory and optional data elements, and is often based on a paper document such as a government form, or an evaluation or test performed by a trusted third party. When specifying digital representation of product information, it is common to encounter data elements which are "required when present", but which do not become present for some time after credential issuance. For example, when producing steel products, the chemical composition of steel is determined at the location and time when the steel is still in liquid form. However, mechanical properties, including length, weight and other dimensions as well as material properties such as tensile strength become available later as the raw product is further refined on its journey to the end customer. In particular, attributes such as protective coatings or finishing details which can impact weight and price may only be available shortly after the product is purchased. These attributes are critical to intermediate supply chain parties, such as logistics providers, who need to load and unload product from vessels or vehicles. Accurate information regarding dimensions and weight is critical to estimating fuel costs, and enabling advanced models of supply chain activity based on realtime digital twins. In some cases, flaws in a batch of products are discovered only after transport has begun, and downstream supply chain partners need access to the latest information regarding a product in order to comply with regulatory or business policies. Traditionally these challenges have been solved for with combinations of the following recommendations: Steele Expires 11 December 2024 [Page 3] Internet-Draft Credential Type Assertions June 2024 * Issue small credentials linked together with a common identifier * Enable the latest revocation, suspension or other status information to be retrieved in realtime * Use credential types or schemas to distinguish credentials with different required fields * Use a confirmation method to selectively disclosed attributes to a single credential Depending on the nature of the new information associated to a credential, these approaches can be difficult to implement, consume needless resources such as CPU, memory or network bandwidth, or reveal confidential supply chain metadata such as location information associated with a credential verification. This document proposes a simple profile for JOSE and COSE based credentials, enabling simple, secure and efficient realtime digital twins. 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. This document uses many terms common to the digital credential ecosystem and the OAUTH, SCITT, SPICE, JOSE and COSE working groups. Media Type: JWT and CWT credential formats support the use of media types to identify the claimset (cty) and the entire secured object (typ). This specification relates these media type extension points to other application specific extension points such as verifiable credential type (vct). Credential ID: CWT ID (CTI) and JWT ID (JTI) as defined in Section 3.1.7 of [RFC8392], are used to identify a digital credential represented as a token. Credential Type: Section 3.2.2.1.1 of [I-D.draft-ietf-oauth-sd-jwt-vc] and Section TBD of [I-D.draft-prorock-spice-cose-sd-cwt] describe a stringOrURI based identifier for distinguishing required or optional JWT or CWT claims. Steele Expires 11 December 2024 [Page 4] Internet-Draft Credential Type Assertions June 2024 Credential Schema: Verifiable Credentials Data Model v2.0 (https://w3c.github.io/vc-data-model/#data-schemas) describes solutions for validating instances of a JSON data model. This specification generalizes this approach to support validating instances of JWT or CWT claimsets similar to the approach taken in [I-D.draft-ietf-rats-eat], by relating the use of schema languages to the vct claim in JWT or CWT. Credential Assertions: [I-D.draft-demarco-oauth-status-attestations] describes a mechanism whereby a holder can retrieve updated credential state from an issuer, and present it to a verifier. Credential Status Lists: [I-D.draft-ietf-oauth-status-list] describes a mechanism whereby a verifier can retrieve updated credential states for a list of credentials from an issuer. 3. Overview This section describes how supply chain event driven architectures can be mapped to high level digital credential workflows to support digital twin ecosystems. +---------+ ... +-------------+ ... +-------------+ ... +--------------+ | Product | | Product | | Product | | Regulations | | Created | | Transformed | | Transfered | | Updated | +-----+---+ +------+------+ +-------+-----+ +-------+------+ | | | | v v v v +-----+------+ +-----+------+ +-------+-------+ +-------+------+ | Credential | | Credential | | Credential | | Credential | | Identifier | | Claims | | Confirmation | | Schema | | Created | | Added | | Updated | | Updated | +------------+ +------------+ +---------------+ +--------------+ Although the figure above suggests a linear ordering of events, complex supply chains also known as value networks often combine component products into higher order products over time with events arriving out of order or for products which are not yet known to the stakeholder. Regulations and therefor credential types requirements can change after or during a product custody transfers, making responsibility for compliance difficult. When requirements change, or in certain policy situations, additional information might be required from one or more supply chain actors, for example a border agent might request specific information from the original manufacturer and the logistics providers that are partnered to transport products. Steele Expires 11 December 2024 [Page 5] Internet-Draft Credential Type Assertions June 2024 Businesses account for these changes today through a combination of messages exchanged over email or through proprietary digital document management systems. As workflows for producing physical or digital products embrace transparency, traceability and security enabled by digital credentials, using the correct extension points at the the correct time becomes essential to reducing data duplication, and improving speed and security. The following sections cover guidance for when to use specific extension points which are available to profiles built on JOSE and COSE credential formats. 4. Entity Identifiers It is important to distinguish subject entity identifiers (sub or iss) for a product, organization or device, from credential identifiers such as cti or jti. Credential identifiers are used to name a set of secured claims about a subject. Consider that in the future, a supply chain party may wish to aggregate all credentials associated with a product identifier such as serial number, including multiple credentials from the same or different issuers. In these cases, the subject identifer can be considered as a primary key for the product, and the credential id can be considered as a foreign key for a table with columns representing the claims available for the token type (typ) and then finally the credential type (vct). For example: Steele Expires 11 December 2024 [Page 6] Internet-Draft Credential Type Assertions June 2024 Token Type Verifiable Credential Type +-----------------------+ +--------------------------------------+ | typ: foo-passport+jwt | | vct: https://.../foo-passport/v1.2.3 | | (jti, iss, sub) | | (product_name, serial_number) | +---------+-------------+ +--------------------+-----------------+ | | | | | Credential Instance | | +----------------------+ | | | jti: urn:uuid:123... | | +-------->| ... typ claims ... | | | ... vct claims ... +<------+ | sub: urn:uuid:456... | +-----------+----------+ | Internal System | +----------------------+ | | id: 0xfacade123... | | | sub: urn:uuid:456... +<-------+ +----------------------+ 5. Credential & Token Types Per [RFC8725] it is considered a best practice for both COSE and JOSE based digital credentials to distinguish types of tokens using the typ header parameter, which is used to indicate the media type of the associated token (including protected headers and signatures or ciphertexts). As described in Section 3.2.2.1.1 of [I-D.draft-ietf-oauth-sd-jwt-vc] and Section TBD of [I-D.draft-prorock-spice-cose-sd-cwt] the type of a JWT or CWT claimset can also be constrained using the vct CWT or JWT claim. It is recommended that both typ and vct be used when possible, and that application specific constraints which might be extended, updated or changed frequently be expressed through vct. The specific semantics of vct have been left intentionally open to support many use cases. A value of vct indicating https://issuer.gov.example/foo-passport/ v1.2.3 might be present in a credential of media type application/ foo-passport+jwt and application/foo-passport+cwt. In other words, it is recommended to not include media type parameters which using typ parameters. When versioning is necessary, it should be performed in the context of mandatory and optional claims and communicated throught the vct property. Although the example above includes a version identifier in the example URI, version information could be requested in other ways, including via HTTP headers. When HTTP is used to transport credential type information it is recommended to support negotiation of the credential type requirements through the use of the Accept Header. This enables human and machine readable requirements to be supported for each version of a digital Steele Expires 11 December 2024 [Page 7] Internet-Draft Credential Type Assertions June 2024 credential. For example: GET https://issuer.gov.example/foo-passport Accept: application/cddl or application/schema+json or text/html; charset=utf-8 5.1. Schemas Schemas are another name for verifiable credential type. Schemas constrain the expected mandatory and optional fields, and can recognize if an instance of a credential is valid according a data definition lanugage such as JSON Schema or CDDL. Schemas can be used to convey updated requirements associated with a credential, such as new fields which are mandatory in a new version. A new schema and associated status assertions can be conveyed using the mechanism described in [I-D.draft-demarco-oauth-status-attestations]. This enables a holder of a credential to disclose the original credential with confirmation, and any new information or requirements that have changed since the original credential was issued. For example: cbor-diag / cose-sign1 / 18([ / protected / << { / alg / 1 : -35 / ES384 / / typ / 16 : "application/sd+cwt" / kid / : "https://issuer.gov.example/key-42" } >>, / unprotected / { / disclosed claims / / sd_claims / TBD1 : <<[ [ / salt / h'399c641e...2aa18c1e', / claim / "region", / value / "ca" / California / ], [ / salt / h'82501bb4...6c655f32', / value / "4.1.7" ] ] / sd_kbt / TBD2 : << [ / 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 / TBD4 : -16 /SHA-256/ / sd_hash / TBD3 : h'c341bb...4a5f3f', / hash of sd_claims / / using sd_alg / >>, / signature / h'1237af2e...6789456' ] >> }, / payload / << / iss / 1 : "https://issuer.example", / sub / 2 : "https://device.example", / vct / TBD10 : "https://issuer.gov.example/foo-passport/v1.2.3", / exp / 2 : 1883000000, / iat / 2 : 1683000000, / cnf / 8 : { / cose key / 1 : { / alg: ES256 / 3: 35, / kty: EC2 / 1: 2, / crv: P-256 / -1: 1, / x / -2: h'768ed8...8626e', / y / -3: h'6a48cc...fd5d5' } }, / status / TBD8 : { / status assertion / TBD9 : { / credential hash alg / : "sha-256" } }, / sd_alg / TBD4 : -16, / SHA-256 / / redacted measurements / -65537 : [ { TBD6 : h'45dd...87af' / redacted_element / } ], "address": { "country" : "us", / United States / / redacted_keys / TBD5 : [ h'adb70604...03da225b', / redacted region / h'e04bdfc4...4d3d40bc' / redacted post_code / ] } >>, / signature / h'3337af2e...66959614' ]) Steele Expires 11 December 2024 [Page 8] Internet-Draft Credential Type Assertions June 2024 The associated status assertion could convey updated measurments that the issuer was not aware of at the time they issued the associated SD-CWT. For example: cbor-diag / cose-sign1 / 18([ / protected / << { / alg / 1 : -35 / ES384 / / typ / 16 : "application/status-assertion+cwt" / kid / : "https://issuer.gov.example/key-42" } >>, / unprotected / {}, / payload / << / iss / 1 : "https://issuer.example", / sub / 2 : "https://device.example", / vct / TBD10 : "https://issuer.gov.example/foo-passport/v2.0.0", / exp / 2 : 1883000000, / iat / 2 : 1683000000, / credential hash / TBD : h'227a33...45975', / credential hash alg / TBD : "sha-256", / cnf / 8 : { / Note this must match the original confirmation method / / cose key / 1 : { / alg: ES256 / 3: 35, / kty: EC2 / 1: 2, / crv: P-256 / -1: 1, / x / -2: h'768ed8...8626e', / y / -3: h'6a48cc...fd5d5' } }, / realtime updates for / -65548 : { / last location geohash / 282 : h'542aaa...66559ff' } >>, / signature / h'627aff...649596dd' ]) Note that in the example above the status assertion added realtime location information which was not present in the original credential type https://issuer.gov.example/foo-passport/v1.2.3, but which is mandatory in the new credential type https://issuer.gov.example/foo- passport/v2.0.0. Status assertions allow for new schemas and new credential type mandatory properties to be added over time, without issuing fresh credentials or updating existing schemas. However, there are cases where a new credential MUST be issued, and they are covered in the next section. 6. Confirmation Confirmation methods and their associated claims are used to ensure that only the authorized holder of a credential retaining the ability to use the associated confirmation method, can present the credential and receive facilitation benefits. Confirmation is critical to prevent credential theft and forgery, but it introduces complications to supply chain workflows that might have previously relied on a bearer token or bearer documents. When custody of a product is transfered for example in relation to a bill of lading and mate receipt for an ocean liner vessel, the controller of the product credential and the associated digital twin needs to be updated. Steele Expires 11 December 2024 [Page 9] Internet-Draft Credential Type Assertions June 2024 This can be accomplished through an issuance of a new credential, binding to the receiver of the product via their confirmation method, and a revocation of the previous credential to ensure the original holder is no longer able to present the proof of custody credential associated with the product shipment. There exist other registry updates which might be required to support product traceability such as notifications to shared databases or new entries in a certificate transparency system. After a new credential has been issued, the ability to provide status assertions transfers from the previous issuer, to the new issuer. It is essential that the validity period of associated credentials be aligned to the revocation and issuance process to ensure that the latest product information come from the current authoritative issuer for the product, and that the fresh status assertions be presentable by the current holder, and with the latest confirmation methods. 7. Status Status information regarding a credential can be expressed in several ways including those described in [I-D.draft-ietf-oauth-status-list] and [I-D.draft-demarco-oauth-status-attestations]. It is important to note that while status assertions are bound to the holder of a credential thought the associated confirmation method, status list information can be aggregated across several issuers over time, and issuer's might a previous issuer's authority to communicate status information for a newly issued credential. In these cases, credential may have 1 or more associated status lists, and a single associated status assertion. 8. Verifier Policies Supply chain actors for who receive credential presentations decide how to interpret the associated claims presented. In some cases, a verifier might reject presentations of a credential that did not include fresh status assertions for the latest version of a schema describing the required elements in a digital twin. For example, if a vessel leaves a port with bill of lading version 1, and regulations change in transit, a port authority might reject presentations of bill of lading version 1 unless they are companied with an assoicated status assertion covering the required data elements associated with bill of lading version 2. A verifier might also communicate with the holder out of band, and decide to accept the presentation of revoked or outdated credentials based on internal information of confidential evidence provided by the holder. It can be useful, especially when crafting machine readable and enforcable verifier policies, to refer Steele Expires 11 December 2024 [Page 10] Internet-Draft Credential Type Assertions June 2024 to token types typ and crendential types vct explicitly. It can also be useful to refer to specific supported protocol versions in a machine readable way, because certain credential features are only available to specific credential protocols. 9. Security Considerations TODO Security 10. IANA Considerations This document has no IANA actions. 11. References 11.1. Normative References [I-D.draft-ietf-oauth-sd-jwt-vc] Terbu, O., Fett, D., and B. Campbell, "SD-JWT-based Verifiable Credentials (SD-JWT VC)", Work in Progress, Internet-Draft, draft-ietf-oauth-sd-jwt-vc-03, 4 March 2024, . [I-D.draft-prorock-spice-cose-sd-cwt] Prorock, M. and O. Steele, "Selective Disclosure CWTs (SD- CWT)", Work in Progress, Internet-Draft, draft-prorock- spice-cose-sd-cwt-00, 21 March 2024, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, May 2018, . [RFC8725] Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best Current Practices", BCP 225, RFC 8725, DOI 10.17487/RFC8725, February 2020, . Steele Expires 11 December 2024 [Page 11] Internet-Draft Credential Type Assertions June 2024 11.2. Informative References [I-D.draft-demarco-oauth-status-attestations] De Marco, G., Steele, O., and F. Marino, "OAuth Status Attestations", Work in Progress, Internet-Draft, draft- demarco-oauth-status-attestations-01, 19 April 2024, . [I-D.draft-ietf-oauth-status-list] Looker, T., Bastian, P., and C. Bormann, "Token Status List", Work in Progress, Internet-Draft, draft-ietf-oauth- status-list-02, 3 March 2024, . [I-D.draft-ietf-rats-eat] Lundblade, L., Mandyam, G., O'Donoghue, J., and C. Wallace, "The Entity Attestation Token (EAT)", Work in Progress, Internet-Draft, draft-ietf-rats-eat-27, 26 May 2024, . Acknowledgments TODO acknowledge. Author's Address Orie Steele Transmute Email: orie@transmute.industries Steele Expires 11 December 2024 [Page 12]