Digital Credentials

Draft Community Group Report

Latest published version:
https://www.w3.org/digital-identity/
Latest editor's draft:
https://wicg.github.io/digital-credentials/
Editors:
Marcos Caceres (Apple Inc.)
Sam Goto (Google Inc.)
Feedback:
GitHub WICG/digital-credentials (pull requests, new issue, open issues)

Copyright © 2024 the Contributors to the Digital Credentials Specification, published by the Web Platform Incubator Community Group under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.

Abstract

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 other types of digital credential. The API builds on Credential Management Level 1 as a means by which to request a digital credential from a user agent or underlying platform.

Status of This Document

This is a preview

Do not attempt to implement this version of the specification. Do not reference this version as authoritative in any way. Instead, see https://wicg.github.io/digital-credentials/ for the Editor's draft.

This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

This is an unofficial proposal.

GitHub Issues are preferred for discussion of this specification.

1. Introduction

TBW

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

2. Model

Digital credential

Is a verifiable credential about a person.

Identity credential provider
An application or service that provides a user interface for selecting and/or querying a digital credential, such as a digital wallet that manages various identity documents and credentials.
Request protocol
A standardized format for requesting a digital credential, designed to ensure the secure, private, and interoperable exchange of identity information. See section 9. Registry of protocols for requesting digital credential.

3. Scope

The following items are within the scope of this specification:

The following items are out of scope:

4. Extensions to the Navigator interface 

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

4.1 The identity attribute

The identity attribute provides access to the the underlying CredentialsContainer for managing digital credentials.

4.2 Extensions to Credential Management API

Issue 65: Credential Management integration spec

The CM spec's Extensions points outlines the following things to do to integrate. Adding as a todo list:

This document provides a generic, high-level API that’s meant to be extended with specific types of credentials that serve specific authentication needs. Doing so is, hopefully, straightforward.

- [X] Define a new interface that inherits from [Credential](https://www.w3.org/TR/credential-management-1/#credential):

Define appropriate:

You might also find that new primitives are necessary. For instance, you might want to return many Credential objects rather than just one in some sort of complicated, multi-factor sign-in process. That might be accomplished in a generic fashion by adding a getAll() method to CredentialsContainer which returned a sequence<Credential>, and defining a reasonable mechanism for dealing with requesting credentials of distinct types.

For any such extension, we recommend getting in touch with [public-webappsec@](mailto:public-webappsec@w3.org) for consultation and review.

5. Extensions to CredentialRequestOptions dictionary 

WebIDLpartial dictionary CredentialRequestOptions {
  DigitalCredentialRequestOptions digital;
};

5.1 The digital member

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

6. The DigitalCredentialRequestOptions dictionary 

WebIDLdictionary DigitalCredentialRequestOptions {
  sequence<IdentityRequestProvider> providers;
};

6.1 The providers member

The providers specify a request protocol and structured request, which the user agent MAY match against a identity credential provider.

7. The IdentityRequestProvider dictionary

The IdentityRequestProvider dictionary is used to specify a request protocol and structured request, which the user agent MAY match against a identity credential provider. 

WebIDLdictionary IdentityRequestProvider {
  required DOMString protocol;
  required DOMString request;
};

7.1 The protocol member

The protocol member denotes the request protocol when requesting an identify credential.

The protocol member's value is be one of the well-defined keys defined in 9. Registry of protocols for requesting digital credential or any other custom one.

7.2 The request member

The request member is the request to be handled by the user's selected identity credential provider.

8. The DigitalCredential interface

The DigitalCredential interface represents a conceptual digital credential. 

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

8.1 The protocol member

The protocol member is the request protocol that was used to request the digital credential.

8.2 The data member

The data member is the credential's encrypted data.

9. Registry of protocols for requesting digital credential

The following is the registry of request protocols that are supported by this specification.

Note: Official Registry

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

9.1 Inclusion criteria

To be included in the registry...

Issue 58: Registry inclusion criteria

We need to come up with a registry governance and inclusion criteria.

For inclusion, at a minimum, there should be implementation support, and we talked about having some privacy checks too.

User agents MUST support the following request protocols:

Table of officially registered request protocols.
Protocol identifier Description Specification
Coming soon...

10. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY and MUST 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.

A. References

A.1 Normative references

[credential-management-1]
Credential Management Level 1. Nina Satragno; Marcos Caceres. W3C. 13 August 2024. W3C Working Draft. URL: https://www.w3.org/TR/credential-management-1/
[fetch]
Fetch Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://fetch.spec.whatwg.org/
[html]
HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[infra]
Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[vc-data-model]
Verifiable Credentials Data Model v1.1. Manu Sporny; Grant Noble; Dave Longley; Daniel Burnett; Brent Zundel; Kyle Den Hartog. W3C. 3 March 2022. W3C Recommendation. URL: https://www.w3.org/TR/vc-data-model/
[WEBIDL]
Web IDL Standard. Edgar Chen; Timothy Gu. WHATWG. Living Standard. URL: https://webidl.spec.whatwg.org/

A.2 Informative references

[w3c-process]
W3C Process Document. Elika J. Etemad (fantasai); Florian Rivoal. W3C. 2 November 2021. URL: https://www.w3.org/Consortium/Process/