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 documents listed below outline various privacy considerations for Digital Credentials, both broadly and for presentation on the web. Their contents will be integrated into this document gradually.
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.