From 52a4209dfaeb6326227bc1e20fe321395494ab5c Mon Sep 17 00:00:00 2001 From: Amy Guy Date: Mon, 8 Jun 2020 04:12:54 +0200 Subject: [PATCH] Add verificationMethod as a DID document property. * Fixes #283. Also removes undefined terms that are verification relationships - which fixes #272 - replacing them with links to the DID Spec Registries. * Change MUSTs to SHOULDs for terms in Registries * Move verification method text from terms to section; add verification relationship dfn * Fix references and wording. Co-authored-by: Manu Sporny --- index.html | 141 ++++++++++++++++++++++++++++++++++++++++------------- terms.html | 16 +++--- 2 files changed, 116 insertions(+), 41 deletions(-) diff --git a/index.html b/index.html index 56217781..e6114969 100644 --- a/index.html +++ b/index.html @@ -1294,37 +1294,105 @@

DID Subject

-

Public Keys

+

Verification Methods

+

+A DID document can express verification methods, such as +cryptographic keys, which can be used to authenticate or authorize interactions +with the DID subject or associated parties. The information expressed +often includes globally unambiguous identifiers and public key material, which +can be used to verify digital signatures. For example, a public key can be +used as a verification method with respect to a digital signature; in such +usage, it verifies that the signer possessed the associated private key. +

+

+Verification methods might take many parameters. An example of this is a set +of five cryptographic keys from which any three are required to contribute to +a threshold signature. Methods need not be cryptographic. An example of this +might be the contact information for a biometric service provider that compares +a purported DID controller against a candidate biometric vector. +

-A DID document can express cryptographic keys and other verification -methods, which can be used to authenticate or authorize interactions with the -DID subject or associated parties. The information expressed often -includes globally unambiguous identifiers and public key material, which can be -used to verify digital signatures. Other information can be expressed, such as -attributes that enable one to determine whether it is a -hardware-backed cryptographic key. +A DID document MAY include a verificationMethod property.

+
+
verificationMethod
+
+If a DID document includes a verificationMethod property, +the value of the property MUST be an array of verification method objects. +Each verification method object MUST have the id, type, +controller, and specific verification method properties. The +verification method objects MAY include additional properties. +
+
+

-Regarding cryptographic key material, public keys can be included in a -DID document using, for example, the publicKey or -authentication properties, depending on what they are to be used -for. Each public key has an identifier (id) of its own, a -type, and a controller, as well as other properties -that depend on the type of key it is. +The value of the id property MUST be a URI. The array of +verification methods MUST NOT contain multiple entries with the same +id. If the array of verification methods contains multiple +entries with the same id, a DID document processor MUST +produce an error.

-This specification strives to limit the number of formats for expressing public -key material in a DID Document to the fewest possible, to increase the -likelihood of interoperability. The fewer formats that implementers have to -implement, the more likely it will be that they will support all of them. This -approach attempts to strike a delicate balance between ease of implementation -and supporting formats that have historically had broad deployment. The specific -types of key formats that are supported in this specification are listed below. +The value of the type property MUST be exactly one verification +method type. In order to maximize global interoperability, the +verification method type SHOULD be registered in the +[[DID-SPEC-REGISTRIES]]. +

+ +

+The value of the controller property, MUST be a valid DID. +

+ +

+In order to maximize global interoperability, the verification method properties +SHOULD be registered in the [[DID-SPEC-REGISTRIES]].

+ 
+{
+  "@context": ["https://www.w3.org/ns/did/v1", "https://w3id.org/security/v1"],
+  "id": "did:example:123456789abcdefghi",
+  ...
+  "verificationMethod": [{
+    "id": ...,
+    "type": ...,
+    "controller": ...,
+    ...
+  ]}
+}
+
+ +
+

Verification relationships

+ +

+A verification relationship expresses the relationship between the +DID subject and a verification method. +

+

+A DID document MAY include a property expressing a specific +verification relationship. In order to maximize global interoperability, +the property SHOULD be registered in [[DID-SPEC-REGISTRIES]]. +

+

+A DID controller MUST be explicit about the verification +relationship between the DID subject and the verification method. +Verification methods that are not associated with a particular +verification relationship MUST NOT be used for that verification +relationship. See Section for a more +detailed example of a verification relationship. +

+ +
+ +
+ +
+

Public Keys

+

A public key is a verification method. Public keys are used for digital signatures, encryption and other cryptographic @@ -1336,20 +1404,21 @@

Public Keys

), which can be defined by DID method specifications.

- -

-A public key is just one type of verification method. A DID -document expresses the relationship between the DID subject and a -verification method using a verification relationship. -Examples of verification relationships include: -authentication, capabilityInvocation, -capabilityDelegation, keyAgreement, and -assertionMethod. A DID controller MUST be explicit about the -verification relationship between the DID subject and the verification -method. Verification methods that are not associated with a -particular verification relationship MUST NOT be used for that -verification relationship. See Section -for a more detailed example of a verification relationship. +

+Public keys can be included in a DID document using the +publicKey or authentication properties, depending on +what they are to be used for. Each public key has an identifier (id) +of its own, a type, and a controller, as well as +other properties that depend on the type of key it is. +

+

+This specification strives to limit the number of formats for expressing public +key material in a DID Document to the fewest possible, to increase the +likelihood of interoperability. The fewer formats that implementers have to +implement, the more likely it will be that they will support all of them. This +approach attempts to strike a delicate balance between ease of implementation +and supporting formats that have historically had broad deployment. The specific +types of key formats that are supported in this specification are listed below.

@@ -1645,6 +1714,8 @@

Authentication

A DID document MAY include an authentication property. +The authentication property is an example of a verification +relationship.

diff --git a/terms.html b/terms.html index 0c371b70..d5c6e5ae 100644 --- a/terms.html +++ b/terms.html @@ -184,7 +184,7 @@ process are defined in . -
DID URL dereferencer
+
DID URL dereferencer
A software and/or hardware system that is capable of executing the DID URL dereferencing @@ -287,14 +287,18 @@ is thus another type of verification method, even though descriptions of the process might not use the words "verification" and "proof."

+
+ +
verification relationship
+ +

-Verification methods might take many parameters. An example of this is a set of five -cryptographic keys from which any three are required to contribute to a threshold signature. Methods -need not be cryptographic. An example of this might be the contact information for a -biometric service provider that compares a purported DID controller against a candidate -biometric vector. +A verification relationship expresses the relationship between the DID +subject and a verification method. An example of a verification +relationship is .

+
Universally Unique Identifier (UUID)