W3C home > Mailing lists > Public > public-credentials@w3.org > December 2018

DIDs, proof purposes, and verification methods

From: Dave Longley <dlongley@digitalbazaar.com>
Date: Sun, 30 Dec 2018 21:02:19 -0500
To: W3C Credentials Community Group <public-credentials@w3.org>
Message-ID: <0aa23d2a-082f-dfae-37be-2306d0826a65@digitalbazaar.com>
TL;DR: I think we should:

1. Rename "cryptographic suites" to "verification methods".

2. Consider a public key a "verification method" rather than needing to
always wrap them in a "cryptographic suite".

3. In Linked Data Proofs, replace "creator" with "verificationMethod"
but support "creator" for backwards compatibility.

4. Require a "proofPurpose" for every Linked Data Proof (and I recommend
the same for other proof schemes). We should also use its value as a
relation in a DID document to link a DID with an authorized verification
method for a particular proof purpose.

5. Establish "assertionMethod" as a common proof purpose for proofs that
are used as a method for making an assertion, whether that
assertion be in a VC or via some social media post/message (where Linked
Data Signatures are used in concert with ActivityPub/activity streams
posts and messages).

6. Make the following terms in the DID JSON-LD @context map thusly:

"authentication" => "<vocab>#authenticationMethod"
"assertionMethod" => "<vocab>#assertionMethod"
"capabilityInvocation" => "<vocab>#capabilityInvocationMethod"
"capabilityDelegation" => "<vocab>#capabilityDelegationMethod"
"contractAgreement" => "<vocab>#contractAgreementMethod"

(Change "xSuite" => "xMethod").


We've spoken in the community before about "cryptographic suites". This
term, at least within the context of our conversation, was meant to
refer to some collection of parameters used to verify a (cryptographic)

I think this terminology is problematic for a few reasons such as
confusion with existing terms of art and a restriction to cryptographic
proofs when we have also discussed supporting proofs that do not
necessarily require the use of cryptography. Implementation experience
both with DID documents and with digital signature and object capability
libraries has also led me to believe that we should adopt slightly
different terminology.

However, rather than go over all the potential problems, I'd like to
just introduce slightly different terminology that I believe is more
accurate and see if there is buy-in from the community. I believe much
of the narrative I provide below and the new terminology already fits in
with Linked Data Proofs and the DID document model we have. This means
that there would be very few changes needed (summarized above).

So, to lay out the case for the terminology I think we should adopt, I
will mention some of the basic ecosystem requirements we're trying to
fulfill in a decentralized and interoperable manner. Then I'll talk
through a concrete example using that terminology.

We would like to enable entities to:

1. Make statements that can be shared without loss of trust because
their authorship can be verified by a third party (e.g. VCs, social
media posts, so on).

2. Authenticate as the controller of some DID to some domain.

3. Delegate capabilities to others that only they can invoke; delegation
can be verified by another party.

4. Invoke capabilities where the invocation can be verified by another

5. Agree to contracts where the agreement can be verified by another party.

There is a common generic thread for each of these requirements:
Entities need a method by which they can demonstrate a specific intent
that can be independently verified.

I believe this description can be understood as a "proof". I think we
can further unpack this to assign terminology to the attributes of a
"proof" that are necessary to give them utility:

1. "type": The specific type of proof, for example, an
"Ed25519Signature2018" type indicates that the proof includes a digital
signature produced by an ed25519 cryptographic key (amongst other things).

2. "proof purpose": The reason why an entity created a proof, i.e. they
were using the proof as a method for declaring what *specific* intent?

3. "verification method": A set of parameters required to independently
verify the proof. This would include the type of verification method
and, for example, public key material.

4. "proof value" or other proof-specific attributes: These would include
any attributes that are specific to the type of proof, such as "jws",
for a cryptographic proof that uses the JWS specification.

The necessity of a proof type and value seem relatively straightforward.

A proof that describes its purpose helps prevent it from being misused
for some other purpose. This is something that has been missing from
earlier revisions of Linked Data Signatures that we've started to
support -- and I recommend every Linked Data Proof (and other proof
methods) has one of these.

A proof that links to its verification method enables discovery of that
method (and its associated parameters) -- but a verifier must be able to
determine that the entity authorized the use of that verification method
for its used purpose.

This last bit means that a verifier must not only confirm that the proof
was created by someone who controls the verification method but that the
verification method was authorized by that controller to be used for the
proof's purpose. This approach has advantages, such as encouraging
entities to separate their verification methods into categories for
specific use, thereby reducing ambient authority.

So, a verification method should indicate who its "controller" is, i.e.
the entity that controls the method and uses it for some purpose. We
already intend to use this terminology to replace "owner" via a PR here:


This isn't enough of course, as a verification method description can
declare anything; we also need the description of the "controller"
itself to declare that the verification method at hand has been
authorized for the intended proof purpose. We have already structured
our DID documents this way -- and that may be more obvious via a
concrete example.

Let's use "authentication" as the reason that an entity has created a
proof, i.e. its "proof purpose". In other words:

Suppose an entity "did:example:123" has created a proof for the purpose
of "authentication" that can be verified via the method

  /* some document the proof is attached to */
  "proof": {
    "type": "Ed25519Signature2018",
    "verificationMethod": "did:example:123#some-key",
    "proofPurpose": "authentication",
    "jws": "3242343..234234234d3232"

Here this "proof" looks just like a typical Linked Data Signature proof,
except that it has a specific "proofPurpose" of "authentication" and
that the field "creator" is replaced with "verificationMethod". I think
using this new terminology instead of "creator" would help alleviate
some confusion. Wrt to Linked Data Signatures, I recommend we always
include a "proofPurpose" and use the "verificationMethod" term going
forward (but support "creator" for backwards compatibility). In any
case, a verifier should dereference the verification method to get its

  "id": "did:example:123#some-key",
  "type": "Ed25519VerificationKey2018",
  "controller": "did:example:123",
  "publicKeyBase58": "z2847623...423"

Note: We can see from this that an instance of a
"Ed25519VerificationKey2018" (a public key description), is a
"verification method". This eliminates the need for an additional
encapsulating "cryptographic suite" as we have previously discussed. It
also allows us to replace the "cryptographic suite" terminology with
"verification method". I think this terminology is more generic and
appropriate for its use. This approach supports other verification
methods such as some sort of biometric template/parameters or a third
party service that must be queried.

From here, a verifier can make sure the verification method is
appropriate for the type of proof and it can verify the digital
signature in the proof. Then it can then dereference the "controller" to
find a DID document. (Note: in the case of DID documents, the common
case will be that keys will be stored in the DID documents themselves,
so the "dereferencing" of the controller may actually be merely a check
against the `id` of the DID document).

Here is an example DID document for the DID "did:example:123":

  "@context": "https://w3id.org/did/v1",
  "id": "did:example:123",
  "authentication": [{
    "id": "did:example:123#some-key",
    "type": "Ed25519VerificationKey2018",
    "controller": "did:example:123",
    "publicKeyBase58": "z2847623...423"

Here we have a relationship between the entity identified by the DID and
the verification method that can be represented as a triple:

<did:example:123> <authentication> <did:example:123#some-key>

This statement is a declaration that the entity uses the public key as
an authentication method. Given that this statement comes from the
entity's description itself, it is an authoritative statement
authorizing the use of that key as a verification method for proofs for
the purpose of authentication.

This ties everything together -- and it works for all of the above more
specific requirements:

A proof created to prove that "entity E asserted something" has a proof
purpose of "assertionMethod" and E's DID document has a relation of
"assertionMethod" with the proof's verification method.

A proof created to prove that "entity E authenticated" has a proof
purpose of "authentication" and E's DID document has a relation of
"authentication" with the proof's verification method.

A proof created to prove that "entity E invoked a capability" has a
proof purpose of "capabilityInvocation" and E's DID document has a
relation of "capabilityInvocation" with the proof's verification method.

A proof created to prove that "entity E delegated a capability" has a
proof purpose of "capabilityDelegation" and E's DID document has a
relation of "capabilityDelegation" with the proof's verification method.

A proof created as a method to prove that "entity E agrees to a
contract" has a proof purpose of "contractAgreement" and E's DID
document has a relation of "contractAgreement" with the proof's
verification method.

The changes needed to adopt this new terminology are summarized at the
top of this email. As an open question to the community, what do you
think of this direction? If there are no objections to these changes I
would move to have us make whatever spec and JSON-LD context changes are
necessary sooner rather than later.

Dave Longley
Digital Bazaar, Inc.
Received on Monday, 31 December 2018 02:02:54 UTC

This archive was generated by hypermail 2.3.1 : Monday, 31 December 2018 02:02:54 UTC