The did:x509 Decentralized Identifier (DID) Method

1.1. Interoperability Between X.509 and DIDs

The did:x509 method lets existing X.509 solutions and DID-based systems interoperate without changes to either:¶

• The X.509 side is unchanged. Certification authorities, public or private, issue ordinary certificates, signers keep their keys, and did:x509 identifiers are created locally from certificate chains (Section 6.1).¶

• The evidence travels with the message. Resolution needs only the DID and the certificate chain that signed messages already carry, for example in the x5chain ([RFC9360]) or x5c (Section 4.1.6 of [RFC7515]) header parameters, so any resolver that accepts the chain derives the same DID Document, without a registry lookup (Section 7).¶

• X.509 keys work in DID-based protocols. The DID Document exposes the leaf certificate's public key as a verification method, with verification relationships that follow its key usage (Section 4), so these protocols need not handle certificates.¶

• X.509 trust is expressed as a DID. The certification authority (CA) fingerprint and the predicates let DID-based policies capture an X.509 identity rather than individual certificates.¶

A single signed message can therefore serve both kinds of relying party (Figure 1). An X.509-only verifier validates the certificate chain with its trust store and ignores the issuer, while a DID-aware verifier resolves the issuer against the same chain and applies its DID-based policy. Neither needs the other's infrastructure.¶

+------+  issues   +--------+
|  CA  |---------->| Signer |
+------+           +--------+
                        |
                        | signed message with the certificate
                        | chain and a did:x509 issuer
                        |
           +------------+------------+
           |                         |
           v                         v
+---------------------+   +----------------------+
| X.509-only verifier |   | DID-aware verifier   |
| validates the chain |   | resolves the issuer  |
| with its trust      |   | against the chain,   |
| store               |   | applies DID policy   |
+---------------------+   +----------------------+

1.2. Relationship to the did:x509 Method Specification

The did:x509 method is registered in the W3C DID Methods registry ([DID-METHODS]), whose entry points to the did:x509 Method Specification maintained in the microsoft/did-x509 repository ([DID-X509-SPEC]). This document is aligned with [DID-X509-SPEC], and much of its text, including the ABNF, the Rego policy, and the DID resolution procedure, is adapted from it; the authors of [DID-X509-SPEC] are also authors of this document. The authors intend to keep this document and [DID-X509-SPEC] synchronized as both evolve.¶

Microsoft has implemented did:x509 in a range of libraries and systems. Its internal and external signing services, such as Artifact Signing, derive did:x509 identifiers from their existing issuing CAs and extended key usages (EKUs), and use them as the issuer of the COSE envelopes they produce, which include Supply Chain Integrity, Transparency, and Trust (SCITT) Signed Statements [RFC9943]. Relying parties' policies pin the accepted did:x509 issuers, together with subjects, to decide which Transparent Statements to accept, and for which purpose.¶

1.3. 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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

In this document, the Concise Data Definition Language (CDDL) [RFC8610] is used to describe the data formats, and ABNF ([RFC5234], [RFC7405]) to describe identifiers.¶

This document uses the terms "DID", "DID URL", "DID Document", "DID subject", "DID resolution", "verification method", and "controller" as defined in [DID], and the terms "certification path" and "trust anchor" as defined in [RFC5280]. A "relying party" is an entity that relies on a resolved did:x509 identifier, for example, to authorize the signer of a message.¶

Rego ([REGO]) is a declarative policy language. This document uses Rego, rather than pseudo-code, to define DID syntax validation and predicate validation for did:x509 identifiers, so that the logic is precise and unambiguous and can be evaluated automatically. 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 [RFC8792], line breaks may be present in the figures of this document to stay within the line-length limits of this document's format.¶

Examples in this document abbreviate long base64url values, such as CA fingerprints, to their first and last two characters with two dots in between (for example, WE..jk) to avoid visual clutter otherwise caused by line size restrictions. Abbreviated values are not syntactically valid.¶

2.1. Percent-Encoding

Some of the predicates that are defined in subsequent sections require values to be percent-encoded. Percent-encoding is specified in Section 2.1 of [RFC3986]. Characters are encoded as UTF-8 ([RFC3629]) before percent-encoding. All characters that are not in the allowed set defined below MUST be percent-encoded:¶

allowed = ALPHA / DIGIT / "-" / "." / "_"

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

Resolution fails if a percent-decoded value is not valid UTF-8.¶

2.2. "subject" Predicate

predicate-name  = %s"subject"
predicate-value = key ":" value *(":" key ":" value)
key             = label / oid
value           = 1*idchar
label           = %s"CN" / %s"L" / %s"ST" / %s"O" / %s"OU" /
                  %s"C" / %s"STREET"
oid             = 1*DIGIT *("." 1*DIGIT)

<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:¶

validate_predicate(name, value) := true if {
    name == "subject"
    items := split(value, ":")
    count(items) % 2 == 0
    keys := {k | some i; i % 2 == 0; k := items[i]}
    count(keys) == count(items) / 2
    subject := {k: v |
        some i
        i % 2 == 0
        k := items[i]
        v := urlquery.decode(items[i+1])
    }
    count(subject) >= 1
    object.subset(input.chain[0].subject, subject) == true
}

2.3. "san" Predicate

predicate-name  = %s"san"
predicate-value = san-type ":" san-value
san-type        = %s"email" / %s"dns" / %s"uri"
san-value       = 1*idchar

san-type is the subject alternative name (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:¶

validate_predicate(name, value) := true if {
    name == "san"
    [san_type, san_value_encoded] := split(value, ":")
    san_value := urlquery.decode(san_value_encoded)
    [san_type, san_value] == input.chain[0].extensions.san[_]
}

2.4. "eku" Predicate

predicate-name  = %s"eku"
predicate-value = eku
eku             = oid
oid             = 1*DIGIT *("." 1*DIGIT)

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:¶

validate_predicate(name, value) := true if {
    name == "eku"
    value == input.chain[0].extensions.eku[_]
}

2.5. "fulcio-issuer" Predicate

predicate-name   = %s"fulcio-issuer"
predicate-value  = fulcio-issuer
fulcio-issuer    = 1*idchar

fulcio-issuer is chain[0].extensions.fulcio_issuer, without leading https://, percent-encoded.¶

The fulcio_issuer extension MUST be present on chain[0] when this predicate is used; resolution fails if it is absent. The extension MUST NOT be marked critical.¶

Example:¶

did:x509:0:sha256:WE..jk::fulcio-issuer:accounts.example.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:¶

=============== NOTE: '\' line wrapping per RFC 8792 ================

validate_predicate(name, value) := true if {
    name == "fulcio-issuer"
    suffix := urlquery.decode(value)
    concat("", ["https://", suffix]) == input.chain[0].extensions.\
                                                        fulcio_issuer
}

2.6. 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)), where DER(C) is the DER encoding ([X.690]) of C and b64url is base64url encoding (Section 5 of [RFC4648]).¶

2. Concatenate the resulting strings in order, separated by comma ",".¶

The chain is ordered leaf first and root or trust anchor last:¶

x509chain = b64url(DER(leaf)) ","
            b64url(DER(intermediate)) ","
            b64url(DER(root))

Each comma-separated item is the DER encoding of one complete X.509 certificate, not a public key, fingerprint, or DER encoding of the whole chain.¶

6.1. Create

Creating a did:x509 identifier is a local operation. The DID MUST be constructed according to the syntax rules in this specification. No registration action is required, and no registry authorization is checked.¶

When constructing a did:x509 identifier, determine what constitutes a logical identity within a given certification authority. Concretely, determine which certificate fields the authority uses to uniquely represent an identity. After that, choose one or more matching predicates that express such an identity as faithfully as possible.¶

As an example, a certification authority may use email addresses as a way to separate identities and use the SAN extension to store the email address. In that case, the did:x509 identifier should be constructed using the san predicate, for example, did:x509:0:sha256:<ca-fingerprint>::san:email:bob%40example.com.¶

In other cases, an authority may not include email addresses at all and instead rely on a specific set of subject fields to separate identities. In that case, the subject predicate should be used.¶

In yet other cases, authorities may assign unique numbers or other types of stable identifiers to logical identities. Typically, this is done to have a stable reference even if a person changes their name or email address.¶

In all cases, the goal is to craft a did:x509 identifier that is stable yet not too loose in its predicates. An example of a loose did:x509 identifier may be to use the subject predicate and only include the O field without location fields like country (C) or state/locality (ST).¶

Whether a did:x509 identifier should pin to an intermediate CA instead of a root CA depends on whether there is value in distinguishing between them. Pinning to an intermediate CA typically means that the lifetime of the did:x509 identifier will be shorter, since intermediate CA certificates usually have a shorter validity period than root CA certificates.¶

6.2. Read / Resolve

The Read operation is DID resolution. The operation takes as input a DID to resolve, together with the x509chain DID resolution option (Section 2.6).¶

The DID resolver uses the DID, the certificate chain, and the process in Section 7 to generate a DID Document. No caller authorization is required; authenticity is checked by certificate chain validation, CA fingerprint matching, and predicate validation.¶

6.3. Update

This DID method does not support updating the DID Document, assuming a fixed certificate chain. There is no update authorization operation.¶

However, the public key included in the DID Document varies depending on the certificate chain that was used as input to the DID resolution process. Typically, multiple chains, in particular leaf certificates, are valid for a given did:x509 identifier.¶

6.4. Deactivate

This DID method does not support deactivating the DID. There is no deactivation authorization operation.¶

However, if the certification authority revokes all certificates for the matching DID, or they expire, and does not issue new certificates matching the same DID, then this can be considered equivalent to deactivation of the DID. There is no technical guarantee in this case and the certification authority can revert its decision.¶

8.1. Microsoft

The implementations below are the ones that Microsoft publishes as open source. Microsoft also has internal implementations, which are not listed here. For all of them, the organization is Microsoft and the contact is the authors of this document.¶

8.2. Nuts Foundation

The Nuts Foundation maintains open-source software for exchanging healthcare data in the Netherlands. For all of the implementations below, both the organization and the contact are the Nuts Foundation (https://nuts.nl).¶

9.1. 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 predicates 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 certification authority should publish its 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 identifier as well as consumers of signed content to decide whether it is appropriate to trust a given did:x509 identifier.¶

9.2. X.509 Trust Stores

Resolution validates the supplied certificate chain with the last certificate in x509chain as the path-validation trust anchor. This checks the chain and DID predicates, but does not decide whether the CA or DID is acceptable to a relying party.¶

Relying parties make that trust decision by policy, for example through a CA trust store, an allowlist of DIDs or CA fingerprints, or other application-specific rules.¶

9.3. Use of Identifier Contents

While it is acceptable to use a did:x509 identifier as an opaque handle to implement a relying-party policy, 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 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.¶

12.1. Normative References

[CID]

"Controlled Identifiers v1.0", 15 May 2025, <https://www.w3.org/TR/cid-1.0/>.

[DID]

Sporny, M., Guy, A., Sabadello, M., and D. Reed, "Decentralized Identifiers (DIDs) v1.0", W3C REC-did-core-20220719, 19 July 2022, <https://www.w3.org/TR/2022/REC-did-core-20220719/>.

[FIPS180-4]

National Institute of Standards and Technology, "Secure Hash Standard (SHS)", FIPS 180-4, August 2015, <https://csrc.nist.gov/publications/detail/fips/180/4/final>.

[JSON-LD]

Kellogg, G., Champin, P.-A., and D. Longley, "JSON-LD 1.1: A JSON-based Serialization for Linked Data", W3C REC-json-ld11-20200716, 16 July 2020, <https://www.w3.org/TR/2020/REC-json-ld11-20200716/>.

[REGO]

Open Policy Agent, "Policy Language", n.d., <https://www.openpolicyagent.org/docs/policy-language>.

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC3629]

Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 2003, <https://www.rfc-editor.org/rfc/rfc3629>.

[RFC3986]

Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, <https://www.rfc-editor.org/rfc/rfc3986>.

[RFC4514]

Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names", RFC 4514, DOI 10.17487/RFC4514, June 2006, <https://www.rfc-editor.org/rfc/rfc4514>.

[RFC4648]

Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, <https://www.rfc-editor.org/rfc/rfc4648>.

[RFC5234]

Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008, <https://www.rfc-editor.org/rfc/rfc5234>.

[RFC5280]

Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R., and W. Polk, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, <https://www.rfc-editor.org/rfc/rfc5280>.

[RFC7405]

Kyzivat, P., "Case-Sensitive String Support in ABNF", RFC 7405, DOI 10.17487/RFC7405, December 2014, <https://www.rfc-editor.org/rfc/rfc7405>.

[RFC7517]

Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/RFC7517, May 2015, <https://www.rfc-editor.org/rfc/rfc7517>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

[RFC8610]

Birkholz, H., Vigano, C., and C. Bormann, "Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, June 2019, <https://www.rfc-editor.org/rfc/rfc8610>.

[STD90]

Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, <https://www.rfc-editor.org/rfc/rfc8259>.

[X.690]

ITU-T, "Information technology - ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER)", ITU-T Recommendation X.690, February 2021, <https://www.itu.int/rec/T-REC-X.690>.

12.2. Informative References

[DID-METHODS]

"DID Methods", 26 September 2026, <https://www.w3.org/TR/2026/NOTE-did-extensions-methods-20260926/>.

[DID-X509-SPEC]

Riechert, M. and A. Delignat-Lavaud, "did:x509 Method Specification", 29 September 2026, <https://github.com/microsoft/did-x509/blob/d065856f18d7e1d426bf6b8e1f169132b7ed1891/specification.md>.

[FULCIO]

Sigstore, "Fulcio", n.d., <https://github.com/sigstore/fulcio>.

[GITSIGN-TIMESTAMP]

Sigstore, "Gitsign: Timestamping", 29 July 2026, <https://github.com/sigstore/gitsign/blob/44f5e17fac6944fdde71c94d2e77ab075c9dca9f/docs/timestamp.md#L102-L107>.

[RFC6960]

Santesson, S., Myers, M., Ankney, R., Malpani, A., Galperin, S., and C. Adams, "X.509 Internet Public Key Infrastructure Online Certificate Status Protocol - OCSP", RFC 6960, DOI 10.17487/RFC6960, June 2013, <https://www.rfc-editor.org/rfc/rfc6960>.

[RFC7515]

Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2015, <https://www.rfc-editor.org/rfc/rfc7515>.

[RFC7519]

Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, <https://www.rfc-editor.org/rfc/rfc7519>.

[RFC7942]

Sheffer, Y. and A. Farrel, "Improving Awareness of Running Code: The Implementation Status Section", BCP 205, RFC 7942, DOI 10.17487/RFC7942, July 2016, <https://www.rfc-editor.org/rfc/rfc7942>.

[RFC8392]

Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, May 2018, <https://www.rfc-editor.org/rfc/rfc8392>.

[RFC8792]

Watsen, K., Auerswald, E., Farrel, A., and Q. Wu, "Handling Long Lines in Content of Internet-Drafts and RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020, <https://www.rfc-editor.org/rfc/rfc8792>.

[RFC9360]

Schaad, J., "CBOR Object Signing and Encryption (COSE): Header Parameters for Carrying and Referencing X.509 Certificates", RFC 9360, DOI 10.17487/RFC9360, February 2023, <https://www.rfc-editor.org/rfc/rfc9360>.

[RFC9597]

Looker, T. and M.B. Jones, "CBOR Web Token (CWT) Claims in COSE Headers", RFC 9597, DOI 10.17487/RFC9597, June 2024, <https://www.rfc-editor.org/rfc/rfc9597>.

[RFC9943]

Birkholz, H., Delignat-Lavaud, A., Fournet, C., Deshpande, Y., and S. Lasker, "An Architecture for Trustworthy and Transparent Digital Supply Chains", RFC 9943, DOI 10.17487/RFC9943, June 2026, <https://www.rfc-editor.org/rfc/rfc9943>.

[RWOT11]

Stoecker, C. and C. Wirrig, "Analysis of hybrid wallet solutions - Implementation options for combining x509 certificates with DIDs and VCs", 20 July 2022, <https://github.com/WebOfTrustInfo/rwot11-the-hague/blob/master/advance-readings/hybrid_wallet_solutions_x509_DIDs_VCs.md>.

[TEST-VECTORS]

Microsoft, "did:x509 Test Vectors", 29 September 2026, <https://github.com/microsoft/did-x509/blob/d065856f18d7e1d426bf6b8e1f169132b7ed1891/test-vectors.json>.

[VC]

"Verifiable Credentials Data Model v1.1", 3 March 2022, <https://www.w3.org/TR/2022/REC-vc-data-model-20220303/>.