This document specifies an API to enable [=user agents=] to mediate presentation and issuance of digital credentials such as a driver's license, government-issued identification card, and/or [=credential type examples|other types of digital credential=]. The API builds on [[[credential-management-1]]] as a means by which to request or issue a digital credential from a user agent or underlying platform.
This is an unofficial proposal.
This document defines an API enabling a website to request presentation and issuance of a [=digital credential=].
The API design is agnostic to both credential [=digital credential/presentation requests|presentation=] [=digital credential/exchange protocols=], credential [=digital credential/issuance request|issuance=] [=digital credential/issuance protocols|protocols=] and credential formats. However, to promote interoperability this document includes a [[[#protocol-registry]]].
The API is designed to support the following goals:
[=Digital credentials=] of many types can be presented and issued using this API. Examples of these types include:
The goal of the definitions in this section is to reuse or establish terminology that is common across a variety of digital credential formats and protocols. Discussions surrounding these definitions are active and the definitions are likely to change over the next several months.
This specification is currently focused on digital credentials pertaining to people.
The following items are within the scope of this specification:
The following items are out of scope:
partial dictionary CredentialRequestOptions {
DigitalCredentialRequestOptions digital;
};
The digital member allows for options to configure the request for a [=digital credential=].
dictionary DigitalCredentialRequestOptions {
sequence<DigitalCredentialGetRequest> requests;
};
The requests specify an [=digital credential/exchange protocol=] and [=digital credential/request data=], which the user agent MAY match against a holder's software, such as a digital wallet.
The {{DigitalCredentialGetRequest}} dictionary represents a [=digital credential/presentation request=]. It is used to specify an [=digital credential/exchange protocol=] and some [=digital credential/request data=], which the user agent MAY match against software used by a holder, such as a digital wallet.
dictionary DigitalCredentialGetRequest {
required DOMString protocol;
required object data;
};
The protocol member denotes the [=digital credential/exchange protocol=].
The {{DigitalCredentialCreateRequest/protocol}} member's value can be one of the well-defined protocol identifiers defined in [[[#protocol-registry]]] or a custom protocol identifier.
The data member is the [=digital credential/request data=] to be handled by the holder's credential provider, such as a digital identity wallet.
partial dictionary CredentialCreationOptions {
DigitalCredentialCreationOptions digital;
};
The digital member allows for options to configure the issuance of a [=digital credential=].
dictionary DigitalCredentialCreationOptions {
sequence<DigitalCredentialCreateRequest> requests;
};
The requests specify an [=digital credential/issuance protocol=] and [=digital credential/request data=], which the user agent MAY forward to a [=holder=].
The {{DigitalCredentialCreateRequest}} dictionary represents an [=digital credential/issuance request=]. It is used to specify an [=digital credential/issuance protocol=] and some [=digital credential/request data=], to communicate the issuance request between the issuer and the holder.
dictionary DigitalCredentialCreateRequest {
required DOMString protocol;
required object data;
};
The protocol member denotes the [=digital credential/issuance protocol=].
The {{DigitalCredentialCreateRequest/protocol}} member's value is be one of the well-defined keys defined in [[[#protocol-registry]]] or any other custom one.
The data member is the [=digital credential/request data=] to be handled by the holder's credential provider, such as a digital identity wallet.
The DigitalCredential interface represents a conceptual [=digital credential=].
[=User mediation=] is always {{CredentialMediationRequirement/"required"}}. [=Request a credential|Requesting a DigitalCredential credential=] does not support {{CredentialMediationRequirement/"conditional"}}, {{CredentialMediationRequirement/"optional"}}, or {{CredentialMediationRequirement/"silent"}} [=user mediation=]. If {{CredentialsContainer/get()}} is called with anything other than {{CredentialMediationRequirement/"required"}}, a {{TypeError}} will be thrown.
[Exposed=Window, SecureContext]
interface DigitalCredential : Credential {
readonly attribute DOMString protocol;
[SameObject] readonly attribute object data;
};
{{DigitalCredential}} instances are [=Credential/origin bound=].
The protocol member is the [=digital credential/exchange protocol=] that was used to request the [=digital credential=], or the [=digital credential/issuance protocol=] that was used to issue the [=digital credential=].
The data member is the credential's response data. It contains the subset of JSON-parseable object types.
When invoked, the [[\DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) internal method MUST:
When invoked, the [[\Store]](credential, sameOriginWithAncestors) MUST call the default implementation of {{Credential}}'s {{Credential/[[Store]](credential, sameOriginWithAncestors)}} internal method with the same arguments.
When invoked, the [[\Create]](origin, options, sameOriginWithAncestors) internal method, if the user agent doesn't support issuance, call the default implementation of {{Credential}}'s {{Credential/[[Create]](origin,options, sameOriginWithAncestors)}} internal method with the same arguments. Otherwise:
The {{DigitalCredential}} [=interface object=] has an internal slot named [[\type]] whose value is "digital".
The {{DigitalCredential}} [=interface object=] has an internal slot named [[\discovery]] whose value is "remote".
The Digital Credential API is a [=powerful feature=] that requires [=express permission=] from an end-user. This requirement is normatively enforced when calling {{CredentialsContainer}}'s {{CredentialsContainer/get()}} method.
This specification defines a [=policy-controlled feature=] identified by the string "digital-credentials-get". Its [=policy-controlled feature/default allowlist=] is [=default allowlist/'self'=].
Initiating the registration a protocol is done by filing an issue in our GitHub repository.
The following is the registry of [=digital credential/exchange protocols=] and [=digital credential/issuance protocols=] that are supported by this specification.
It is expected that this registry will be become a [=W3C registry=] in the future.
To be included in the registry, the [=digital credential/exchange protocol=]:
To be included as a presentation protocol in the registry (used with `navigator.credentials.get`), the [=digital credential/exchange protocol=]:
To add a new [=digital credential/exchange protocol=] to the registry, or to update an existing one:
[=User agents=] MUST support the following [=digital credential/exchange protocols=]:
| [=registry/identifier|Protocol identifier=] | [=registry/Type=] | [=registry/Description=] | [=registry/link|Specification=] |
|---|---|---|---|
| Coming soon... | |||
This section is a work in progress as this document evolves.
The documents listed below outline initial security considerations for Digital Credentials, both broadly and for presentation on the web. Their contents will be integrated into this document gradually.
Explain that while the API provides security at the browser API level, that security for the underlying credential issuance or presentation protocol is a separate concern and that developers need to understand that layer of the stack to get a total picture of the protections that are in place during any given transaction.
Explain that cross-device issuance or presentation uses a separate protocol that has its own security characteristics.
Explain that the API is designed to avoid the problem of quishing (phishing via QR Codes) and other QR Code and non-browser API-based attacks and to be aware of exposure of QR Codes during digital credential interactions.
Explain that the API does not provide data integrity on the digital credential requests or responses and that responsibility is up to the underlying protocol used for the request or response.
Explain that authentication (such as a PIN code to unlock) to a particular app, such as a digital wallet, that responds to an API request is crucial in high-risk use cases.
Explain what attacks are possible via XSS and CSRF, if any.
Explain that once a secure session is established at a website using credentials exchanged over this API, that the subsequent security is no longer a function of the credential used or this API and is up to the session management utilized on the website.
This section is a work in progress as this document evolves.
The Digital Credentials API integrates into a complex ecosystem with multiple technology layers and various participants (including but not limited to Verifiers, Holders and Issuers), each of which have to consider different aspects of user privacy. This specification does not attempt to exhaustively list all considerations for the different participants. We would like to refer these parties to a variety of other resources that explore the digital credentials threat model more holistically:
Instead, these considerations focus on the Digital Credentials API itself, and describe how user agents can satisfy their user agent duties in an implementation of the API, taking into account the relevant privacy properties of the ecosystem it interacts with.
The privacy considerations for digital credentials are not static. They will evolve over time as the ecosystem matures, and may be informed by the behavior of other actors in the ecosystem, improvements in other layers of the stack, new threats to user privacy, as well as changing societal norms and regulations.
It is expected that the various groups involved in the design and implementation of the Digital Credentials API actively monitor the evolving privacy landscape and participate in the corresponding evolution of the API.
The Digital Credentials API serves a variety of use cases with different grades of data disclosure and individual users with different preferences depending on the context that they are in. Notably, the privacy properties of a credential exchange mediated by this API could be mandated by the legal and regulatory environment of an individual user.
This means that some users may not want, or be allowed, to use the most privacy-preserving means of exchanging credential information. Nonetheless, user agents need to serve users with an experience that is private by default and protect them from harm.
Because of this spectrum of preferences and use cases, it may be difficult for a user agent to discern whether a user means to expose their personal information or is being tricked into doing so. It is thus the user agent's responsibility to ensure that every user understands what data they are sharing and who will participate in the exchange of information, before the exchange begins.
Explain how the API could be used to unnecessarily request digital credentials from individuals such as requesting a driver's license to log into a movie rating website and how the ecosystem can mitigate this risk.
Explain how the API could be used to request more data than necessary for a transaction and how the ecosystem can mitigate that over collection.
Explain how the API acquires an individual's consent to share a digital credential and how digital wallets can also provide further consent when sharing information.
Explain how verifiers might retain data and what the ecosystem does to mitigate excessive data retention policies.
Explain to what extent the API complies with known privacy regulations (e.g., consent) and what parts of those regulations are not possible to enforce via the API (e.g., retention).
Explain how selective disclosure and unlinkable disclosure help preserve privacy as well as their limitations in doing so.
Explain how some systems might "phone home", the impact on privacy that might have, and what the ecosystem provides to mitigate the risk.
Explain that the API does enable the transmission of personally identifiable information and that it does its best to ensure there is informed consent by the individual, but that the consent might be provided due to exhaustion or not understanding what PII is being transmitted and how to mitigate those concerns.
This section is a work in progress as this document evolves.