Skip to content
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

Jump to bottom

Add more detail to DID Authentication section. #18

Merged
merged 8 commits into from Aug 14, 2022
Merged

Add more detail to DID Authentication section. #18

Changes from 3 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
2fcee65
Update DID Authentication introduction and examples.
msporny Aug 7, 2022
0edf045
Add normative details on DID Authentication query format.
msporny Aug 7, 2022
e753bd0
Update complex DID Authentication use case to add did:key.
msporny Aug 7, 2022
f1a5e97
Add DID Authentication Response Format section.
msporny Aug 8, 2022
0889042
Fix grammar in DID Authentication section.
msporny Aug 8, 2022
d939bad
Implement object descriptors for DID Methods.
msporny Aug 14, 2022
8340869
Apply fixes to DID Authentication from @TallTed.
msporny Aug 14, 2022
e7c4a51
Add object descriptors for cryptosuites.
msporny Aug 14, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
143 changes: 128 additions & 15 deletions index.html
View file
Open in desktop
Expand Up @@ -188,6 +188,9 @@ <h2>Overview</h2>

</section>

<section id="conformance">
</section>

<section class="informative">
<h2>Terminology</h2>

Expand All @@ -196,7 +199,7 @@ <h2>Terminology</h2>
</section>

<section class="normative">
<h2>Query Types</h2>
<h2>Query and Response Types</h2>

<p>
The <dfn>query type</dfn> serves as the main extension point mechanism for
Expand Down Expand Up @@ -303,36 +306,146 @@ <h3>Query By Frame</h3>
</section>

<section>
<h3>DID Authentication Request</h3>
<h3>DID Authentication</h3>

<p>
This section defines how a <a>verifier</a> can request that a
<a>holder</a> performs a Decentralized Identifier-based Authentication
msporny marked this conversation as resolved.
Show resolved Hide resolved
[[?DID-CORE]]. In its simplest form, the authentication protocol is comprised
of a challenge by the <a>verifier</a> and a response by a <a>holder</a>:
</p>

<pre class="example nohighlight" title="A DIDAuth request">
<pre class="example" title="A DID Authentication request">
{
query: [{
type: 'DIDAuth'
"query": [{
"type": "DidAuthentication"
}],
challenge: '99612b24-63d9-11ea-b99f-4f66f3e4f81a',
domain: 'example.com'
"challenge": "99612b24-63d9-11ea-b99f-4f66f3e4f81a",
"domain": "example.com"
}
</pre>

<p>Response:</p>
<p>
The DID Authentication request above specifies that the <a>verifier</a> would
like the <a>holder</a> to demonstrate control over a DID by generating a
digital signature over the provided challenge. The <a>holder</a> might respond
by providing the following response:
</p>

<pre class="example nohighlight" title="A DIDAuth response">
<pre class="example" title="A DID Authentication response">
{
"@context": ["https://www.w3.org/2018/credentials/v1"],
"@context": ["https://www.w3.org/2022/credentials/v2"],
"type": "VerifiablePresentation",
"holder": "did:example:12345",
"proof": {
"proofPurpose": "authentication",
"type": "Ed25519Signature2018",
"type": "DataIntegritySignature",
"cryptosuite": "eddsa-2022",
"verificationMethod": "did:example:12345#key-1",
"challenge": "99612b24-63d9-11ea-b99f-4f66f3e4f81a",
"domain": "example.com",
"created": "2020-06-06T21:05:13Z",
"verificationMethod": "did:example:12345#z6Mkkg...",
"jws": "..."
"created": "2022-02-25T14:58:42Z",
"proofPurpose": "authentication",
"proofValue": "z3FXQjecWufY46...UAUL5n2Brbx"
}
}
</pre>

<section>
<h3>The DID Authentication Query Format</h3>

<p>
The DID Authentication query format enables a <a>verifier</a> to request that a
<a>holder</a> authentication in specific ways. A DID Authentication query
msporny marked this conversation as resolved.
Show resolved Hide resolved
MUST be of the following form:
</p>
<table class="simple">
<tr>
<th>Property</th>
<th>Description</th>
</tr>
<tr>
<td>type</td>
<td>
a REQUIRED string value that MUST be set to <code>DIDAuthentication</code>.
</td>
</tr>
<tr>
<td>didMethod</td>
<td>
An optional set of one or more values that conveys the DID Methods that are
supported by the <a>verifier</a>. If only one DID Method is listed, the value
MUST be a string containing the DID Method name. If more than one DID Method is
listed, the value MUST be an array of string values and each string value
MUST be a string containing the DID Method name. Listing multiple values
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
MUST be a string containing the DID Method name. Listing multiple values
MUST be a string containing a DID Method name. Listing multiple values

expresses that the <a>verifier</a> would accept any DID Method listed. Valid
example values include: <code>"key"</code> and <code>["key", "web"]</code>.
Copy link
Contributor

@dlongley dlongley Aug 7, 2022 •
edited

Choose a reason for hiding this comment

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

I would support making this always be an array instead to ease some concerns from other implementers around native type handling in some languages. I'm fine either way.

Copy link
Contributor

Choose a reason for hiding this comment

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

In the open/decentralized ecosystem, I believe the common pattern will be for Verifiers to accept multiple types of DID methods, so +1 to always having this as an array.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Ok, I'll make this change and merge it into this PR.

Copy link
Contributor

Choose a reason for hiding this comment

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

might it make sense to make the didMethod array contain objects, instead of just strings? There's a very good chance that various DID methods require multiple parameters for a given method. (For example, how Veres One DID method has a testnet vs main, cryptonyms vs not, etc).

Copy link
Contributor Author

Choose a reason for hiding this comment

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

We discussed this on the 2022-08-09 telecon. The group seemed to have consensus around the didMethod value always being an array. The group didn't object to renaming didMethod to acceptedMethods to ensure that the contents of the array is always a set of objects. Each object MUST contain at least an entry for method and MAY contain other parameters that are specific to the DID Method.

Copy link
Contributor Author

@msporny msporny Aug 14, 2022 •
edited

Choose a reason for hiding this comment

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

Fixed in d939bad.

</td>
</tr>
<tr>
<td>cryptosuite</td>
<td>
An optional string value that conveys a cryptography suite that MUST be
used by the <a>holder</a> to generate a cryptographic proof. Valid example
values include: <code>"eddsa-2022"</code>, <code>"ecdsa-2022"</code> and
<code>"bbs-2022"</code>.
Copy link
Contributor

Choose a reason for hiding this comment

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

Why is this only a single option? Wouldn't verifiers support multiple crypto suites?

Copy link
Contributor

Choose a reason for hiding this comment

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

nvm, seen below that a request may contain multiple DIDAuth requests.

Copy link
Contributor Author

@msporny msporny Aug 8, 2022 •
edited

Choose a reason for hiding this comment

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

Yeah, I went back and forth on this. There is a combinatoric concern here with listing all the DID Methods and all the cryptosuites, making it an NxN selection, which then gets more multidimensional if we have other "possible things you could do". I'm suggesting that we start with a single value and then depend on the ability to send multiple queries (some of them optional) to suggest the support for multiple cryptosuites. The downside there, of course, is if you support multiple cryptosuites, you have a new query for every cryptosuite. I expect that we might just have to make this an array in time, and if that's the case, we should just do it now... but the counter-argument to that is to make it painful to support more than a handful of cryptosuites to force an increase in interop!

In the end, I expect that we'll probably have to support an array of cryptosuites here.

Copy link
Contributor

Choose a reason for hiding this comment

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

Maybe we should just start with an array of cryptosuites? To match the array of did methods?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

We discussed this on the 2022-08-09 telecon. @dlongley suggested that we rename the value to acceptedCryptosuites and make the value an array of objects where we could parameterize each cryptosuite. Each object MUST contain a cryptosuite property and MAY contain other cryptosuite-specific parameters.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Fixed in e7c4a51.

</td>
</tr>
</table>

<p>
The following example demonstrates that the <a>verifier</a> would like the
<a>holder</a> to utilize the DID Web Method and the 2022 ECDSA cryptography
msporny marked this conversation as resolved.
Show resolved Hide resolved
suite to authenticate over the established communication channel, such as the
Credential Handler API (CHAPI):
</p>

<pre class="example"
title="A DID Authentication request using did:web and ecdsa-2022">
{
"query": [{
"type": "DidAuthentication",
"didMethod": "web",
"cryptosuite": "ecdsa-2022"
}],
"challenge": "99612b24-63d9-11ea-b99f-4f66f3e4f81a",
"domain": "example.com"
}
</pre>

<p>
The next example demonstrates that the <a>verifier</a> would like the
<a>holder</a> to utilize either the DID Key or DID Web Method and the 2022 EdDSA
msporny marked this conversation as resolved.
Show resolved Hide resolved
cryptography suite, and optionally also include a cryptographic proof that they
are capable of performing a 2022 BBS proof, and authenticate over a different
communication channel, in this case utilising a Verifiable Credential API HTTP
msporny marked this conversation as resolved.
Show resolved Hide resolved
endpoint:
</p>

<pre class="example" title="A complex DID Authentication request">
{
"query": [{
"type": "DidAuthentication",
"didMethod": ["key", "web"],
"cryptosuite": "ecdsa-2022"
}, {
"type": "DidAuthentication",
"required": false,
"didMethod": ["key", "web"],
"cryptosuite": "bbs-2022"
}],
"challenge": "zLEwtBYgQVNR4tyeo",
"domain": "didauth.example",
"interact": {
"service": [{
"type": "UnmediatedHttpPresentationService2021",
"serviceEndpoint": "https://didauth.example/exchanges/zYRo25k7G2UVWkrNt"
}]
}
}
</pre>

</section>

</section>

<section>
Expand Down