]> Microsoft

Maik.Riechert@microsoft.com

Microsoft

antdl@microsoft.com

Fraunhofer SIT

henk.birkholz@ietf.contact

Microsoft

Amaury.Chamayou@microsoft.com

Security DID X.509 This document defines the did:x509 decentralized identifier method, which enables a direct, resolvable binding between X.509 certificate chains and compact issuer identifiers (DID string). In particular, the did:x509 identifier format in this documents comes with a CWT Claims definition. In general, this identifier is a compact and interoperable mechanism for certificate-based identification by combining a certificate fingerprint with optional policies for subject names, subject alternative names, extended key usage, and issuer information. It is especially useful for policy evaluation and reference in transparency services and similar systems requiring cryptographic binding to certificate material. This Informational document is published as an Independent Submission to improve interoperability with Microsoft's architecture. It is not a standard nor a product of the IETF. Discussion Venues Source for this draft and an issue tracker can be found at .

Introduction This document aims to define an interoperable and flexible decentralized identifier () format for COSE messages that transport or refer to X.509 certificates using . The did:x509 identifier format implements a direct, resolvable binding between a certificate chain and a compact issuer string. It can be used in a COSE Header CWT Claims map as defined in . Including a certificate chain directly in configuration or in policy is often impractical. This is due to its size, and to the frequency at which some elements, particularly the leaf, are refreshed. Relying on a partial certificate chain (e.g., a root certificate and some intermediary certificates) is similarly unwieldy. While stable, the level of granularity afforded by a partial certificate chain may not be sufficient to distinguish several identities that are not equivalent for the purpose of policy. Combining authority pinning with attribute assertions is a precise and stable way of capturing identities as a constrained set of certificates. Their representation as compact and durable identifier strings enables the formulation of readable policy (e.g. "request.issuer == 'did:x509...'"), for example in the context of transparency ledger registration.

Conventions and Definitions 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 when, and only when, they appear in all capitals, as shown here. In this document, CDDL (, ) is used to describe the data formats, and ABNF (defined in ) to describe identifiers. The reader is assumed to be familiar with the vocabulary and concepts defined in . Rego is a descriptive query language used to define policies in a precise and unambiguous way. This document uses Rego () to define the parsing and validation logic for did:x509 identifiers. The Rego code snippets provided in this document can be evaluated using any Rego v1 runtime, but there is no expectation that implementations use the Rego language. Per , line breaks may be present in the figures of this document to stay within the line-length limits of this document's format.

Identifier Syntax The did:x509 ABNF definition defined below uses the syntax defined in and the corresponding definitions for ALPHA and DIGIT. contains the definitions for idchar and pct-encoded in Section 3.1.

ABNF Definition of Core did-x509 Syntax

Implementations of this specification MUST indicate a version value of 0. ca-fingerprint-alg is one of sha256, sha384, or sha512. ca-fingerprint is chain[i].fingerprint[ca-fingerprint-alg] with i > 0, that is, either an intermediate or root CA certificate. predicate-name is a predicate name and predicate-value is a predicate-specific value. :: is used to separate multiple predicates from each other. The following sections define the predicates and their predicate-specific syntax. Validation of predicates is defined using policies written in the Rego language (), rather than pseudo-code. This is to avoid ambiguity and to make it possible for a reader to evaluate the logic automatically. The inputs to the resolution process are the DID string itself and the x509chain DID resolution option, which carries a comma-separated base64url-encoded X.509 certificate chain. To evaluate the reference Rego code shown below, the DID and certificate chain have to be passed to a Rego runtime as a JSON document: {"did": "<DID>", "chain": <CertificateChain>}, where did is the DID string and chain is the parsed representation of the certificate chain derived from the x509chain resolution option. Core Rego policy:

Core Rego Validation Rule

The overall Rego policy is assembled by concatenating the core Rego policy with the Rego policy fragments in the following sections, each one defining a validate_predicate function.

Percent-encoding Some of the predicates that are defined in subsequent sections require values to be percent-encoded. Percent-encoding is specified in . All characters that are not in the allowed set defined below must be percent-encoded:

ABNF Definition of Characters That Do Not Need to Be Percent-Encoded

Note that most libraries implement percent-encoding in the context of URLs and do NOT encode ~ (%7E).

"subject" predicate

ABNF Definition of Subject Policy

<key>:<value> are the subject name fields in chain[0].subject in any order. Key repetitions are not allowed. Values must be percent-encoded. Example: did:x509:0:sha256:WE..jk::subject:C:US:ST:Texas:L:Austin:O:Example Rego policy:

Rego Function Validating Subject Policy = 1 object.subset(input.chain[0].subject, subject) == true } ]]>

"san" predicate

ABNF Definition of SAN Policy

san-type is the SAN type and must be one of email, dns, or uri. Note that dn is not supported. san-value is the SAN value, percent-encoded. The pair [<san_type>, <san_value>] is one of the items in chain[0].extensions.san. Example: did:x509:0:sha256:WE..jk::san:email:bob%40example.com Rego policy:

Rego Function Validating SAN Policy

"eku" predicate

ABNF Definition of EKU Policy

eku is one of the OIDs within chain[0].extensions.eku. Example: did:x509:0:sha256:WE..jk::eku:1.3.6.1.4.1.311.10.3.13 Rego policy:

Rego Function Validating EKU Policy

"fulcio-issuer" predicate

ABNF Definition of Fulcio-Issuer Policy

fulcio-issuer is chain[0].extensions.fulcio_issuer, without leading https://, percent-encoded. Example: did:x509:0:sha256:WE..jk::fulcio-issuer:accounts.google.com::san:email:bob%40example.com Example 2: did:x509:0:sha256:WE..jk::fulcio-issuer:issuer.example.com::san:uri:https%3A%2F%2Fexample.com%2Focto-org%2Focto-automation%2Fworkflows%2Foidc.yml%40refs%2Fheads%2Fmain Rego policy:

Rego Function Validating Fulcio-Issuer Policy

DID resolution options This DID method introduces a new DID resolution option called x509chain: Name: x509chain Value type: string The value is constructed as follows:

1. Encode each certificate C that is part of the chain as the string b64url(DER(C)).
2. Concatenate the resulting strings in order, separated by comma ",".

Example DID Document This illustrates what a typical DID document (), describing the DID subject and the methods it can use to authenticate itself, can look like once resolved:

JSON Controller Document Example

CDDL for a JSON Data Model for X.509 Certificate Chains

CDDL Definition of did:x509 JSON Data Model tstr } ; base64url-encoded data, see RFC 4648, Section 5 base64url = tstr ; ASN.1 Object Identifier ; Dotted string, for example "1.2.3" OID = tstr ; X.509 Subject Alternative Name ; Strings are converted to UTF-8 SAN = rfc822Name / DNSName / URI / DirectoryName rfc822Name = ["email", tstr] ; Example: ["email", "user@example.com"] DNSName = ["dns", tstr] ; Example: ["dns", "example.com"] URI = ["uri", tstr] ; Example: ["uri", "https://example.com"] DirectoryName = ["dn", Name] ; Example: ["dn", {CN: "Example"}] ]]>

Security Consideration

Identifier Ambiguity This DID method maps characteristics of X.509 certificate chains to identifiers. It allows a single identifier to map to multiple certificate chains, giving the identifier stability across the expiry of individual chains. However, if the policies used in the identifier are chosen too loosely, the identifier may match too wide a set of certificate chains. This may have security implications as it may authorize an identity for actions it was not meant to be authorized for. To mitigate this issue, the certificate authority should publish their expected usage of certificate fields and indicate which ones constitute a unique identity, versus any additional fields that may be of an informational nature. This will help users create an appropriate did:x509 as well as consumers of signed content to decide whether it is appropriate to trust a given did:x509.

X.509 Trust Stores Typically, a verifier trusts an X.509 certificate by applying chain validation defined in using a set of certificate authority (CA) certificates as trust store, together with additional application-specific policies. This DID method does not require an X.509 trust anchor store but rather relies on verifiers either trusting an individual DID directly or using third-party endorsements for a given DID, like , to establish trust. By layering this DID method on top of X.509, verifiers are free to use traditional chain validation (for example, verifiers unaware of DID), or rely on DID as an ecosystem to establish trust.

Use of Identifier Contents While it is acceptable to use a did:x509 identifier as an opaque handle when it has been endorsed through an external trust mechanism, such as a verifiable credential or a trusted registry, implementers MUST NOT parse or interpret individual components of the identifier string for authorization decisions unless the identifier has been resolved against a verified certificate chain. Specifically, extracting and relying upon subject names, organizational information, or other embedded values directly from the identifier string, without performing full resolution and chain validation, is insecure. An attacker could craft a syntactically valid did:x509 identifier containing arbitrary values that do not correspond to any legitimate certificate chain. Only after successful resolution, which includes verification of the CA fingerprint against the provided chain and validation of all policy predicates, can the identifier be considered authentic. Systems that bypass this resolution process and instead parse identifier components directly are vulnerable to impersonation and privilege escalation attacks.

IANA Considerations RFC Editor: Please replace "RFCthis" with the RFC number assigned to this document. RFC Editor: Some considerations

References Normative References A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK] JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. This document proposes a notational convention to express Concise Binary Object Representation (CBOR) data structures (RFC 7049). Its main goal is to provide an easy and unambiguous way to express structures for protocol messages and data formats that use CBOR or JSON. The Concise Data Definition Language (CDDL), standardized in RFC 8610, provides "control operators" as its main language extension point. The present document defines a number of control operators that were not yet ready at the time RFC 8610 was completed:.plus,.cat, and.det for the construction of constants;.abnf/.abnfb for including ABNF (RFC 5234 and RFC 7405) in CDDL specifications; and.feature for indicating the use of a non-basic feature in an instance. The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. These design goals make it different from earlier binary serializations such as ASN.1 and MessagePack. This document obsoletes RFC 7049, providing editorial improvements, new details, and errata fixes while keeping full compatibility with the interchange format of RFC 7049. It does not create a new version of the format. Many protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA). To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry. This is the third edition of this document; it obsoletes RFC 5226. Internet technical specifications often need to define a formal syntax. Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications. The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power. The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges. This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications. [STANDARDS-TRACK] n.d. This memo profiles the X.509 v3 certificate and X.509 v2 certificate revocation list (CRL) for use in the Internet. An overview of this approach and model is provided as an introduction. The X.509 v3 certificate format is described in detail, with additional information regarding the format and semantics of Internet name forms. Standard certificate extensions are described and two Internet-specific extensions are defined. A set of required certificate extensions is specified. The X.509 v2 CRL format is described in detail along with standard and Internet-specific extensions. An algorithm for X.509 certification path validation is described. An ASN.1 module and examples are provided in the appendices. [STANDARDS-TRACK] n.d. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References Fraunhofer SIT Microsoft Research Microsoft Research ARM Traceability in supply chains is a growing security concern. While verifiable data structures have addressed specific issues, such as equivocation over digital certificates, they lack a universal architecture for all supply chains. This document defines such an architecture for single-issuer signed statement transparency. It ensures extensibility, interoperability between different transparency services, and compliance with various auditing procedures and regulatory requirements. n.d. This document defines two strategies for handling long lines in width-bounded text content. One strategy, called the "single backslash" strategy, is based on the historical use of a single backslash ('\') character to indicate where line-folding has occurred, with the continuation occurring with the first character that is not a space character (' ') on the next line. The second strategy, called the "double backslash" strategy, extends the first strategy by adding a second backslash character to identify where the continuation begins and is thereby able to handle cases not supported by the first strategy. Both strategies use a self-describing header enabling automated reconstitution of the original content. The CBOR Object Signing and Encryption (COSE) message structure uses references to keys in general. For some algorithms, additional properties are defined that carry parameters relating to keys as needed. The COSE Key structure is used for transporting keys outside of COSE messages. This document extends the way that keys can be identified and transported by providing attributes that refer to or contain X.509 certificates. This document describes how to include CBOR Web Token (CWT) claims in the header parameters of any CBOR Object Signing and Encryption (COSE) structure. This functionality helps to facilitate applications that wish to make use of CWT claims in encrypted COSE structures and/or COSE structures featuring detached signatures, while having some of those claims be available before decryption and/or without inspecting the detached payload. Another use case is using CWT claims with payloads that are not CWT Claims Sets, including payloads that are not CBOR at all. n.d.

Acknowledgments The authors would like to thank list for their reviews and suggestions.