#960: Controller Documents v1.0

Visit on Github.

Opened Jun 2, 2024

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).

Further details:

  • 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

Discussions

2024-08-26

Minutes

Brief conversation about this, but nothing concrete. (continued on slack)

2024-09-02

Minutes

Draft comment by @jyasskin

<blockquote>

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:

</blockquote>
2024-09-09

Minutes

Jeffrey: they replied to a couple aspects of it... they replied to the issue I raised on their repo... I can discuss with them, but should I take questions back to the TAG?

Hadley: fine with that... if you want TAG backup you're welcome to back to us...

Amy: +1 - yes i clicked through to their minutes... reviewing...

2024-09-16

Minutes

Discussion at https://github.com/w3c/controller-document/issues/94#issuecomment-2332584962

Jeffrey: some feedback from them... I'm waiting for the wg to talk about it...

Hadley: if we do decide to drop in on them we should do some coordination...

Peter: marks as pending external feedback.

2024-10-07

Minutes

no update let's discuss it at plenary

2024-10-14

Minutes

They've sent a bunch of PRs, and we (Jeffrey) need to review those.