Skip to content

Change from Registry to Supported Protocols #401

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
timcappalli wants to merge 7 commits into
base: main
Choose a base branch
from
Draft

Change from Registry to Supported Protocols #401

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
08ca900
initial changes for supported protocols
timcappalli Dec 1, 2025
9f4fd0a
Merge branch 'main' into 396-supported-protocols
timcappalli Dec 1, 2025
b962211
add to dictionary
timcappalli Dec 1, 2025
3ffca6e
move section up
timcappalli Dec 1, 2025
ccd4db1
tweaks
timcappalli Dec 2, 2025
3ba6495
refactor spec references
timcappalli Dec 2, 2025
ebab51d
remove names after spec ref refactor
timcappalli Dec 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .cspell/misc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,6 @@ linkable
linkability
fingerprinters
birthdates
reidentify
reidentify
multisigned
licence
296 changes: 100 additions & 196 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@
authors: ["Simone Onofri"],
date: "2025-02-25",
publisher: "W3C"
},
}
},
xref: {
profile: "web-platform",
Expand Down Expand Up @@ -113,12 +113,8 @@ <h2 class="informative">
and issuance of a [=digital credential=].
</p>
<p>
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 design is agnostic to credential formats and includes support for
multiple [=digital credential/exchange protocols=]. See [[[#supported-protocols]]].
</p>
<p>
The API is designed to support the following goals:
Expand Down Expand Up @@ -524,8 +520,7 @@ <h2>
<dd>
A standardized protocol used for exchanging a [=digital credential=]
between a [=holder=] and a [=verifier=]. A protocol is identified by a
[=digital credential/protocol identifier=]. See section also
[[[#protocol-registry]]].
[=digital credential/protocol identifier=]. See [[[#supported-protocols]]].
</dd>
<dt>
<dfn data-dfn-for="digital credential">Protocol identifier</dfn>
Expand All @@ -544,15 +539,105 @@ <h2>
A standardized protocol used for communication between an [=issuer=]
and a [=holder=] during the issuance of a [=digital credential=]. The
issuance protocol is identified by a [=digital credential/protocol
identifier=]. See also section [[[#protocol-registry]]].
identifier=]. See [[[#supported-protocols]]].
</dd>
<dt>
Request coordinator
</dt>
<dd>
See [=credential request coordinator=].
</dd>
</dl><!--
</dl>
<!--
// MARK: Supported Protocols
-->
<h2 id="supported-protocols">
Supported protocols
Copy link
Collaborator

@marcoscaceres marcoscaceres Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should avoid the word "Supported" as passive voice begs the question "supported by who?". Also, it's not clear what "supported by this specification" means.

This should really be about, "protocols that are known to be allowed by user agents" as verified by userAgentAllowsProtocol() for instance.

We could even have a column(s) for user agent or engine (WebKit | Gecko | Chromium).

Copy link
Collaborator Author

@timcappalli timcappalli Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The text says: "supported by this specification."

</h2>
<p>
The following [=digital credential/exchange protocols=] are supported
by this specification.
</p>
<table class="data">
<caption>
Table of supported [=digital credential/exchange protocols=]
</caption>
<thead>
<tr>
<th>
Name
</th>
<th>
Type
</th>
<th>
[=digital credential/Protocol identifier=]
</th>
<th>
Reference
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
OpenID for Verifiable Presentations 1.0 - Unsigned Requests
</td>
<td>
[=digital credential/Exchange Protocol=]
</td>
<td>
`openid4vp-v1-unsigned`
</td>
<td>
[[OPENID4VP]] Appendix A
</td>
</tr>
<tr>
<td>
OpenID for Verifiable Presentations 1.0 - Signed Requests
</td>
<td>
[=digital credential/Exchange Protocol=]
</td>
<td>
`openid4vp-v1-signed`
</td>
<td>
[[OPENID4VP]] Appendix A
</td>
</tr>
<tr>
<td>
OpenID for Verifiable Presentations 1.0 - Multi-signed Requests
</td>
<td>
[=digital credential/Exchange Protocol=]
</td>
<td>
`openid4vp-v1-multisigned`
</td>
<td>
[[OPENID4VP]] Appendix A
</td>
</tr>
<tr>
<td>
ISO/IEC 18013-7:2025 - Annex C
</td>
<td>
[=digital credential/Exchange Protocol=]
</td>
<td>
`org-iso-mdoc`
</td>
<td>
[[ISO18013-7]] Annex C
</td>
</tr>
</tbody>
</table>
<!--
// MARK: Credential Request Coordinator
-->
<h2>
Expand Down Expand Up @@ -767,9 +852,8 @@ <h4>
denotes the [=digital credential/exchange protocol=].
</p>
<p>
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 {{DigitalCredentialCreateRequest/protocol}} member's value MUST be one
Copy link
Collaborator

@marcoscaceres marcoscaceres Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This basically makes it an enum... if we put MUST here, then we need to also specify what happens when the value is not one of these (i.e., be mindful when this is user agent requirement or an authoring requirement).

Copy link
Collaborator Author

@timcappalli timcappalli Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes, this PR is not done (it is marked draft and not ready for review)...

Copy link
Collaborator

@marcoscaceres marcoscaceres Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Noted... ping when ready or want me to have another early look.

of the protocol identifiers defined in [[[#supported-protocols]]].
</p>
<h4>
The `data` member
Expand Down Expand Up @@ -841,9 +925,8 @@ <h4>
member denotes the [=digital credential/issuance protocol=].
</p>
<p>
The {{DigitalCredentialCreateRequest/protocol}} member's value is be one
of the well-defined keys defined in [[[#protocol-registry]]] or any other
custom one.
The {{DigitalCredentialCreateRequest/protocol}} member's value MUST be one
Copy link
Collaborator

@marcoscaceres marcoscaceres Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As above...

of the protocol identifiers defined in [[[#supported-protocols]]].
</p>
<h4>
The `data` member
Expand Down Expand Up @@ -1125,185 +1208,6 @@ <h2>
</dd>
</dl>
</section>
<h2 id="protocol-registry">
Registry of protocols
Copy link
Collaborator

@marcoscaceres marcoscaceres Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree we should delete this, but I'm wondering if any of this is salvageable for how new protocols are added to the spec. Should we have a non-normative note about "file a bug if you think your protocol belongs here?" or something?

</h2>
<p>
Initiating the registration a protocol is done by <a href=
"https://github.com/w3c-fedid/digital-credentials/issues">filing an
issue</a> in our GitHub repository.
</p>
<p>
The following is the registry of [=digital credential/exchange
protocols=] and [=digital credential/issuance protocols=] that are
supported by this specification.
</p>
<p class="note" title="Official Registry" data-cite="w3c-process">
It is expected that this registry will be become a [=W3C registry=] in
the future.
</p><!--
// MARK: General inclusion criteria
-->
<h3>
General inclusion criteria
</h3>
<aside class="note">
The below criteria are a work in progress and are likely to change as
this document evolves.
</aside>
<p>
To be included in the registry, the [=digital credential/exchange
protocol=]:
</p>
<ol>
<li>MUST be standardized at a <a href=
"https://www.w3.org/liaisons/">consortium the W3C liaises with</a>
</li>
<li>MUST be defined in a specification which is freely and publicly
available at the stable URL listed in the registry.
</li>
<li>MUST define a representation, as either a [[WebIDL]] [=dictionary=]
or a JSON object, of the [=digital credential/exchange protocol=] request
structure (i.e., the [=dictionary=] which defines the semantics and
validation of the {{DigitalCredentialGetRequest}}'s
{{DigitalCredentialGetRequest/data}} member) and the [=digital
credential/issuance protocol=] request structure (i.e., the
[=dictionary=] which defines the semantics and validation of the
{{DigitalCredentialCreateRequest}}'s
{{DigitalCredentialCreateRequest/data}} member).
</li>
<li>MUST define a representation, as either a [[WebIDL]] [=dictionary=]
or a JSON object, of the [=digital credential/exchange protocol=]
response structure (i.e., the [=dictionary=] which defines the semantics
and validation of the {{DigitalCredential}}'s {{DigitalCredential/data}}
member.
</li>
<li>MUST define validation rules for members of the request and response
structures.
</li>
<li>MUST have undergone privacy review by the W3C's <a href=
"https://www.w3.org/groups/wg/privacy/">Privacy Working Group</a> and
<a href="https://www.w3.org/groups/wg/fedid/">Federated Identity Working
Group</a>.
<aside class="note" title="Organizing reviews">
Once an expression of registration is received via GitHub, the
registry maintainers will organize the privacy review with the
<a href="https://www.w3.org/groups/wg/privacy/">Privacy Working
Group</a> . Please see the [[[security-privacy-questionnaire]]] for
the kind of questions that will be asked of the protocol you are
registering.
</aside>
</li>
<li>MUST have undergone security review by the <a href=
"https://www.w3.org/groups/ig/security/">Security Interest Group</a>.
</li>
<li>MUST have implementation commitment from at least one browser engine,
one credential provider/wallet, and one issuer or verifier (depending on
the protocol type). Each component MUST be from independent
organizations.
</li>
<li>MUST have formally recorded consensus by the Federated Identity
Working Group to be included in the registry.
</li>
</ol>
<h4>
Presentation-specific inclusion criteria
</h4>
<p>
To be included as a presentation protocol in the registry (used with
`navigator.credentials.get`), the [=digital credential/exchange
protocol=]:
</p>
<ol>
<li>MUST support response encryption.
</li>
<li>MUST encrypt any response containing personally identifiable
information (PII).
</li>
</ol><!--
// MARK: Change process
-->
<h3>
Change process
</h3>
<p>
To add a new [=digital credential/exchange protocol=] to the registry, or
to update an existing one:
</p>
<dl>
<dt>
Define a [=digital credential/protocol identifier=].
</dt>
<dd>
The [=digital credential/protocol identifier=] MUST be a unique string
that is not already in use in the registry. The [=digital
credential/protocol identifier=] MUST uniquely define the set of
required parameters and/or behavior that a digital credential provider
implementation needs to support to successfully handle the request. If
the set of required parameters or behaviors is updated in a way which
would require a digital credential provider to also require an update
to remain functional, a new protocol identifier MUST be assigned and be
added to the registry.
</dd>
<dt>
Specify a <dfn data-dfn-for="registry" data-local-lt="type">protocol
type</dfn>.
</dt>
<dd>
The protocol type is either "Presentation" for presentation protocols
used with `navigator.credentials.get` or "Issuance" for issuance
protocols used with `navigator.credentials.create`.
</dd>
<dt>
<dfn data-dfn-for="registry" data-local-lt="description">Describe the
protocol</dfn>.
</dt>
<dd>
The description MUST be a brief summary of the protocol's purpose and
use case.
</dd>
<dt>
Provide a <dfn data-dfn-for="registry" data-local-lt="link">link to the
specification</dfn>.
</dt>
<dd>
The specification MUST be a stable URL that points to the authoritative
source for the protocol, including validation rules.
</dd>
</dl>
<p>
[=User agents=] MUST support the following [=digital credential/exchange
protocols=]:
</p>
<table class="data">
<caption>
Table of officially registered [=digital credential/exchange
protocols=].
</caption>
<thead>
<tr>
<th>
[=digital credential/Protocol identifier=]
</th>
<th>
[=registry/Type=]
</th>
<th>
[=registry/Description=]
</th>
<th>
[=registry/link|Specification=]
</th>
</tr>
</thead>
<tbody>
<tr>
<td colspan="4">
Coming soon...
</td>
</tr>
</tbody>
</table>
<section class="informative">
<!--
// MARK: Security Considerations
Expand Down