Draft
Community
Group
Report
08
October
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.
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.
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.
TBW
There are many types of digital credential that can be conveyed 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:
WebIDLpartial dictionary CredentialRequestOptions {
DigitalCredentialRequestOptions digital;
};
The
digital
member
allows
for
options
to
configure
the
request
for
a
digital
credential
.
WebIDLdictionary DigitalCredentialRequestOptions {
sequence<DigitalCredentialsRequest> requests;
};
The
requests
specify
an
exchange
protocol
and
request
data
,
which
the
user
agent
MAY
match
against
a
holder's
software,
such
as
a
digital
wallet.
The
DigitalCredentialsRequest
dictionary
represents
a
presentation
request
.
It
is
used
to
specify
an
exchange
protocol
and
a
request
data
,
which
the
user
agent
MAY
match
against
software
used
by
a
holder,
such
as
a
digital
wallet.
WebIDLdictionary DigitalCredentialsRequest {
required DOMString protocol;
required object data;
};
The
protocol
member
denotes
the
exchange
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.
The
data
member
is
the
request
data
to
be
handled
by
the
holder's
software,
such
as
a
digital
wallet.
The
DigitalCredential
interface
represents
a
conceptual
digital
credential
.
User
mediation
is
always
"
required
".
Requesting
a
DigitalCredential
credential
does
not
support
"
conditional
",
"
optional
",
or
"
silent
"
user
mediation
.
If
get
()
is
called
with
anything
other
than
"
required
",
a
TypeError
will
be
thrown.
WebIDL[Exposed=Window, SecureContext]
interface DigitalCredential : Credential {
[Default] object toJSON();
readonly attribute DOMString protocol;
readonly attribute object data;
};
DigitalCredential
instances
are
origin
bound
.
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.
Define appropriate:
[[CollectFromCredentialStore]](origin, options, sameOriginWithAncestors) . [[CollectFromCredentialStore]](origin, options, sameOriginWithAncestors) is appropriate for credentials that remain effective forever and can therefore simply be copied out of the credential store
[[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) . [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) is appropriate for credentials that need to be re-generated from a credential source .
[[Store]](credential, sameOriginWithAncestors) methods on ExampleCredential's interface object .
Long-running operations, like those in PublicKeyCredential 's [[Create]](origin, options, sameOriginWithAncestors) and [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) operations are encouraged to use options.signal to allow developers to abort the operation. See DOM §3.3 Using AbortController and AbortSignal objects in APIs for detailed instructions.
ExampleCredential's [[CollectFromCredentialStore]](origin, options, sameOriginWithAncestors) internal method is called with an origin (origin), a CredentialRequestOptions object (options), and a boolean which is true iff the calling context is same-origin with its ancestors . The algorithm returns a set of Credential objects that match the options provided. If no matching Credential objects are available, the returned set will be empty.
Define the value of the ExampleCredential interface object 's [[type]] slot:
Define the value of the ExampleCredential interface object 's [[discovery]] slot:
Extend (using partial dictionary) CredentialRequestOptions with the options the new credential type needs to respond reasonably to get() .
Extend (using partial dictionary) CredentialCreationOptions with the data the new credential type needs to create Credential objects in response to create() .
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
.
The
protocol
member
is
the
exchange
protocol
that
was
used
to
request
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 :
Document
.
NotAllowedError
"
DOMException
.
NotAllowedError
"
DOMException
.
digital
's
requests
member.
TypeError
.
DigitalCredential
.
When
invoked,
the
[[Store]](credential,
sameOriginWithAncestors)
MUST
call
the
default
implementation
of
Credential
's
[[Store]](
credential
,
sameOriginWithAncestors
)
internal
method
with
the
same
arguments.
When
invoked,
the
[[Create]](origin,
options,
sameOriginWithAncestors)
internal
method
MUST
call
the
default
implementation
of
Credential
's
[[Create]](
origin
,
options
,
sameOriginWithAncestors
)
internal
method
with
the
same
arguments.
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".
This section is non-normative.
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
get
()
method.
This specification defines a policy-controlled feature identified by the string "digital-credentials-get" . Its default allowlist is 'self' .
The following is the registry of exchange 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...
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 exchange protocols :
| Protocol identifier | Description | Specification |
|---|---|---|
| Coming soon... | ||
This section is non-normative.
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.
This section is non-normative.
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.
This section is non-normative.
This section is a work in progress as this document evolves.
WebIDLpartial dictionary CredentialRequestOptions {
DigitalCredentialRequestOptions digital;
};
dictionary DigitalCredentialRequestOptions {
sequence<DigitalCredentialsRequest> requests;
};
dictionary DigitalCredentialsRequest {
required DOMString protocol;
required object data;
};
[Exposed=Window, SecureContext]
interface
interface DigitalCredential : Credential {
[Default] object toJSON();
readonly attribute DOMString protocol;
readonly attribute object data;
};
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.
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: