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

Update resolution scheme #42 #47

Closed
wants to merge 6 commits into from
Closed

Update resolution scheme #42 #47

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
b03ff0c
Update resolution scheme #42
Nov 23, 2021
db763a1
remove mime types, refer to DID core IANA considerations #47
Nov 24, 2021
b7ffd8e
explain webserver index files #47
Nov 24, 2021
93a94dc
restate abstract in positive terms #47
Nov 30, 2021
e308e22
remove normative languge from implementation-specific configuration d…
Nov 30, 2021
f18ed93
defer full filenames #47
Nov 30, 2021
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
169 changes: 108 additions & 61 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,13 +98,12 @@
<body>
<section id="abstract">
<p>
DIDs that target a distributed ledger face significant practical challenges in
bootstrapping enough meaningful trusted data around identities to incentivize
mass adoption. We propose using a new DID method in conjunction with
blockchain-based DIDs that allows them to bootstrap trust using a web domain's
existing reputation.
We propose a DID method that leverages globally deployed infrastructure that is
readily available to billions of people who use the Web with a trust model based
on DNS and TLS certificates that is widely understood and accepted today.
</p>
</section>

<section id="sotd">
</section>
<section>
Expand Down Expand Up @@ -210,36 +209,12 @@ <h2>

<pre class="example nohighlight" title="Example Web Method DIDs">
did:web:w3c-ccg.github.io

did:web:w3c-ccg.github.io:user:alice

did:web:example.com%3A3000
did:web:example.com%3A3000:bob%3Awork
</pre>
</section>

<section>
<h2>
JSON-LD context definition
</h2>
<p>
The definition of the Web DID JSON-LD context is:
</p>

<pre title="Web DID method JSON-LD context">
{
"@context":
{
"ethereumAddress": "https://github.com/uport-project/ethr-did-resolver#ethereumAddress",
"Secp256k1VerificationKey2018": "https://github.com/uport-project/ethr-did-resolver#Secp256k1VerificationKey2018",
"Secp256k1SignatureAuthentication2018": "https://github.com/uport-project/ethr-did-resolver#Secp256k1VerificationKey2018",
}
}
</pre>
<p class="issue" title="Update context">
Bring the context definition in line with latest DID Core.
</p>
</section>

Comment on lines -220 to -242
Copy link
Contributor

Choose a reason for hiding this comment

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

How do we express new cryptographic keys in a machine readable way? For example, when post-quantum public keys become a thing, how do we enforce any sort of machine verifiability here? How do I say I want to express JWK-based public keys and not LDI-based public keys?

Copy link
Contributor

Choose a reason for hiding this comment

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

Is this PR making it so that it's illegal for a did:web-based DID Document to contain JSON-LD?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

This PR does not, at present, rule out JSON-LD. There is ongoing discussion on the topic, but this PR is currently representation-agnostic.

<section>
<h2>
DID method operations
Expand All @@ -260,41 +235,46 @@ <h3>
service
</li>
<li>
creating the DID document JSON-LD file including a suitable keypair, e.g.,
using the Koblitz Curve, and storing the <code>did.json</code> file under the
well-known URL to represent the entire domain, or under the specified path if
many DIDs will be resolved in this domain.
creating the DID document JSON, and storing the file as the index of the
Copy link
Collaborator

Choose a reason for hiding this comment

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

re "storing the file as the index" -- we don't define what we mean by "index" anywhere.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I am referring to the "directory index'. It has been commonplace for webservers to return index.html or some other configured. Nginx uses index and Apache uses DirectoryIndex to set a file or files to return when a user requests a directory path.

I can add a description.

Copy link
Collaborator

Choose a reason for hiding this comment

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

Thanks. Adding a description would be helpful (so that people don't think we mean index.html)

Copy link
Contributor Author

@gribneau gribneau Nov 24, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

index.html has been a common default as long as I can remember, but it is possible to set other files as the index.

Does this do it?
b7ffd8e

<code>/.well-known/did/</code> directory to represent the entire domain, or as
the index of the specified path, or as a file with the filename and path matching
the method specific identifier.
</li>
</ol>

<p>
For example, for the domain name `w3c-ccg.github.io`, the `did.json` will be
available under the following URL:
The well-known URL for a domain name is the simplest example:
</p>

<pre class="example nohighlight" title="Creating the DID">
<pre class="example nohighlight" title="DID at well known path">
did:web:w3c-ccg.github.io
-> https://w3c-ccg.github.io/.well-known/did.json
-> https://w3c-ccg.github.io/.well-known/did/
Copy link
Collaborator

Choose a reason for hiding this comment

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

I interpret this as really => https://w3c-ccg.github.io/.well-known/did/index.json after some internal server redirect... can you confirm?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Index files - the files returned when a directory is requested - are configured on the server.

Index.html has been a default for ages, but any file name may be specified in most webserver configurations.

Copy link
Contributor

Choose a reason for hiding this comment

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

I don't understand how we're supposed to interpret this change.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

The resolver translates the method specific identifier to a URL and makes an HTTPS request to retrieve the DID document. This changes the HTTPS URL to a directory rather than a full file path in order to meet the requirements in IANA Considerations to support multiple representations with appropriate filename extensions and content types (which are mapped to filename extensions in webservers and many clients).

->  - https://w3c-ccg.github.io/.well-known/did.json
->  + https://w3c-ccg.github.io/.well-known/did/

The first url should always return a content type of application/json based on the .json filename extension, while the second can return the contents of a file named appropriately for a different DID representation, together with the associated content type HTTP response header.

If we return a file with a .json filename extension, and a content type header value associated with some alternate DID representation, we potentially break a long standing best practice. One can argue that .json is consistent with application/did+json and application/did+ld+json, but as soon as we see application/did+cbor or some other alternative, we'll no longer have an argument that we're in compliance.

</pre>

<p>
If an optional path is specified rather the bare domain, the
<code>did.json</code> will be available under the specified path:
If an optional path is specified in addition to the bare domain, the
file will be available as the index of the specified path:
Copy link
Collaborator

Choose a reason for hiding this comment

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

Same as above -- it's unclear what "index of the specified path" means.

</p>

<pre class="example nohighlight" title="Creating the DID with optional path">
<pre class="example nohighlight" title="DID with optional path">
did:web:w3c-ccg.github.io:user:alice
-> https://w3c-ccg.github.io/user/alice/did.json
-> https://w3c-ccg.github.io/user/alice/
</pre>

<p>
If an optional port is specified on the domain, the port colon splitting the
host and the port MUST be percent encoded to prevent collision with the path.
If an optional port is specified on the domain, the colon splitting the host and
the port MUST be percent encoded to prevent collision with the path.
</p>
<pre class="example nohighlight" title="DID with port and path">
did:web:example.com%3A3000:user:alice
-> https://example.com:3000/user/alice/
</pre>

<pre class="example nohighlight" title="Creating the DID with optional path and port">
did:web:example.com%3A3000:user:alice
-> https://example.com:3000/user/alice/did.json
<p>
If an element of the path contains a colon, the colon MUST be percent encoded to
avoid being replaced with a slash:
</p>
<pre class="example nohighlight" title="DID with port, path, and colon">
did:web:example.com:user:alice%3Awork
-> https://example.com/user/alice:work/
</pre>
</section>

Expand All @@ -313,17 +293,18 @@ <h3>
qualified domain name and optional path.
</li>
<li>
If the domain contains a port percent decode the colon.
Replace "%3A" with ":" in the first segment of method specific identifier
containing the fully qualified domain name to support optional port numbers.
</li>
<li>
Generate an HTTPS URL to the expected location of the DID document by
prepending <code>https://</code>.
</li>
<li>
If no path has been specified in the URL, append <code>/.well-known</code>.
If no path has been specified in the URL, append <code>/.well-known/did</code>.
</li>
<li>
Append <code>/did.json</code> to complete the URL.
Append <code>/</code> to complete the URL.
</li>
<li>
Perform an HTTP <code>GET</code> request to the URL using an agent that can
Expand All @@ -332,11 +313,19 @@ <h3>
</li>
<li>
When performing the DNS resolution during the HTTP <code>GET</code> request, the
client SHOULD utilize <div RFC8484=""></div> in order to prevent
Man-in-the-middle attacks as well as to prevent tracking of the lookup.
client SHOULD utilize DNS over HTTPS [[RFC8484]] to minimize tracking of the lookup.
</li>
<li>
If a specific DID representation is preferred a client MAY specify the associated
content type in the <code>Accept:</code> HTTP request header.
</li>
<li>
If the <code>Accept:</code> HTTP request header includes a preferred DID
representation the web server SHOULD attempt to meet that preference when
selecting an index file to return by matching the content type to the filename
extension.
</li>
</ol>

<p class="issue" data-number="13">
The read mechanism does not provide any sort of auditability on the DID, which
leaves this DID Method open to insider-threat attacks, among others.
Expand All @@ -353,11 +342,17 @@ <h3>
Update
</h3>
<p>
To update the DID document, the <code>did.json</code> has to be updated.
To update the DID document, the associated file or files have to be updated.
Copy link
Collaborator

Choose a reason for hiding this comment

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

single file currently, no support for multiple representations, JSON only... for now at least.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I disagree.

Index files are configured server-side, and we should leave that capability in place.

Copy link
Contributor

Choose a reason for hiding this comment

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

Where did this whole index file thing come from? What's the use case there?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Index files have always been with us. Wikipedia has a historic overview.

The use case here is to comply with the core spec on various representations without breaking other long-standing best practices on filename extension and content type header agreement.

Please note that the DID will remain the same, but the contents of the DID
document could change, e.g., by including a new verification key or adding
service endpoints.
</p>
<p>
In the event that multiple representations of the same DID are present in a
directory, updates of all representations MUST be made when any representation is
updated. Key material and service endpoints MUST be consistent across representations
of a DID. Other metadata SHOULD be consistent across representations.
Copy link
Collaborator

Choose a reason for hiding this comment

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

Let's remove this possibility, JSON only for DID Web.... no JSON-LD and no CBOR.

They are interop destroying, and create massive security issues, we don't need them, at least right now.

Copy link
Collaborator

@dmitrizagidulin dmitrizagidulin Nov 29, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

@OR13 - wait, in what way are JSON-LD did:webs interop destroying?

Copy link
Collaborator

Choose a reason for hiding this comment

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

@OR13 - n/m, I think I'm +1 with just JSON for DID Web.

Copy link
Contributor

Choose a reason for hiding this comment

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

They are interop destroying, and create massive security issues, we don't need them, at least right now.

Citation? Strong opinions require strong evidence.

</p>

<p class="issue" data-number="12">
This DID method does not specify any authentication or authorization mechanism
Expand All @@ -368,20 +363,72 @@ <h3>
<p class="note" title="HTTP API">
There is no HTTP API specified for the update process leaving programmatic
registrations and management to be defined by each implementation.
</p>
</p>
</section>

<section>
<h3>
Deactivate (Revoke)
</h3>
<p>
To delete the DID document, the <code>did.json</code> has to be removed or has
to be no longer publicly available due to any other means.
To delete the DID document, the associated file or files have to be removed or
made no longer publicly available due to any other means.
</p>
</section>
</section>

<section>
<h2>
Webserver Configuration
</h2>
<h3>
Index Files
</h3>
<p>
Webserver software typically supports returning specified files when a URL path
matches a directory rather than a file. These are generally refered to as index
files, and <code>index.html</code> is a common default. To resolve method specific
identifiers that have no filename and extension, webservers MUST be configured
to return the appropriate DID file when a request path matches a DID directory.
</p>
Comment on lines +385 to +393
Copy link
Contributor

Choose a reason for hiding this comment

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

Can we put this in a separate PR?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

The informational section describing webserver index files was added upon request.

For some audiences, it may be seen as superfluous.

<h3>
MIME Types
</h3>
<p>
Webservers MUST be configured to associate proper content types with registered
filename extensions. The filename extensions and content types are noted in the
[[DID-CORE]] <a href="https://w3c.github.io/did-core/#iana-considerations">IANA
considerations section</a>.
</p>
gribneau marked this conversation as resolved.
Show resolved Hide resolved
<h3>
Multiple DID Representations
</h3>
<p>
DIDs in directories MAY support multiple representations. The server MUST support
at least one of the DID representatons listed in the note above, and MAY support
more than one. If multiple representations are supported, the server MUST prefer
the representation in the HTTP <code>Accept:</code> request header when selecting
an index file to return.
Comment on lines +409 to +411
Copy link
Contributor

Choose a reason for hiding this comment

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

This is confusing since the selection of a representation via HTTP is typically a negotiation between the client and the server... the client can provide preferences and the server typically picks among the ones it supports and prefers to respond with what the client would prefer (not what the server prefers).

Copy link
Contributor Author

Choose a reason for hiding this comment

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

The HTTP request headers are set by the client. The language in the PR obligates implementations to respect the client preference if possible.

Content negotiation is supported in some servers and will require custom configuration or scripting in others. Apache has a mod_negotiation that can be configured, but Nginx will require unusual configuration or scripting to meet the requirement.

</p>
<h3>
Cross Origin Browser Access
</h3>
<p>
Implementations involving web browser clients operating in other domains will
need access to the DID documents. [[CORS]] specifies headers to enable browser
cross-domain access.
</p>
<h3>
Cache Control
</h3>
<p>
Web browsers, proxies, and CDNs Webservers often cache HTTP responses. Select
appropriate cache control header values based on the specific requirements of the
implementation to avoid stale DID documents. [[RFC7234]] specifies headers to
control cache behavior.
</p>
</section>

<section class="informative">
<h2>
Security and privacy considerations
Expand Down Expand Up @@ -539,10 +586,10 @@ <h3>
did:web:example.com:u:bob
</pre>
<p>
resolves to the DID document at:
resolves to the DID document at the index of:
</p>
<pre class="nohighlight">
https://example.com/u/bob/did.json
https://example.com/u/bob/
Copy link
Collaborator

@OR13 OR13 Nov 29, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

https://example.com/u/bob/ -> https://example.com/u/bob/index.json

Adding 1 more arrow here might help better explain the potential upgrade path for other representations....

IMO, DID Web SHOULD NOT support representations other than JSON, because it makes interop harder and introduces dangerous security issues which are "not worth it".

Copy link
Contributor

Choose a reason for hiding this comment

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

Likewise strongly opposed to anything other than JSON here

Copy link
Contributor Author

Choose a reason for hiding this comment

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

The proposed change is to resolve the DID to a directory URL, leaving file selection up to the webserver.

The index file could very well be index.json, but it could also be arbitrary.json if so configured.

The resolvers would request https://example.com/u/bob/.

Copy link
Contributor

Choose a reason for hiding this comment

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

because it makes interop harder and introduces dangerous security issues which are "not worth it".

Citation? Evidence?

Copy link
Collaborator

Choose a reason for hiding this comment

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

@msporny

IMO, DID Web SHOULD NOT support representations other than JSON, because it makes interop harder and introduces dangerous security issues which are "not worth it".

DID Core defines 2 JSON Formats... application/did+json which only requires an id.... and application/did+ld+json which requires an id and @context.... if DID web has to support both, in different files, with potentially different key material, service endpoints, etc... and the JSON version wants to just let JSON be JSON and add fields not defined in the context, and the JSON-LD version wants to add terms only defined in a w3id.org hosted context... and a developer needs to understand both representations... thats all a lot harder than just having a single json file on a web server that has an id property that is a DID.

JSON-LD should be possible, but it should not be required for DID Web... and I don't think we get any value from having 2 JSON files that are potentially different... other than pain.

The simpler we can make DID web, the better.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@OR13 @msporny

The simpler we can make DID web, the better.

I absolutely agree that simplicity in the specification is important.

Is there a middle ground here in which the specification makes a variety of representations possible, but does not require any particular representation?

Resolving to directory paths and leaving file selection up to server configuration and client preference assertion is intended to put the choice of DID representation in the hands of each implementation.

There may be a number of alternative representations in the future, and my preference is a specification that need not be revised each time a new one is added. Static filenames ( did.json ) have been a feature of this specification from the early days when it was intended only as a single anchor for a given domain. The added flexibility of various representations via directory paths feels like an appropriate extension following the support of multiple DIDs on a single domain.

I don't think we get any value from having 2 JSON files that are potentially different...

My intent with this PR is not to require multiple representations, but rather to allow for variety within the representations used by any given implementation. The language indicating that multiple representations must be kept consistent is not intended to imply that multiple representations must exist - only to note they should be consistent if they do exist.

Copy link
Collaborator

Choose a reason for hiding this comment

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

I like a lot of the changes in this PR, but I don't see us getting any value from normatively defining support for multiple JSON representations at this time...

If I could go back and fix DID Core I would, but since its frozen, I think its best that DID Web support the JSON representation that is a super set and only that JSON representation... which is application/did+json.. but since that representation will not be understood by any web server... we should allow application/json to be returned for any did web document... google and others also do this... messing with accept headers should probably not be added until there is a really good reason, and so far, I am not seeing one.

We have a path to allowing multiple representations, but we should not take that path, because it introduces lots of security issues and is not worth the complexity or attack surface.

Copy link
Contributor

@msporny msporny Nov 30, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

JSON-LD should be possible, but it should not be required for DID Web... and I don't think we get any value from having 2 JSON files that are potentially different... other than pain.

Then we have a really deep technical problem here (no machine-verifiable extensibility mechanism), with no technical solution being proposed. Digital Bazaar will (eventually) formally object to any such change to did:web -- I don't think you guys are thinking this through.

An analogy would be "We made this car simpler by removing the emergency brake and the complex power steering system." -- you did make it simpler, you also made it more dangerous.

The only other alternative suggestion I can think of is, "yeah, do application/did+json ONLY and make the use of "@context" a MUST". Those that want to process it can do so and those that don't... don't. At least in that case, we can tell which properties were meant to be used and which ones are superfluous/unknown. If we don't do that, you end up having to publish a JSON Schema file for did:web -- and at that point, you're just re-creating JSON-LD (but with something that's a one-off for this DID Method). Wrt. interop... we have no idea without either of those two solutions, and that is a huge security vulnerability that Digital Bazaar is not willing to expose themselves to.

The more I think about this, the more I think not allowing proper content negotiation is a terrible idea. I'm starting to sour on this PR given the direction that @OR13 and @mprorock seem to be proposing... and I have no idea what portions of it that @gribneau is trying to move towards. We'll need to discuss this.

Copy link
Contributor

@msporny msporny Nov 30, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

Upon re-reading @gribneau's comments, I tend to agree with him. @OR13 and @mprorock -- you guys seem to be trying to make this PR into something it's not. If you want to push your proposal, do it via a separate PR. Both of you seem to be arguing against content negotiation, which is going against Web Architecture (both at W3C and IETF).

Copy link
Contributor Author

@gribneau gribneau Nov 30, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

Streamlined.

See #47 (comment)

</pre>
<p>
In this scenario, it is probable that example.com has given user Bob control
Expand Down