Copyright © 2024 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.
A controller document is a set of data that specifies one or more relationships between a controller and a set of data, such as a set of public cryptographic keys.
This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This document was published by the Verifiable Credentials Working Group as a Working Draft using the Recommendation track.
Publication as a Working Draft does not imply endorsement by W3C and its Members.
This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 03 November 2023 W3C Process Document.
This section is non-normative.
A controller document is a set of data that specifies one or more relationships between a controller and a set of data, such as a set of public cryptographic keys. The controller document SHOULD contain verification relationships that explicitly permit the use of certain verification methods for specific purposes.
It is expected that other specifications using this specification will profile the features that it defines, requiring and/or recommending the use of some and prohibiting and/or deprecating the use of others.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
A conforming controller document is any concrete expression of the data model that follows the relevant normative requirements in Sections 2. Data Model and 4. Contexts and Vocabularies.
A conforming verification method is any concrete expression of the data model that follows the relevant normative requirements in Sections 2.2 Verification Methods and 4. Contexts and Vocabularies.
A conforming document is either a conforming controller document, or a conforming verification method.
A conforming processor is any algorithm realized as software and/or hardware that generates and/or consumes a conforming document according to the relevant normative statements in Section 3. Algorithms. Conforming processors MUST produce errors when non-conforming documents are consumed.
This section is non-normative.
This section defines the terms used in this specification. A link to the relevant definition is included whenever one of these terms appears in this specification.
id
property in a controller document.
Anything can be a subject: person, group, organization, physical thing, digital
thing, logical thing, etc.
A set of parameters that can be used together with a process to independently verify a proof. For example, a cryptographic public key can be used as a verification method with respect to a digital signature; in such use, it verifies that the signer possessed the associated cryptographic private key.
"Verification" and "proof" in this definition are intended to apply broadly. For example, a cryptographic public key might be used during Diffie-Hellman key exchange to negotiate a shared symmetric key for encryption. This guarantees the integrity of the key agreement process. It is thus another type of verification method, even though descriptions of the process might not use the words "verification" or "proof."
An expression of the relationship between a subject and a verification method. One example of a verification relationship is 2.3.1 Authentication.
A controller document is a set of data that specifies one or more relationships between a controller and a set of data, such as a set of public cryptographic keys. The controller document SHOULD contain verification relationships that explicitly permit the use of certain verification methods for specific purposes.
The property names id
, type
, and controller
can be present in map of
different types with possible differences in constraints.
The following sections define the properties in a controller document, including whether these properties are required or optional. These properties describe relationships between the subject and the value of the property.
The following tables contain informative references for the core properties defined by this specification, with expected values, and whether or not they are required. The property names in the tables are linked to the normative definitions and more detailed descriptions of each property.
Property | Required? | Value constraints |
---|---|---|
id |
yes | A string that conforms to the URL syntax defined in Section 2.1.1 Subjects. |
alsoKnownAs |
no | A set of strings, each of which conforms to the URL syntax defined in the URL Standard as defined in Section 2.1.3 Also Known As. |
controller |
no | A string or a set of strings, each of which conforms to the URL syntax defined in the URL Standard as defined in Section 2.1.2 Controllers. |
verificationMethod |
no | A set of verification method maps, each of which conforms to the rules in Section 2.2 Verification Methods. |
authentication |
no | A set of verification method maps, each of which conforms to the rules in Section 2.3.1 Authentication; or a a set of strings, each of which conforms to the URL syntax defined in the URL Standard. |
assertionMethod |
no | A set of verification method maps, each of which conforms to the rules in Section 2.3.2 Assertion; or a a set of strings, each of which conforms to the URL syntax defined in the URL Standard. |
keyAgreement |
no | A set of verification method maps, each of which conforms to the rules in Section 2.3.3 Key Agreement; or a a set of strings, each of which conforms to the URL syntax defined in the URL Standard. |
capabilityInvocation |
no | A set of verification method maps, each of which conforms to the rules in Section 2.3.4 Capability Invocation; or a a set of strings, each of which conforms to the URL syntax defined in the URL Standard. |
capabilityDelegation |
no | A set of verification method maps, each of which conforms to the rules in Section 2.3.5 Capability Delegation; or a a set of strings, each of which conforms to the URL syntax defined in the URL Standard. |
The identifier for a particular subject is expressed using the
id
property in the controller document.
id
MUST be a string
that conforms to the rules in the URL Standard.
A controller document MUST contain an id
value in the
root map.
{ "id": "https://controller.example/123" }
The id
property only denotes the identifier of the subject when it is
present in the topmost
map of the controller document.
A controller is an entity that is authorized to make changes to a controller document.
controller
property is OPTIONAL. If present, its value MUST
be a string or a set of strings, each of which conforms to the rules in
the URL Standard. The corresponding controller document(s) SHOULD
contain verification relationships that explicitly permit the use of
certain verification methods for specific purposes. If the controller
property is not present, the value expressed by the id
property MUST be
treated as if it were also set as the value of the controller
property.
When a controller
property is present in a controller document, its
value expresses one or more identifiers. Any verification methods contained
in the controller documents for those identifiers SHOULD
be accepted as authoritative, such that proofs that satisfy those
verification methods are considered equivalent to proofs provided
by the subject.
{ "@context": "https://www.w3.org/ns/controller/v1", "id": "https://controller1.example/123", "controller": "https://controllerB.example/abc", }
Note that authorization provided by the value of controller
is
separate from authentication as described in Section 2.3.1 Authentication.
This is particularly important for key recovery in the cases of cryptographic key
loss, where the subject no longer has access to their keys, or cryptographic
key compromise, where the controller's trusted third parties need to
override malicious activity by an attacker. See 5. Security Considerations
for information related to threat models and attack vectors.
A subject can have multiple identifiers that are used for different purposes
or at different times. The assertion that two or more identifiers (or other types
of URI) refer to the same subject can be made using the
alsoKnownAs
property.
alsoKnownAs
property is OPTIONAL. If present, its value MUST
be a set where each item in the
set is a URI conforming to [RFC3986].
Applications might choose to consider two identifiers related by alsoKnownAs
to be equivalent if the alsoKnownAs
relationship expressed in the
controller document of one subject is also expressed in the reverse direction
(i.e., reciprocated) in the controller document of the other subject. It is
best practice not to consider them
equivalent in the absence of this reciprocating relationship. In other words,
the presence of an alsoKnownAs
assertion does not prove that this assertion
is true. Therefore, it is strongly advised that a requesting party obtain
independent verification of an alsoKnownAs
assertion.
Given that the subject might use different identifiers for different purposes, such as enhanced privacy protection, an expectation of strong equivalence between the two identifiers, or taking action to merge the information from the two corresponding controller documents, is not necessarily appropriate, even with a reciprocal relationship.
A controller document can express verification methods, such as cryptographic public keys, which can be used to authenticate or authorize interactions with the controller or associated parties. For example, a cryptographic public key can be used as a verification method with respect to a digital signature; in such use, it verifies that the signer could use the associated cryptographic 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 cryptographic threshold signature.
The verificationMethod
property is OPTIONAL. If present, the value
MUST be a set of verification
methods, where each verification method is expressed using a map. The verification method map MUST include the id
,
type
, controller
, and specific verification material
properties that are determined by the value of type
and are defined
in 2.2.1 Verification Material. A verification method MAY
include additional properties.
The value of the id
property for a verification method
MUST be a string that
conforms to the [URL] syntax.
type
property MUST be a string that references exactly one verification
method type.
controller
property MUST be a string that conforms to the [URL] syntax.
revoked
property is OPTIONAL.
If present, it MUST be an [XMLSCHEMA11-2]
dateTimeStamp
string specifying when the verification method
SHOULD cease to be used. Once the value is set, it is not expected to be
updated, and systems depending on the value are expected to not verify any
proofs associated with the verification method at or after the time of
revocation.
{ "@context": [ "https://www.w3.org/ns/controller/v1", "https://www.w3.org/ns/credentials/v2", "https://w3id.org/security/jwk/v1", "https://w3id.org/security/data-integrity/v2" ] "id": "https://controller.example/123456789abcdefghi", ... "verificationMethod": [{ "id": ..., "type": ..., "controller": ..., "publicKeyJwk": ... }, { "id": ..., "type": ..., "controller": ..., "publicKeyMultibase": ... }] }
The semantics of the controller
property are the same when the
subject of the relationship is the controller document as when the subject of
the relationship is a verification method, such as a cryptographic public
key. Since a key can't control itself, and the key controller cannot be inferred
from the controller document, it is necessary to explicitly express the identity
of the controller of the key. The difference is that the value of
controller
for a verification method is not
necessarily a controller. Controllers are expressed
using the controller
property at the highest level of the
controller document.
Verification material is any information that is used by a process that applies
a verification method. The type
of a verification method is
expected to be used to determine its compatibility with such processes. Examples
of verification methods include JsonWebKey
and Multikey
.
A cryptographic suite specification is responsible for specifying the
verification method type
and its associated verification material
format. For examples, see
Securing Verifiable Credentials using JOSE and COSE,
the Data Integrity ECDSA
Cryptosuites and
the Data Integrity EdDSA Cryptosuites.
To increase the likelihood of interoperable implementations, this specification limits the number of formats for expressing verification material in a controller document. 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 easing implementation and providing support for formats that have historically had broad deployment.
A verification method MUST NOT contain multiple verification material
properties for the same material. For example, expressing key material in a
verification method using both publicKeyJwk
and
publicKeyMultibase
at the same time is prohibited.
Implementations MAY convert keys between formats as desired for operational purposes or to interface with cryptographic libraries. As an internal implementation detail, such conversion MUST NOT affect the external representation of key material.
An example of a controller document containing verification methods using both properties above is shown below.
{ "@context": [ "https://www.w3.org/ns/controller/v1", "https://www.w3.org/ns/credentials/v2", "https://w3id.org/security/jwk/v1", "https://w3id.org/security/multikey/v1" ] "id": "https://controller.example/123456789abcdefghi", ... "verificationMethod": [{ "id": "https://controller.example/123#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A", "type": "JsonWebKey", // external (property value) "controller": "https://controller.example/123", "publicKeyJwk": { "crv": "Ed25519", // external (property name) "x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOyPVQaO3FxVeQ", // external (property name) "kty": "OKP", // external (property name) "kid": "_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A" // external (property name) } }, { "id": "https://controller.example/123456789abcdefghi#keys-1", "type": "Multikey", // external (property value) "controller": "did:example:pqrstuvwxyz0987654321", "publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu" }], ... }
The Multikey data model is a specific type of verification method that encodes key types into a single binary stream that is then encoded as a Multibase value as described in Section 2.4 Multibase.
When specifying a Multikey
, the object takes the following form:
type
property MUST contain the string Multikey
.
publicKeyMultibase
property is OPTIONAL. If present, its value MUST be a
Multibase encoded value as described in Section 2.4 Multibase.
secretKeyMultibase
property is OPTIONAL. If present, its value MUST be a
Multibase encoded value as described in Section 2.4 Multibase.
The example below expresses an Ed25519 public key using the format defined above:
{ "@context": ["https://w3id.org/security/multikey/v1"], "id": "https://controller.example/123456789abcdefghi#keys-1", "type": "Multikey", "controller": "https://controller.example/123456789abcdefghi", "publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu" }
The public key values are expressed using the rules in the table below:
Key type | Description |
---|---|
ECDSA 256-bit public key |
The Multikey encoding of a P-256 public key MUST start with the two-byte prefix
0x8024 (the varint expression of 0x1200 ) followed by the 33-byte compressed
public key data. The resulting 35-byte value MUST then be encoded using the
base-58-btc alphabet, according to Section 2.4 Multibase, and then
prepended with the base-58-btc Multibase header (z ).
|
ECDSA 384-bit public key |
The encoding of a P-384 public key MUST start with the two-byte prefix 0x8124
(the varint expression of 0x1201 ) followed by the 49-byte compressed public
key data. The resulting 51-byte value is then encoded using the base-58-btc
alphabet, according to Section 2.4 Multibase, and then prepended with the
base-58-btc Multibase header (z ).
|
Ed25519 256-bit public key |
The encoding of an Ed25519 public key MUST start with the two-byte prefix
0xed01 (the varint expression of 0xed ), followed by the 32-byte public key
data. The resulting 34-byte value MUST then be encoded using the base-58-btc
alphabet, according to Section 2.4 Multibase, and then prepended with the
base-58-btc Multibase header (z ).
|
BLS12-381 381-bit public key |
The encoding of an BLS12-381 public key in the G2 group MUST start with
the two-byte prefix 0xeb01 (the varint expression of 0xeb ), followed
by the 96-byte compressed public key data. The resulting 98-byte value MUST
then be encoded using the base-58-btc alphabet, according to Section
2.4 Multibase, and then prepended with the base-58-btc Multibase header
(z ).
|
The secret key values are expressed using the rules in the table below:
Key type | Description |
---|---|
ECDSA 256-bit secret key |
The Multikey encoding of a P-256 secret key MUST start with the two-byte prefix
0x8626 (the varint expression of 0x1306 ) followed by the 32-byte
secret key data. The resulting 34-byte value MUST then be encoded using the
base-58-btc alphabet, according to Section 2.4 Multibase, and then
prepended with the base-58-btc Multibase header (z ).
|
ECDSA 384-bit secret key |
The encoding of a P-384 secret key MUST start with the two-byte prefix 0x8726
(the varint expression of 0x1307 ) followed by the 48-byte secret
key data. The resulting 50-byte value is then encoded using the base-58-btc
alphabet, according to Section 2.4 Multibase, and then prepended with the
base-58-btc Multibase header (z ).
|
Ed25519 256-bit secret key |
The encoding of an Ed25519 secret key MUST start with the two-byte prefix
0x8026 (the varint expression of 0x1300 ), followed by the 32-byte secret key
data. The resulting 34-byte value MUST then be encoded using the base-58-btc
alphabet, according to Section 2.4 Multibase, and then prepended with the
base-58-btc Multibase header (z ).
|
BLS12-381 381-bit secret key |
The encoding of an BLS12-381 secret key in the G2 group MUST start with
the two-byte prefix 0x8030 (the varint expression of 0x130a ), followed
by the 96-byte compressed public key data. The resulting 98-byte value MUST
then be encoded using the base-58-btc alphabet, according to Section
2.4 Multibase, and then prepended with the base-58-btc Multibase header
(z ).
|
Developers are advised to not accidentally publish a representation of a secret key. Implementations that adhere to this specification will raise errors in the event of a Multikey header value that is not in the public key header table above, or when reading a Multikey value that is expected to be a public key, such as one published in a controller document, that does not start with a known public key header.
When defining values for use with publicKeyMultibase
and secretKeyMultibase
,
specification authors MAY define additional header values for other key types in
other specifications and MUST NOT define alternate encodings for key types
already defined by this specification.
The JSON Web Key (JWK) data model is a specific type of verification method that uses the JWK specification [RFC7517] to encode key types into a set of parameters.
When specifing a JsonWebKey
, the object takes the following form:
type
property MUST contain the string JsonWebKey
.
The publicKeyJwk
property is OPTIONAL. If present, its value MUST
be a map representing a JSON Web Key that
conforms to [RFC7517]. The map MUST NOT
include any members of the private information class, such as d
, as described
in the JWK
Registration Template. It is RECOMMENDED that verification methods that use
JWKs [RFC7517] to represent their public keys use the value of kid
as
their fragment identifier. It is RECOMMENDED that JWK kid
values are set to
the public key fingerprint [RFC7638]. See the first key in
Example 4 for an example of a
public key with a compound key identifier.
As specified in Section 4.4 of the JWK specification,
the OPTIONAL alg
property identifies the algorithm intended for use with the public key,
and SHOULD be included to prevent security issues that can arise when using the same
key with multiple algorithms. As specified in
Section 6.2.1.1 of the JWA specification, describing a key using an elliptic curve,
the REQUIRED crv
property is used to identify the particular curve type of the public key.
As specified in Section 4.1.4 of the JWS specification,
the OPTIONAL kid
property is a hint used to help discover the key; if present, the kid
value SHOULD
match, or be included in, the id
property of the encapsulating JsonWebKey
object,
as part of the path, query, or fragment of the URL.
secretKeyJwk
property is OPTIONAL. If present, its value MUST be a map representing a JSON Web Key that conforms
to [RFC7517].
It MUST NOT be used if the data structure containing it is public or may be revealed to parties other than the legitimate holders of the secret key.
An example of an object that conforms to JsonWebKey
is provided below:
{ "id": "https://controller.example/123456789abcdefghi#key-1", "type": "JsonWebKey", "controller": "https://controller.example/123456789abcdefghi", "publicKeyJwk": { "kid": "key-1", "kty": "EC", "crv": "P-384", "alg": "ES384", "x": "1F14JSzKbwxO-Heqew5HzEt-0NZXAjCu8w-RiuV8_9tMiXrSZdjsWqi4y86OFb5d", "y": "dnd8yoq-NOJcBuEYgdVVMmSxonXg-DU90d7C4uPWb_Lkd4WIQQEH0DyeC2KUDMIU" } }
In the example above, the publicKeyJwk
value contains the JSON Web Key.
The kty
property encodes the key type of "OKP", which means
"Octet string key pairs". The alg
property identifies the algorithm intended
for use with the public key, which in this case is ES384
. The crv
property identifies
the particular curve type of the public key, P-384
. The x
property specifies
the point on the P-384 curve that is associated with the public key.
The publicKeyJwk
property MUST NOT contain any property marked as
"Private" or "Secret" in any registry contained in the JOSE Registries [JOSE-REGISTRIES], including "d".
The JSON Web Key data model is also capable of encoding secret keys, sometimes referred to as private keys.
{ "id": "https://controller.example/123456789abcdefghi#key-1", "type": "JsonWebKey", "controller": "https://controller.example/123456789abcdefghi", "secretKeyJwk": { "kty": "EC", "crv": "P-384", "alg": "ES384", "d": "fGwges0SX1mj4eZamUCL4qtZijy9uT15fI4gKTuRvre4Kkoju2SHM4rlFOeKVraH", "x": "1F14JSzKbwxO-Heqew5HzEt-0NZXAjCu8w-RiuV8_9tMiXrSZdjsWqi4y86OFb5d", "y": "dnd8yoq-NOJcBuEYgdVVMmSxonXg-DU90d7C4uPWb_Lkd4WIQQEH0DyeC2KUDMIU" } }
The private key example above is almost identical to the previous example of the
public key, except that the information is stored in the secretKeyJwk
property
(rather than the publicKeyJwk
), and the private key value is encoded in the d
property thereof (alongside the x
property, which still specifies the point on
the Ed25519 curve that is associated with the public key).
Verification methods can be embedded in or referenced from properties associated with various verification relationships as described in 2.3 Verification Relationships. Referencing verification methods allows them to be used by more than one verification relationship.
If the value of a verification method property is a map, the verification method has been
embedded and its properties can be accessed directly. However, if the value is a
URL string, the verification method has
been included by reference and its properties will need to be retrieved from
elsewhere in the controller document or from another controller document. This
is done by dereferencing the URL and searching the resulting resource for a
verification method map with an
id
property whose value matches the URL.
{ ... "authentication": [ // this key is referenced and might be used by // more than one verification relationship "https://controller.example/123456789abcdefghi#keys-1", // this key is embedded and may *only* be used for authentication { "id": "https://controller.example/123456789abcdefghi#keys-2", "type": "Multikey", // external (property value) "controller": "https://controller.example/123456789abcdefghi", "publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu" } ], ... }
A verification relationship expresses the relationship between the controller and a verification method.
Different verification relationships enable the associated verification methods to be used for different purposes. It is up to a verifier to ascertain the validity of a verification attempt by checking that the verification method used is contained in the appropriate verification relationship property of the controller document.
The verification relationship between the controller and the
verification method is explicit in the controller document.
Verification methods that are not associated with a particular
verification relationship cannot be used for that verification relationship. For example, a verification method in the value of
the [=authentication=]
property cannot be used to engage in
key agreement protocols with the controller — the value of the
`keyAgreement` property needs to be used
for that.
The controller document does not express revoked keys using a verification relationship. If a referenced verification method is not in the latest controller document used to dereference it, then that verification method is considered invalid or revoked.
The following sections define several useful verification relationships. A controller document MAY include any of these, or other properties, to express a specific verification relationship. To maximize global interoperability, any such properties used SHOULD be registered in the VC Specifications Directory.
The authentication
verification relationship is used to
specify how the controller is expected to be authenticated, for
purposes such as logging into a website or engaging in any sort of
challenge-response protocol.
authentication
property is OPTIONAL. If present, its
value MUST be a set of one or more
verification methods. Each verification method MAY be embedded or
referenced.
{ "@context": [ "https://www.w3.org/ns/controller/v1", "https://www.w3.org/ns/credentials/v2", "https://w3id.org/security/multikey/v1" ], "id": "https://controller.example/123456789abcdefghi", ... "authentication": [ // this method can be used to authenticate as did:...fghi "https://controller.example/123456789abcdefghi#keys-1", // this method is *only* approved for authentication, it may not // be used for any other proof purpose, so its full description is // embedded here rather than using only a reference { "id": "https://controller.example/123456789abcdefghi#keys-2", "type": "JsonWebKey", "controller": "https://controller.example/123456789abcdefghi", "publicKeyJwk": { "crv": "Ed25519", "x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOyPVQaO3FxVeQ", "kty": "OKP", "kid": "_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A" } }, { "id": "https://controller.example/123456789abcdefghi#keys-3", "type": "Multikey", "controller": "https://controller.example/123456789abcdefghi", "publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu" } ], ... }
If authentication is established, it is up to the application to decide what to do with that information.
This is useful to any authentication verifier that needs to check to
see if an entity that is attempting to authenticate is, in fact,
presenting a valid proof of authentication. When a verifier receives
some data (in some protocol-specific format) that contains a proof that was made
for the purpose of "authentication", and that says that an entity is identified
by the id
, then that verifier checks to ensure that the proof can be
verified using a verification method (e.g., public key) listed
under authentication
in the controller document.
Note that the verification method indicated by the
authentication
property of a controller document can
only be used to authenticate the controller. To
authenticate a different controller, the entity associated with
the value of controller
needs to authenticate with its
own controller document and associated
authentication
verification relationship.
The assertionMethod
verification relationship is used to
specify how the controller is expected to express claims, such as for
the purposes of issuing a verifiable credential.
assertionMethod
property is OPTIONAL. If present, its associated
value MUST be a set of one or
more verification methods. Each verification method MAY
be embedded or referenced.
This property is useful, for example, during the processing of a verifiable credential by a verifier.
{ "@context": [ "https://www.w3.org/ns/controller/v1", "https://www.w3.org/ns/credentials/v2", "https://w3id.org/security/multikey/v1" ], "id": "https://controller.example/123456789abcdefghi", ... "assertionMethod": [ // this method can be used to assert statements as did:...fghi "https://controller.example/123456789abcdefghi#keys-1", // this method is *only* approved for assertion of statements, it is not // used for any other verification relationship, so its full description is // embedded here rather than using a reference { "id": "https://controller.example/123456789abcdefghi#keys-2", "type": "Multikey", // external (property value) "controller": "https://controller.example/123456789abcdefghi", "publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu" } ], ... }
The keyAgreement
verification relationship is used to
specify how an entity can generate encryption material in order to transmit
confidential information intended for the controller, such as for
the purposes of establishing a secure communication channel with the recipient.
keyAgreement
property is OPTIONAL. If present, the associated
value MUST be a set of one or more
verification methods. Each verification method MAY be embedded or
referenced.
An example of when this property is useful is when encrypting a message intended for the controller. In this case, the counterparty uses the cryptographic public key information in the verification method to wrap a decryption key for the recipient.
{ "@context": "https://www.w3.org/ns/did/v1", "id": "https://controller.example/123456789abcdefghi", ... "keyAgreement": [ "https://controller.example/123456789abcdefghi#keys-1", // the rest of the methods below are *only* approved for key agreement usage // they will not be used for any other verification relationship // the full value is embedded here rather than using only a reference { "id": "https://controller.example/123#keys-2", "type": "Multikey", "controller": "https://controller.example/123", "publicKeyMultibase": "zDnaerx9CtbPJ1q36T5Ln5wYt3MQYeGRG5ehnPAmxcf5mDZpv" }, { "id": "https://controller.example/123#keys-3", "type": "JsonWebKey", "controller": "https://controller.example/123", "publicKeyJwk": { "kty": "OKP", "crv": "X25519", "x": "W_Vcc7guviK-gPNDBmevVw-uJVamQV5rMNQGUwCqlH0" } } ], ... }
The capabilityInvocation
verification relationship is used
to specify a verification method that might be used by the
controller to invoke a cryptographic capability, such as the
authorization to update the controller document.
capabilityInvocation
property is OPTIONAL. If present, the
associated value MUST be a set of
one or more verification methods. Each verification method MAY be
embedded or referenced.
An example of when this property is useful is when a controller needs to access a protected HTTP API that requires authorization in order to use it. In order to authorize when using the HTTP API, the controller uses a capability that is associated with a particular URL that is exposed via the HTTP API. The invocation of the capability could be expressed in a number of ways, e.g., as a digitally signed message that is placed into the HTTP Headers.
The server providing the HTTP API is the verifier of the capability and
it would need to verify that the verification method referred to by the
invoked capability exists in the capabilityInvocation
property of the controller document. The verifier would also check to make sure
that the action being performed is valid and the capability is appropriate for
the resource being accessed. If the verification is successful, the server has
cryptographically determined that the invoker is authorized to access the
protected resource.
{ "@context": [ "https://www.w3.org/ns/controller/v1", "https://w3id.org/security/multikey/v1" ], "id": "https://controller.example/123456789abcdefghi", ... "capabilityInvocation": [ // this method can be used to invoke capabilities as https:...fghi "https://controller.example/123456789abcdefghi#keys-1", // this method is *only* approved for use in capability invocation; it will not // be used for any other verification relationship, so its full description is // embedded here rather than using only a reference { "id": "https://controller.example/123456789abcdefghi#keys-2", "type": "Multikey", // external (property value) "controller": "https://controller.example/123456789abcdefghi", "publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu" } ], ... }
The capabilityDelegation
verification relationship is used
to specify a mechanism that might be used by the controller to delegate
a cryptographic capability to another party, such as delegating the authority
to access a specific HTTP API to a subordinate.
capabilityDelegation
property is OPTIONAL. If present, the
associated value MUST be a set of
one or more verification methods. Each verification method MAY be
embedded or referenced.
An example of when this property is useful is when a controller chooses
to delegate their capability to access a protected HTTP API to a party other
than themselves. In order to delegate the capability, the controller
would use a verification method associated with the
capabilityDelegation
verification relationship to
cryptographically sign the capability over to another controller. The
delegate would then use the capability in a manner that is similar to the
example described in 2.3.4 Capability Invocation.
{ "@context": [ "https://www.w3.org/ns/controller/v1", "https://w3id.org/security/multikey/v1" ], "id": "https://controller.example/123456789abcdefghi", ... "capabilityDelegation": [ // this method can be used to perform capability delegation as did:...fghi "https://controller.example/123456789abcdefghi#keys-1", // this method is *only* approved for granting capabilities; it will not // be used for any other verification relationship, so its full description is // embedded here rather than using only a reference { "id": "https://controller.example/123456789abcdefghi#keys-2", "type": "JsonWebKey", // external (property value) "controller": "https://controller.example/123456789abcdefghi", "publicKeyJwk": { "kty": "OKP", "crv": "Ed25519", "x": "O2onvM62pC1io6jQKm8Nc2UyFXcd4kOmOsBIoYtZ2ik" } }, { "id": "https://controller.example/123456789abcdefghi#keys-3", "type": "Multikey", // external (property value) "controller": "https://controller.example/123456789abcdefghi", "publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu" } ], ... }
A Multibase string includes a single character header which identifies the base and encoding alphabet used to encode a binary value, followed by the encoded binary value (using that base and alphabet). The common Multibase header values and their associated base encoding alphabets as provided below are normative:
Multibase Header | Description |
---|---|
u |
The base-64-url-no-pad alphabet is used to encode the bytes. The base-alphabet
consists of the following characters, in order:
ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_
|
z |
The base-58-btc alphabet is used to encode the bytes. The base-alphabet consists
of the following characters, in order:
123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz
|
Other Multibase encoding values MAY be used, but interoperability is not guaranteed between implementations using such values.
To base-encode a binary value into a Multibase string, an implementation MUST apply the algorithm in Section 3.1 Base Encode to the binary value, with the desired base encoding and alphabet from the table above, ensuring to prepend the associated Multibase header from the table above to the result. Any algorithm with equivalent output MAY be used.
To base-decode a Multibase string, an implementation MUST apply the algorithm in Section 3.2 Base Decode to the string following the first character (Multibase header), with the alphabet associated with the Multibase header. Any algorithm with equivalent output MAY be used.
A Multihash value starts with a binary header, which includes 1) an identifier for the specific cryptographic hash algorithm, 2) the length of the cryptographic hash, and 3) the value of the cryptographic hash. The normative Multihash header values defined by this specification, and their associated output sizes and associated specifications, are provided below:
Multihash Identifier | Multihash Header | Description |
---|---|---|
sha2-256 |
0x12 |
SHA-2 with 256 bits (32 bytes) of output, as defined by [RFC6234]. |
sha2-384 |
0x20 |
SHA-2 with 384 bits (48 bytes) of output, as defined by [RFC6234]. |
sha3-256 |
0x16 |
SHA-3 with 256 bits (32 bytes) of output, as defined by [SHA3]. |
sha3-384 |
0x15 |
SHA-3 with 384 bits (48 bytes) of output, as defined by [SHA3]. |
Other Multihash encoding values MAY be used, but interoperability is not guaranteed between implementations.
To encode to a Multihash value, an implementation MUST concatenate the associated Multihash header, the cryptographic hash length, and the cryptographic hash value, in that order.
To decode a Multihash value, an implementation MUST 1) remove the prepended Multihash header value, which identifies the type of cryptographic hashing algorithm, 2) remove the output length, and 3) extract the raw cryptographic hash value which MUST match the expected output length associated with the Multihash header as well as the output length provided in the Multihash value itself.
This section defines algorithms used by this specification including instructions on how to base-encode and base-decode values, safely retrieve verification methods, and produce processing errors over HTTP channels.
The following algorithm specifies how to encode an array of bytes, where each byte represents a base-256 value, to a different base representation that uses a particular base alphabet, such as base-64-url-no-pad or base-58-btc. The required inputs are the bytes, targetBase, and baseAlphabet. The output is a string that contains the base-encoded value. All mathematical operations MUST be performed using integer arithmetic. Alternatives to the algorithm provided below MAY be used as long as the outputs of the alternative algorithm remain the same.
0
, length to
0
, begin to 0
, and end to the length of
bytes.
0
byte
values in bytes.
1
to the
value of size.
0
. Set basePosition to
size minus 1
. Perform the following loop as long as carry
does not equal 0
or i is less than length, and
basePosition does not equal -1
.
256
and add
it to carry.
1
and increment i by 1
.
1
.
0
, increment
baseEncodingPosition. This step skips the leading zeros in the
base-encoded result.
function baseEncode(bytes, targetBase, baseAlphabet) {
let zeroes = 0;
let length = 0;
let begin = 0;
let end = bytes.length;
// count the number of leading bytes that are zero
while(begin !== end && bytes[begin] === 0) {
begin++;
zeroes++;
}
// allocate enough space to store the target base value
const baseExpansionFactor = Math.log(256) / Math.log(targetBase);
let size = Math.floor((end - begin) * baseExpansionFactor + 1);
let baseValue = new Uint8Array(size);
// process the entire input byte array
while(begin !== end) {
let carry = bytes[begin];
// for each byte in the array, perform base-expansion
let i = 0;
for(let basePosition = size - 1;
(carry !== 0 || i < length) && (basePosition !== -1);
basePosition--, i++) {
carry += Math.floor(256 * baseValue[basePosition]);
baseValue[basePosition] = Math.floor(carry % targetBase);
carry = Math.floor(carry / targetBase);
}
length = i;
begin++;
}
// skip leading zeroes in base-encoded result
let baseEncodingPosition = size - length;
while(baseEncodingPosition !== size &&
baseValue[baseEncodingPosition] === 0) {
baseEncodingPosition++;
}
// convert the base value to the base encoding
let baseEncoding = baseAlphabet.charAt(0).repeat(zeroes)
for(; baseEncodingPosition < size; ++baseEncodingPosition) {
baseEncoding += baseAlphabet.charAt(baseValue[baseEncodingPosition])
}
return baseEncoding;
}
The following algorithm specifies how to decode an array of bytes, where each byte represents a base-encoded value, to a different base representation that uses a particular base alphabet, such as base-64-url-no-pad or base-58-btc. The required inputs are the sourceEncoding, sourceBase, and baseAlphabet. The output is an array of bytes that contains the base-decoded value. All mathematical operations MUST be performed using integer arithmetic. Alternatives to the algorithm provided below MAY be used as long as the outputs of the alternative algorithm remain the same.
0
,
zeroes to 0
, and decodedLength to 0
.
256
) and then multiplying by the
length of sourceEncoding minus the leading zeroes. Add 1 to the value
of size.
0
. Set byteOffset
to decodedSize minus 1
. Perform the following loop as long as,
carry does not equal 0
or i is less than
decodedLength, and byteOffset does not equal -1
:
256
.
256
, ensuring that integer
division is used to perform the division.
1
and increment i by 1
.
1
.
0
, increment
decodedOffset by 1
. This step skips the leading zeros in the
final base-decoded byte array.
0
.
1
, copy all bytes in decodedBytes, up
to decodedSize, starting at offset decodedOffset to
finalBytes.
function baseDecode(sourceEncoding, sourceBase, baseAlphabet) {
// build the base-alphabet to integer value map
baseMap = {};
for(let i = 0; i < baseAlphabet.length; i++) {
baseMap[baseAlphabet[i]] = i;
}
// skip and count zero-byte values in the sourceEncoding
let sourceOffset = 0;
let zeroes = 0;
let decodedLength = 0;
while(sourceEncoding[sourceOffset] === baseAlphabet[0]) {
zeroes++;
sourceOffset++;
}
// allocate the decoded byte array
const baseContractionFactor = Math.log(sourceBase) / Math.log(256);
let decodedSize = Math.floor((
(sourceEncoding.length - sourceOffset) * baseContractionFactor) + 1);
let decodedBytes = new Uint8Array(decodedSize);
// perform base-conversion on the source encoding
while(sourceEncoding[sourceOffset]) {
// process each base-encoded number
let carry = baseMap[sourceEncoding[sourceOffset]];
// convert the base-encoded number by performing base-expansion
let i = 0
for(let byteOffset = decodedSize - 1;
(carry !== 0 || i < decodedLength) && (byteOffset !== -1);
byteOffset--, i++) {
carry += Math.floor(sourceBase * decodedBytes[byteOffset]);
decodedBytes[byteOffset] = Math.floor(carry % 256);
carry = Math.floor(carry / 256);
}
decodedLength = i;
sourceOffset++;
}
// skip leading zeros in the decoded byte array
let decodedOffset = decodedSize - decodedLength;
while(decodedOffset !== decodedSize && decodedBytes[decodedOffset] === 0) {
decodedOffset++;
}
// create the final byte array that has been base-decoded
let finalBytes = new Uint8Array(zeroes + (decodedSize - decodedOffset));
let j = zeroes;
while(decodedOffset !== decodedSize) {
finalBytes[j++] = decodedBytes[decodedOffset++];
}
return finalBytes;
}
The following algorithm specifies how to safely retrieve a verification method, such as a cryptographic public key, by using a verification method identifier. Required inputs are a verification method (verificationMethod), a proof purpose (proofPurpose), and a set of dereferencing options (options). A verification method is produced as output.
The following example provides a minimum conformant controller document containing a minimum conformant verification method as required by the algorithm in this section:
{
"id": "https://controller.example/123",
"verificationMethod": [{
"id": "https://controller.example/123#key-456",
"type": "ExampleVerificationMethodType",
"controller": "https://controller.example/123",
// public cryptographic material goes here
}],
"authentication": ["#key-456"]
}
The algorithms described in this specification throw specific types of errors. Implementers might find it useful to convey these errors to other libraries or software systems. This section provides specific URLs, descriptions, and error codes for the errors, such that an ecosystem implementing technologies described by this specification might interoperate more effectively when errors occur.
When exposing these errors through an HTTP interface, implementers SHOULD use [RFC9457] to encode the error data structure. If [RFC9457] is used:
type
value of the error object MUST be a URL that starts with the value
https://w3id.org/security#
and ends with the value in the section listed
below.
code
value MUST be the integer code described in the table below
(in parentheses, beside the type name).
title
value SHOULD provide a short but specific human-readable string for
the error.
detail
value SHOULD provide a longer human-readable string for the error.
verificationMethod
value in a proof was malformed. See Section
3.3 Retrieve Verification Method.
id
value in a controller document was malformed. See Section
3.3 Retrieve Verification Method.
proofPurpose
property in the proof. See Section
3.3 Retrieve Verification Method.
This section lists cryptographic hash values that might change during the Candidate Recommendation phase based on implementer feedback that requires the referenced files to be modified.
Implementations that perform JSON-LD processing MUST treat the following JSON-LD context URLs as already resolved, where the resolved document matches the corresponding hash values below:
URL, Media Type, and Content Digest |
---|
URL:
https://w3id.org/security/data-integrity/v2 (application/ld+json) SHA2-256 Digest: 67f21e6e33a6c14e5ccfd2fc7865f7474fb71a04af7e94136cb399dfac8ae8f4
|
URL:
https://w3id.org/security/multikey/v1 (application/ld+json) SHA2-256 Digest: ba2c182de2d92f7e47184bcca8fcf0beaee6d3986c527bf664c195bbc7c58597
|
URL:
https://w3id.org/security/jwk/v1 (application/ld+json) SHA2-256 Digest: 0f14b62f6071aafe00df265770ea0c7508e118247d79b7d861a406d2aa00bece
|
The security vocabulary terms that the JSON-LD contexts listed above resolve
to are in the https://w3id.org/security#
namespace. That is, all security terms in this vocabulary are of the form
https://w3id.org/security#TERM
, where TERM
is the name of a term.
Implementations that perform RDF processing MUST treat the following JSON-LD vocabulary URL as already resolved, where the resolved document matches the corresponding hash values below.
When dereferencing the https://w3id.org/security# URL, the data returned depends on HTTP content negotiation. These are as follows:
URL, Media Type, and Content Digest |
---|
URL:
https://w3id.org/security (application/ld+json) SHA2-256 Digest: 6415eddd5732d97a85e04ecfc1a3727cffa8b337d1c49ef6331296a5377017c0
|
URL:
https://w3id.org/security (text/turtle) SHA2-256 Digest: 59663cbe53b4e26f89e77bab602ca9c16a68cf5f5606dc6e286418cbacb48f00
|
URL:
https://w3id.org/security (text/html) SHA2-256 Digest: 0ed0ee5ebc6de40025ca5aa0ed447fa5563931a577f4589e35f2f0b4dc22e77a
|
It is possible to confirm the digests listed above by running the following
command from a modern Unix command interface line:
curl -sL -H "Accept: <MEDIA_TYPE>" <DOCUMENT_URL> | openssl dgst -sha256
.
Authors of application-specific vocabularies and specifications SHOULD ensure that their JSON-LD context and vocabulary files are permanently cacheable using the approaches to caching described above or a functionally equivalent mechanism.
Implementations MAY load application-specific JSON-LD context files from the network during development, but SHOULD permanently cache JSON-LD context files used in conforming documents in production settings to increase their security and privacy characteristics. Caching goals MAY be achieved through approaches such as those described above or functionally equivalent mechanisms.
Some applications, such as digital wallets, that are capable of holding arbitrary verifiable credentials or other data-integrity-protected documents, from any issuer and using any contexts, might need to be able to load externally linked resources, such as JSON-LD context files, in production settings. This is expected to increase user choice, scalability, and decentralized upgrades in the ecosystem over time. Authors of such applications are advised to read the security and privacy sections of this document for further considerations.
For further information regarding processing of JSON-LD contexts and vocabularies, see Verifiable Credentials v2.0: Base Context and Verifiable Credentials v2.0: Vocabularies.
The @context
property is used to ensure that implementations are using the
same semantics when terms in this specification are processed. For example, this
can be important when properties like type
are processed and its value, such
as DataIntegrityProof
, are used.
If an @context
property is not provided in a document that is being secured or
verified, or the Data Integrity terms used in the document are not mapped by
existing values in the @context
property, implementations MUST inject or add
an @context
property with a value of
https://w3id.org/security/data-integrity/v2
.
Context injection is expected to be unnecessary sometimes, such as when the Verifiable
Credential Data Model v2.0 context (https://www.w3.org/ns/credentials/v2
)
exists as a value in the @context
property, as that context maps all of the
necessary Data Integrity terms that were previously mapped by
https://w3id.org/security/data-integrity/v2
.
This section defines datatypes that are used by this specification.
Multibase-encoded strings are used to encode binary
data into ASCII-only formats, which are useful in environments that cannot
directly represent binary values. This specification makes use of this encoding.
In environments that support data types for string values, such as RDF
[RDF-CONCEPTS], Multibase-encoded content is
indicated using a literal value whose datatype is set to
https://w3id.org/security#multibase
.
The multibase
datatype is defined as follows:
https://w3id.org/security#multibase
This section is non-normative.
This section contains a variety of security considerations that people using this specification are advised to consider before deploying this technology in a production setting. This technologies described in this document are designed to operate under the threat model used by many IETF standards and documented in [RFC3552]. This section elaborates upon a number of the considerations in [RFC3552], as well as other considerations that are unique to this specification.
Binding an entity in the digital world or the physical world to an identifier, to a controller document, or to cryptographic material requires, the use of security protocols contemplated by this specification. The following sections describe some possible scenarios and how an entity therein might prove control over an identifier or a controller document for the purposes of authentication or authorization.
Proving control over an identifier and/or a controller document is useful when accessing remote systems. Cryptographic digital signatures enable certain security protocols related to controller documents to be cryptographically verifiable. For these purposes, this specification defines useful verification relationships in 2.3.1 Authentication and 2.3.4 Capability Invocation. The secret cryptographic material associated with the verification methods can be used to generate a cryptographic digital signature as a part of an authentication or authorization security protocol.
An identifier or controller document do not inherently carry any personal data and it is strongly advised that non-public entities do not publish personal data in controller documents.
It can be useful to express a binding of an identifier to a person's or organization's physical identity in a way that is provably asserted by a trusted authority, such as a government. This specification provides the 2.3.2 Assertion verification relationship for these purposes. This feature can enable interactions that are private and can be considered legally enforceable under one or more jurisdictions; establishing such bindings has to be carefully balanced against privacy considerations (see 6. Privacy Considerations).
The process of binding an identifier to something in the physical world, such as a person or an organization — for example, by using verifiable credentials with the same subject as that identifier — is contemplated by this specification and further defined in Verifiable Credentials Data Model v2.0.
In a decentralized architecture, there might not be centralized authorities to enforce cryptographic material or cryptographic digital signature expiration policies. Therefore, it is with supporting software such as verification libraries that requesting parties validate that cryptographic material were not expired at the time they were used. Requesting parties might employ their own expiration policies in addition to inputs into their verification processes. For example, some requesting parties might accept authentications from five minutes in the past, while others with access to high precision time sources might require authentications to be time stamped within the last 500 milliseconds.
There are some requesting parties that have legitimate needs to extend the use of already-expired cryptographic material, such as verifying legacy cryptographic digital signatures. In these scenarios, a requesting party might instruct their verification software to ignore cryptographic key material expiration or determine if the cryptographic key material was expired at the time it was used.
Rotation is a management process that enables the secret cryptographic material associated with an existing verification method to be deactivated or destroyed once a new verification method has been added to the controller document. Going forward, any new proofs that a controller would have generated using the old secret cryptographic material can now instead be generated using the new cryptographic material and can be verified using the new verification method.
Rotation is a useful mechanism for protecting against verification method compromise, since frequent rotation of a verification method by the controller reduces the value of a single compromised verification method to an attacker. Performing revocation immediately after rotation is useful for verification methods that a controller designates for short-lived verifications, such as those involved in encrypting messages and authentication.
The following considerations might be of use when contemplating the use of verification method rotation:
Revocation is a management process that enables the secret cryptographic material associated with an existing verification method to be deactivated such that it ceases to be a valid form of creating new proofs.
Revocation is a useful mechanism for reacting to a verification method compromise. Performing revocation immediately after rotation is useful for verification methods that a controller designates for short-lived verifications, such as those involved in encrypting messages and authentication.
Compromise of the secrets associated with a verification method allows the attacker to use them according to the verification relationship expressed by controller in the controller document, for example, for authentication. The attacker's use of the secrets might be indistinguishable from the legitimate controller's use starting from the time the verification method was registered, to the time it was revoked.
The following considerations might be of use when contemplating the use of verification method revocation:
Although verifiers might choose not to accept proofs or signatures from a revoked verification method, knowing whether a verification was made with a revoked verification method is trickier than it might seem. Some auditing systems provide the ability to look back at the state of an identifier at a point in time, or at a particular version of the controller document. When such a feature is combined with a reliable way to determine the time or identifier version that existed when a cryptographically verifiable statement was made, then revocation does not undo that statement. This can be the basis for using digital signatures to make binding commitments; for example, to sign a mortgage.
If these conditions are met, revocation is not retroactive; it only nullifies future use of the method.
However, in order for such semantics to be safe, the second condition — an ability to know what the state of the controller document was at the time the assertion was made — is expected to apply. Without that guarantee, someone could discover a revoked key and use it to make cryptographically verifiable statements with a simulated date in the past.
Some auditing systems only allow the retrieval of the current state of a identifier. When this is true, or when the state of an identifier at the time of a cryptographically verifiable statement cannot be reliably determined, then the only safe course is to disallow any consideration of state with respect to time, except the present moment. Identifier ecosystems that take this approach essentially provide cryptographically verifiable statements as ephemeral tokens that can be invalidated at any time by the controller.
Encryption algorithms have been known to fail due to advances in cryptography and computing power. Implementers are advised to assume that any encrypted data placed in a controller document might eventually be made available in clear text to the same audience to which the encrypted data is available. This is particularly pertinent if the controller document is public.
Encrypting all or parts of a controller document is not an appropriate means to protect data in the long term. Similarly, placing encrypted data in a controller document is not an appropriate means to protect personal data.
Given the caveats above, if encrypted data is included in a controller document, implementers are advised to not associate any correlatable information that could be used to infer a relationship between the encrypted data and an associated party. Examples of correlatable information include public keys of a receiving party, identifiers to digital assets known to be under the control of a receiving party, or human readable descriptions of a receiving party.
Controller documents which include links to external machine-readable content such as images, web pages, or schemas are vulnerable to tampering. It is strongly advised that external links are integrity protected using mechanisms to secure related resources such as those described in the Verifiable Credentials Data Model v2.0 specification. External links are to be avoided if they cannot be integrity protected and the controller document's integrity is dependent on the external link.
One example of an external link where the integrity of the controller document itself could be affected is the JSON-LD Context [JSON-LD11]. To protect against compromise, controller document consumers are advised to cache local static copies of JSON-LD contexts and/or verify the integrity of external contexts against a cryptographic hash that is known to be associated with a safe version of the external JSON-LD Context.
Additional information about the security context of authentication events is often required for compliance reasons, especially in regulated areas such as the financial and public sectors. This information is often referred to as a Level of Assurance (LOA). Examples include the protection of secret cryptographic material, the identity proofing process, and the form-factor of the authenticator.
Payment services (PSD 2) and eIDAS introduce such requirements to the security context. Level of assurance frameworks are classified and defined by regulations and standards such as eIDAS, NIST 800-63-3 and ISO/IEC 29115:2013, including their requirements for the security context, and making recommendations on how to achieve them. This might include strong user authentication where FIDO2/WebAuthn can fulfill the requirement.
Some regulated scenarios require the implementation of a specific level of assurance. Since verification relationships used to perform assertion and authentication might be used in some of these situations, information about the applied security context might need to be expressed and provided to a verifier. Whether and how to encode this information in the controller document data model is out of scope for this specification. Interested readers might note that 1) the information could be transmitted using Verifiable Credentials [VC-DATA-MODEL-2.0], and 2) the controller document data model can be extended to incorporate this information.
This section is non-normative.
Since controller documents are designed to be administered directly by the controller, it is critically important to apply the principles of Privacy by Design [PRIVACY-BY-DESIGN] to all aspects of the controller document. All seven of these principles have been applied throughout the development of this specification. The design used in this specification does not assume that there is a registrar, hosting company, nor other intermediate service provider to recommend or apply additional privacy safeguards. Privacy in this specification is preventive, not remedial, and is an embedded default. The following sections cover privacy considerations that implementers might find useful when building systems that utilize controller documents.
If a controller document is about a specific individual and is public-facing, it is critical that the controller documents contain no personal data. Personal data can instead be transmitted through other means such as 1) verifiable credentials [VC-DATA-MODEL-2.0], or 2) other private communication channels.
Globally unambiguous identifiers can be used for the purpose of correlation. Controllers can mitigate this privacy risk by using pairwise identifiers that are unique to each relationship; in effect, each identifier acts as a pseudonym. A pairwise identifier need only be shared with more than one party when correlation is explicitly desired. If pairwise identifiers are the default, then the only need to publish an identifier openly, or to share it with multiple parties, is when the controllers and/or subjects explicitly desire public identification and correlation.
The anti-correlation protections of pairwise identifiers are easily defeated if the data in the corresponding controller documents can be correlated. For example, using identical verification methods in multiple controller documents can provide as much correlation information as using the same identifier. Therefore, the controller document for a pairwise identifier also needs to use pairwise unique information, such as ensuring that verification methods are unique to the pairwise relationship.
It is dangerous to add properties to the controller document that can be used to indicate, explicitly or through inference, what type or nature of thing the subject is, particularly if the subject is a person.
Not only do such properties potentially result in personal data (see 6.1 Keep Personal Data Private) or correlatable data (see 6.2 Identifier Correlation Risks and 6.3 Controller Document Correlation Risks) being present in the controller document, but they can be used for grouping particular identifiers in such a way that they are included in or excluded from certain operations or functionalities.
Including type information in a controller document can result in personal privacy harms even for subjects that are non-person entities, such as IoT devices. The aggregation of such information around a controller could serve as a form of digital fingerprint and this is best avoided.
To minimize these risks, all properties in a controller document ought to be for expressing verification methods and verification relationships related to using the identifier.
The following section describes accessibility considerations that developers implementing this specification are urged to consider in order to ensure that their software is usable by people with different cognitive, motor, and visual needs. As a general rule, this specification is used by system software and does not directly expose individuals to information subject to accessibility considerations. However, there are instances where individuals might be indirectly exposed to information expressed by this specification and thus the guidance below is provided for those situations.
This specification enables the expression of dates and times related to the validity period of cryptographic proofs. This information might be indirectly exposed to an individual if a proof is processed and is detected to be outside an allowable time range. When exposing these dates and times to an individual, implementers are urged to take into account cultural normas and locales when representing dates and times in display software. In addition to these considerations, presenting time values in a way that eases the cognitive burden on the individual receiving the information is a suggested best practice.
For example, when conveying the expiration date for a particular set of digitally signed information, implementers are urged to present the time of expiration using language that is easier to understand rather than language that optimizes for accuracy. Presenting the expiration time as "This ticket expired three days ago." is preferred over a phrase such as "This ticket expired on July 25th 2023 at 3:43 PM." The former provides a relative time that is easier to comprehend than the latter time, which requires the individual to do the calculation in their head and presumes that they are capable of doing such a calculation.
This section is non-normative.
This section contains more detailed examples of the concepts introduced in the specification.
This section is non-normative.
This section contains various Multikey examples that might be useful for developers seeking test values.
{ "id": "https://multikey.example/issuer/123#key-0", "type": "Multikey", "controller": "https://multikey.example/issuer/123", "publicKeyMultibase": "zDnaerx9CtbPJ1q36T5Ln5wYt3MQYeGRG5ehnPAmxcf5mDZpv" }
{ "id": "https://multikey.example/issuer/123#key-0", "type": "Multikey", "controller": "https://multikey.example/issuer/123", "publicKeyMultibase": "z82LkvCwHNreneWpsgPEbV3gu1C6NFJEBg4srfJ5gdxEsMGRJ Uz2sG9FE42shbn2xkZJh54" }
{ "id": "https://multikey.example/issuer/123#key-0", "type": "Multikey", "controller": "https://multikey.example/issuer/123", "publicKeyMultibase": "z6Mkf5rGMoatrSj1f4CyvuHBeXJELe9RPdzo2PKGNCKVtZxP" }
{ "id": "https://multikey.example/issuer/123#key-0", "type": "Multikey", "controller": "https://multikey.example/issuer/123", "publicKeyMultibase": "zUC7EK3ZakmukHhuncwkbySmomv3FmrkmS36E4Ks5rsb6VQSRpoCrx6 Hb8e2Nk6UvJFSdyw9NK1scFXJp21gNNYFjVWNgaqyGnkyhtagagCpQb5B7tagJu3HDbjQ8h 5ypoHjwBb" }
{ "@context": "https://www.w3.org/ns/controller/v1", "id": "https://controller.example/123", "verificationMethod": [{ "id": "https://multikey.example/issuer/123#key-1", "type": "Multikey", "controller": "https://multikey.example/issuer/123", "publicKeyMultibase": "zDnaerx9CtbPJ1q36T5Ln5wYt3MQYeGRG5ehnPAmxcf5mDZpv" }, { "id": "https://multikey.example/issuer/123#key-2", "type": "Multikey", "controller": "https://multikey.example/issuer/123", "publicKeyMultibase": "z6Mkf5rGMoatrSj1f4CyvuHBeXJELe9RPdzo2PKGNCKVtZxP" }, { "id": "https://multikey.example/issuer/123#key-3", "type": "Multikey", "controller": "https://multikey.example/issuer/123", "publicKeyMultibase": "zUC7EK3ZakmukHhuncwkbySmomv3FmrkmS36E4Ks5rsb6VQSRpoCrx6 Hb8e2Nk6UvJFSdyw9NK1scFXJp21gNNYFjVWNgaqyGnkyhtagagCpQb5B7tagJu3HDbjQ8h 5ypoHjwBb" }], "authentication": [ "https://controller.example/123#key-1" ], "assertionMethod": [ "https://controller.example/123#key-2" "https://controller.example/123#key-3" ], "capabilityDelegation": [ "https://controller.example/123#key-2" ], "capabilityInvocation": [ "https://controller.example/123#key-2" ] }
This section is non-normative.
This section contains various JsonWebKey examples that might be useful for developers seeking test values.
{ "id": "https://jsonwebkey.example/issuer/123#key-0", "type": "JsonWebKey", "controller": "https://jsonwebkey.example/issuer/123", "publicKeyJwk": { "kty": "EC", "crv": "P-256", "x": "Ums5WVgwRkRTVVFnU3k5c2xvZllMbEcwM3NPRW91ZzN", "y": "nDQW6XZ7b_u2Sy9slofYLlG03sOEoug3I0aAPQ0exs4" } }
{ "id": "https://jsonwebkey.example/issuer/123#key-0", "type": "JsonWebKey", "controller": "https://jsonwebkey.example/issuer/123", "publicKeyJwk": { "kty": "EC", "crv": "P-384", "x": "VUZKSlUwMGdpSXplekRwODhzX2N4U1BYdHVYWUZsaXVDR25kZ1U0UXA4bDkxeHpE", "y": "jq4QoAHKiIzezDp88s_cxSPXtuXYFliuCGndgU4Qp8l91xzD1spCmFIzQgVjqvcP" } }
{ "id": "https://jsonwebkey.example/issuer/123#key-0", "type": "JsonWebKey", "controller": "https://jsonwebkey.example/issuer/123", "publicKeyJwk": { "kty": "OKP", "crv": "Ed25519", "x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOyPVQaO3FxVeQ" } }
{ "id": "https://jsonwebkey.example/issuer/123#key-0", "type": "JsonWebKey", "controller": "https://jsonwebkey.example/issuer/123", "publicKeyJwk": { "kty": "EC", "crv": "BLS12381G2", "x": "Ajs8lstTgoTgXMF6QXdyh3m8k2ixxURGYLMaYylVK_x0F8HhE8zk0YWiGV3CHwpQEa2sH4PBZLaYCn8se-1clmCORDsKxbbw3Js_Alu4OmkV9gmbJsy1YF2rt7Vxzs6S", "y": "BVkkrVEib-P_FMPHNtqxJymP3pV-H8fCdvPkoWInpFfM9tViyqD8JAmwDf64zU2hBV_vvCQ632ScAooEExXuz1IeQH9D2o-uY_dAjZ37YHuRMEyzh8Tq-90JHQvicOqx" } }
{ "id": "https://jsonwebkey.example/issuer/123#key-0", "type": "JsonWebKey", "controller": "https://jsonwebkey.example/issuer/123", "publicKeyJwk": { "kty": "OKP", "crv": "Bls12381G2", "x": "rMvXj_LibMeRrNh2sqmkBqBH4xKeOWmAYK8inVMX1839y6XeolnbT6vxnxU2PmV9FXJ-rtcz6Txe7v2ij1dFzMHuBT1TyBrtEZWtCSOMTIBXpnVsOMMSdhsTB1iUS9o1" } }
{ "@context": "https://www.w3.org/ns/controller/v1", "id": "https://controller.example/123", "verificationMethod": [{ "id": "https://jsonwebkey.example/issuer/123#key-1", "type": "JsonWebKey", "controller": "https://jsonwebkey.example/issuer/123", "publicKeyJwk": { "kty": "EC", "crv": "P-256", "x": "fyNYMN0976ci7xqiSdag3buk-ZCwgXU4kz9XNkBlNUI", "y": "hW2ojTNfH7Jbi8--CJUo3OCbH3y5n91g-IMA9MLMbTU" } }, { "id": "https://jsonwebkey.example/issuer/123#key-2", "type": "JsonWebKey", "controller": "https://jsonwebkey.example/issuer/123", "publicKeyJwk": { "kty": "EC", "crv": "P-521", "x": "ASUHPMyichQ0QbHZ9ofNx_l4y7luncn5feKLo3OpJ2nSbZoC7mffolj5uy7s6KSKXFmnNWxGJ42IOrjZ47qqwqyS", "y": "AW9ziIC4ZQQVSNmLlp59yYKrjRY0_VqO-GOIYQ9tYpPraBKUloEId6cI_vynCzlZWZtWpgOM3HPhYEgawQ703RjC" } }, { "id": "https://jsonwebkey.example/issuer/123#key-3", "type": "JsonWebKey", "controller": "https://jsonwebkey.example/issuer/123", "publicKeyJwk": { "kty": "OKP", "crv": "Ed25519", "x": "_eT7oDCtAC98L31MMx9J0T-w7HR-zuvsY08f9MvKne8" } }], "authentication": [ "https://controller.example/123#key-1" ], "assertionMethod": [ "https://controller.example/123#key-2" "https://controller.example/123#key-3" ], "capabilityDelegation": [ "https://controller.example/123#key-2" ], "capabilityInvocation": [ "https://controller.example/123#key-2" ] }
This section is non-normative.
This section contains the substantive changes that have been made to this specification over time.
This section is non-normative.
The specification authors would like to thank the contributors to the W3C Decentralized Identifiers (DIDs) v1.0, W3C Verifiable Credential Data Integrity 1.0, and W3C Securing Verifiable Credentials using JOSE and COSE specifications upon which this work is based.
we would also like to thank the base-x software library contributors and the Bitcoin Core developers who wrote the original code, shared under an MIT License, found in Section 3.1 Base Encode and Section 3.2 Base Decode.
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: