Digital Credentials

This document specifies an API to enable [=user agents=] to mediate access to, and presentation 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 a digital credential from a user agent or underlying platform.

This is an unofficial proposal.

Introduction

TBW

There are many types of digital credential that can be conveyed using this API. Examples of these types include:

a driver's license or identity card issued by a government institution
TBW: other credential types

Model

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.

Digital credential: A cryptographically signed digital document containing one or more [=claims=] made by an [=issuer=] about one or more [=subjects=].
This specification is currently focused on digital credentials pertaining to people.
query: A format that [=verifier=] software or a [=user agent=] uses, via an [=digital credential/exchange protocol=], to request a [=digital credential=] from a [=holder=].
Presentation response: A format that a [=holder|holder's=] software, such as a digital wallet, uses, via an [=digital credential/exchange protocol=], to respond to a [=digital credential/query=] by a [=verifier=].
Exchange protocol: A protocol used for exchanging a [=digital credential=] between a [=holder=] and a [=verifier=]. See section [[[#protocol-registry]]].

Scope

The following items are within the scope of this specification:

Requesting a [=digital credential=], including mechanisms for secure presentation.

The following items are out of scope:

Issuance process for establishing a [=digital credential=].
UI/UX considerations, with the exception of privacy considerations, which are addressed to ensure the protection of user data during the request process.

Extensions to the `Navigator` interface

    partial interface Navigator {
      [SecureContext, SameObject] readonly attribute CredentialsContainer identity;
    };

The `identity` attribute

The identity attribute provides access to the the underlying {{CredentialsContainer}} for managing [=digital credentials=].

Extensions to Credential Management API

Extensions to `CredentialRequestOptions` dictionary

    partial dictionary CredentialRequestOptions {
      DigitalCredentialRequestOptions digital;
    };

The `digital` member

The digital member allows for options to configure the request for a [=digital credential=].

The `DigitalCredentialRequestOptions` dictionary

    dictionary DigitalCredentialRequestOptions {
      sequence<IdentityRequestProvider> providers;
    };

The `providers` member

The providers specify an [=digital credential/exchange protocol=] and [=digital credential/query=], which the user agent MAY match against a holder's software, such as a digital wallet.

The `IdentityRequestProvider` dictionary

The {{IdentityRequestProvider}} dictionary is used to specify an [=digital credential/exchange protocol=] and a [=digital credential/query=], which the user agent MAY match against software used by a holder, such as a digital wallet.

    dictionary IdentityRequestProvider {
      required DOMString protocol;
      required object request;
    };

The `protocol` member

The protocol member denotes the [=digital credential/exchange protocol=] when requesting an identify credential.

The {{IdentityRequestProvider/protocol}} member's value is be one of the well-defined keys defined in [[[#protocol-registry]]] or any other custom one.

The `request` member

The request member is the request to be handled by the holder's software, such as a digital wallet.

The `DigitalCredential` interface

The DigitalCredential interface represents a conceptual [=digital credential=].

    [Exposed=Window, SecureContext]
    interface DigitalCredential : Credential {
      readonly attribute DOMString protocol;
      readonly attribute any data;
    };

The `protocol` member

The protocol member is the [=digital credential/exchange protocol=] that was used to request the [=digital credential=].

The `data` member

The data member is the credential's response data.

Registry of protocols for requesting digital credential

The following is the registry of [=digital credential/exchange protocols=] that are supported by this specification.

It is expected that this registry will be become a [=W3C registry=] in the future.

Inclusion criteria

To be included in the registry...

[=User agents=] MUST support the following [=digital credential/exchange protocols=]:

Table of officially registered [=digital credential/exchange protocols=].
Protocol identifier	Description	Specification
Coming soon...