Controller Documents v1.0

[msporny]

The Verifiable Credentials Working Group is requesting a TAG review of Controller Documents by the end of summer 2024 (ideally, sooner). Controller Documents are a generalization of DID Documents and some content from VC Data Integrity. All this to say, the TAG has reviewed most of this content before when it reviewed DID Core, and then again when it reviewed Verifiable Credential Data Integrity. The Working Group recently decided that it would rather have this content in a separate specification than embed it in DID Core or VC Data Integrity.

A Controller Document is a generalization of a DID Document that enables one to use more than just DIDs as identifiers. It also standardizes some data structures and algorithms that we were unable to standardize during the DID Core v1.0 work. Almost all of the normative content that exists in the specification was approved by the TAG before VC Data Integrity entered the Candidate Recommendation phase (so, a light review is probably all that is needed).

• Explainer:
  • DID Core Explainer
  • Data Integrity Explainer
  • Let us know if you would like us to write another explainer for this spec: The spec is basically just "DID Documents, but you can now use other types of URLs in them (like HTTPS-based ones)". The spec exists so we can establish spec text, separate from DID Core and Data Integrity, that we can then normatively reference from other specs in the VCWG that don't have anything to do with DIDs, like generalized public key discovery algorithms.
• Specification URLs:
  • Controller Document
• Tests:
  • Controller Documents are being tested via the VC Data Integrity test suites (when verifying digital signatures, cryptographic key material is fetched from Controller Documents).
  • VC Data Integrity Test Suites
• User research: Jobs for the Future Interoperability Results using VC Data Integrity
• Security and Privacy self-review: https://github.com/w3c/vc-data-integrity/issues/98
• GitHub repo (if you prefer feedback filed there):
  • https://github.com/w3c/controller-document/issues/
• Primary contacts (and their relationship to the specification):
  • Manu Sporny (@msporny), Editor, Digital Bazaar
  • Mike Jones (@selfissued), Editor, Independent
  • Brent Zundel (@brentzundel), VCWG Chair, Mesur.io
  • Ivan Herman (@iherman), VCWG Staff Contact, W3C
• Organization(s)/project(s) driving the specification: W3C Verifiable Credentials Working Group
• Key pieces of existing multi-stakeholder review or discussion of these specifications:
  • Inclusion of the work in the VCWG Charter
  • Jobs for the Future Interoperability Plugfest #2 using Controller Documents
• External status/issue trackers for these specification (publicly visible, e.g. Chrome Status):
  • https://github.com/w3c/controller-document/issues/

Further details:

• [x] I have reviewed the TAG's Web Platform Design Principles
• Relevant time constraints or deadlines: The VCWG is planning to take this specification to Candidate Recommendation in September 2024 (at W3C TPAC), reviews before that time frame (ideally, by the end of July 2024) would be ideal.
• The group where the work on this specification is currently being done: W3C Verifiable Credentials Working Group
• Major unresolved issues with or opposition to this specification:
  • None
• This work is being funded by: The members of the W3C VCWG that are actively participating in the development of these specifications including funding from the US Federal Government, the European Commission, and the Canadian Federal Government.

You should also know that...

• The TAG has reviewed and approved 90%+ of the content in the specification before once when it reviewed DID Core and then again when it reviewed Data Integrity.

We'd prefer the TAG provide feedback as:

☂️ open a single issue in our GitHub repo for the entire review

[brentzundel]

Howdy, just checking to see if there are any questions we might be able to answer for the reviewers and if there were an estimate for when we might be able to expect a response.

Most of the content for the document under review was pulled directly from VC JOSE COSE and VC Data Integrity, both of which were previously reviewed by TAG and are in Candidate Recommendation. We pulled some common language from both specs into a standalone specification so that it could be presented in a more logically consistent manner, but other than than have only made minimal changes.

[selfissued]

FYI, @msporny and I are editors of the specification, and both would be glad to answer any questions, as would @brentzundel, our working group chair.

[jyasskin]

We appreciate this effort to make the bag-of-keys functionality that Verifiable Credentials use more independent from the did: URL scheme. Beyond that, we're not confident that other systems will find much use in it, since the effort of profiling it is likely to be larger than the effort in defining a bespoke format. There is also a risk that defining a generic format will introduce security vulnerabilities into specific applications when libraries implement the generic format and fail to enforce the restrictions that those specific applications need. We've seen this in the past when generic JWT libraries allowed alg=none or symmetric keys in applications that were designed for asymmetric keys. While those specific flaws don't exist here, analogous ones might.

We were happy to see that this document doesn't try to define a format that can be interpreted as JSON and JSON-LD at the same time. Some of the discussion in issues has been worrying on that front — it sounds like some implementers might be intending to include @context properties, parse documents as JSON-LD using hash-pinned values for those @context URLs (which is better than not pinning them), and then interpret the result using an unspecified (though logical) mapping from URLs to the terms that this specification defines. We are concerned about such an implicit interoperability requirement that isn't captured in the format's specification, and we're concerned that attackers will find ways to exploit the complexity of JSON-LD context processing. We're also skeptical that JSON-LD provides benefits for a format designed for grouping cryptographic keys: interoperable extensibility can be achieved through IANA registries at least as well as through individually-owned URL prefixes. (We recognize that the DID WG sees registries as too-centralized, but we disagree.)

Some of us are concerned about the inclusion of multihash and multibase. We all think it's best to mandate that all implementations of this specification align on a single cryptographic digest algorithm and a single base encoding, to improve interoperability. We're split on whether it's a good idea to use the multihash and multibase formats to make those strings self-describing.

We don't see some security considerations that we were expecting to see:

• It seems risky, at least in some cases, to say "https://some.url/ defines the keys that can approve changes to this document" without pinning the content of https://some.url/ either by hash or signature, and we don't see any facility in this specification to do that pinning. Where would that be defined?

• If one controller document creates a "verification relationship" to "https://actor1.example/key1", can a hostile actor include a verification method in their controller document with "id": "https://actor1.example/key1" and cause their key to be trusted? https://www.w3.org/TR/2024/WD-controller-document-20240817/#retrieve-verification-method does say to fetch every verification method URL with no caching at all, but it seems unlikely that implementations will actually omit all caching.

[pchampin]

This was discussed during the did meeting on 2024-09-05: https://www.w3.org/2024/09/05-did-minutes.html#t04

[msporny]

The VCWG believes that we have addressed all of the TAG's feedback provided during W3C TPAC 2024.

PRs have been merged and all issues have been closed (after requesting confirmation that we've addressed the concerns that TAG raised). The tracking issue for all of TAGs requests and PRs raised can be found here:

https://github.com/w3c/controller-document/issues/94#issuecomment-2395604054

If TAG believes that we've addressed all of the issues raised, please confirm and close this issue (as it's still showing as open on our issue tracker and we're trying to go to Candidate Recommendation and need a confirmation that we addressed all issues TAG raised).

/cc @brentzundel @iherman