A controller document specifies one or more relationships between
an identifier and a set of verification methods and/or service
endpoints. The controller document SHOULD
contain verification relationships that explicitly permit the use of
certain verification methods for specific purposes.
Example 1: Controller Document using publicKeyJwk
{
"id": "https://controller.example/101",
"verificationMethod": [{
"id": "https://controller.example/101#key-20240828",
"type": "JsonWebKey",
"controller": "https://controller.example/101",
"publicKeyJwk": {
"kid": "key-20240828",
"kty": "EC",
"crv": "P-256",
"alg": "ES256",
"x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
"y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0"
}
}],
"authentication": ["#key-20240828"]
}
Example 2: Controller Document using publicKeyMultibase and JSON-LD
{
"@context": "https://www.w3.org/ns/controller/v1",
"id": "https://controller.example",
"authentication": [{
"id": "https://controller.example#authn-key-123",
"type": "Multikey",
"controller": "https://controller.example",
"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
}]
}
Note: Property names used in map of different types
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 |
Definition |
id |
yes |
A string that conforms to the URL syntax.
|
2.1.1 Subjects |
controller |
no |
A string or a
set of
strings, each of which conforms to the URL
syntax.
|
2.1.2 Controllers |
alsoKnownAs |
no |
A set of
strings, each of which conforms to the URL
syntax.
|
2.1.3 Also Known As |
service |
no |
A set of service
maps.
|
2.1.4 Services |
verificationMethod |
no |
A set of
verification method maps.
|
2.2 Verification Methods |
authentication |
no |
A set of strings, each of which conforms to
the URL syntax, or a set of
verification method maps.
|
2.3.1 Authentication |
assertionMethod |
no |
A set of strings, each of which conforms to
the URL syntax, or a set of
verification method maps.
|
2.3.2 Assertion |
keyAgreement |
no |
A set of strings, each of which conforms to
the URL syntax, or a set of
verification method maps.
|
2.3.3 Key Agreement |
capabilityInvocation |
no |
A set of strings, each of which conforms to
the URL syntax, or a set of
verification method maps.
|
2.3.4 Capability Invocation |
capabilityDelegation |
no |
A set of strings, each of which conforms to
the URL syntax, or a set of
verification method maps.
|
2.3.5 Capability Delegation |
A controller of a controller document is any entity capable of making changes to that
controller document. Whoever can update
the content of the resource returned from dereferencing the controller
document's canonical URL is, by definition, a controller of the
document and its canonical identifier. Proofs that satisfy a
controller document's verification methods are taken as cryptographic
assurance that the controller of the identifier created those proofs.
- controller
-
The
controller property is OPTIONAL. If it is possible to represent
the legitimate controllers of the document as URLs, the document SHOULD
list URLs identifying those controllers.
Note: Presumed Control
It is possible to list a verification method which is
functionally under the control of someone other than the controller
of the controller document. For example, a document controller could
set a public key under another party's control as an authentication
verification method. This would enable the other party to authenticate
on behalf of this identifier (because their public key is listed in
an authentication verification method) without enabling that party
to update the controller document. However, since the document
controller explicitly listed that key for authentication, the
proof in question is taken as created by the document controller, as
it was created by their explicit assignee. This is especially useful
when the "other party" is a device under the control of the document
controller, but with a distinct cryptographic authority, i.e., it
has its own keystore and can generate proofs. That pattern enables
different devices, each using their own cryptographic material, to
generate verifiable proofs that are taken as proofs created by
controller of the identifier.
Each entry in the controller property MUST identify
an entity capable of updating the canonical version
of the controller document.
Subsequent requests for this controller document through its
canonical location will always receive the latest version.
If the controller property is not present, then control of the document
is determined entirely by its storage location.
Example 4: Controller document with a controller property
{
"@context": "https://www.w3.org/ns/controller/v1",
"id": "https://controller1.example/123",
"controller": "https://controllerB.example/abc",
}
While the identifier used for a controller is unambiguous, this does not
imply that a single entity is always the controller, nor that a controller
only has a single identifier. A controller might be a single entity, or a
collection of entities, such as a partnership. A controller might also use
multiple identifiers to refer to itself, for purposes such as privacy or
delineating operational boundaries within an organization. Similarly, a
controller might control many verification methods. For these reasons,
no assumptions are to be made about a controller being a single entity nor
controlling only a single verification method.
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
-
The
alsoKnownAs property is OPTIONAL. If present, its value MUST
be a set where each item in the
set is a URI conforming to [RFC3986].
-
This relationship is a statement that the subject of this identifier is
also identified by one or more other identifiers.
Note: Equivalence and alsoKnownAs
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.
Services are used in controller documents to express ways of
communicating with the controller, or associated entities, in relation to
the controlled identifier. A service can be
any type of service the controller wants to advertise for further discovery,
authentication, authorization, or interaction.
Due to privacy concerns, revealing public information through services, such
as social media accounts, personal websites, and email addresses, is
discouraged. Further exploration of privacy concerns can be found in sections
6.1 Keep Personal Data Private and 6.6 Service Privacy. The information
associated with services is often service specific. For example, the
information associated with an encrypted messaging service can express how to
initiate the encrypted link before messaging begins.
Services are expressed using the service property, which is described
below:
- service
-
The service property is OPTIONAL. If present, the associated value MUST be a
set of services, where each service is
described by a map. Each service map MUST contain id, type, and
serviceEndpoint properties. Each service extension MAY include additional
properties and MAY further restrict the properties associated with the
extension.
- id
-
The
id property is OPTIONAL. If present, its value MUST be a URL
conforming to URL Standard. A conforming document MUST NOT include multiple
service entries with the same id.
- type
-
The
type property is REQUIRED. Its value MUST be a
string or a
set of
strings. To maximize interoperability,
the service type and its associated properties SHOULD be registered in the
Verifiable Credential Extensions.
- serviceEndpoint
-
The
serviceEndpoint property is REQUIRED. The value of the serviceEndpoint
property MUST be a single string, a single
map, or a set
composed of one or more
strings and/or
maps. Each string
value MUST be a valid URL conforming to URL Standard.
For more information regarding privacy and security considerations related to
services see 6.6 Service Privacy, 6.1 Keep Personal Data Private,
6.4 Controller Document Correlation Risks, and
5.11 Service Endpoints for Authentication and Authorization.
{
"service": [{
"type": "ExampleSocialMediaService",
"serviceEndpoint": "https://warbler.example/sal674"
}]
}
A controller document can express verification methods, such as
cryptographic public keys, which can be used to verify proofs,
such as those 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.
"Verification" and "proof" 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."
A verification method is defined in a controller document using the
map below and is referred to as the
verification method definition:
- verificationMethod
-
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.
- id
-
The value of the id property for a verification method MUST be a string that conforms to the [URL] syntax. This
value is called the verification method identifier and can also be
used in a proof to refer to a specific instance of a verification method, which is called the verification method definition.
- type
-
The value of the
type property MUST be a string that references exactly one verification
method type. This specification defines the types JsonWebKey (see Section
2.2.3 JsonWebKey) and Multikey (see Section 2.2.2 Multikey).
- controller
-
The value of the
controller property MUST be a string that conforms to the [URL] syntax.
- expires
-
The
expires property is OPTIONAL.
If provided, 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 expiration.
- revoked
-
The
revoked property is OPTIONAL.
If present, it MUST be an [XMLSCHEMA11-2]
dateTimeStamp string specifying when the verification method
MUST NOT 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.
Example 6: Example verification method structure
{
"@context": "https://www.w3.org/ns/controller/v1",
"id": "https://controller.example/123456789abcdefghi",
"verificationMethod": [{
"id": ,
"type": ,
"controller": ,
"publicKeyJwk":
}, {
"id": ,
"type": ,
"controller": ,
"publicKeyMultibase":
}]
}
Note: The `controller` property is used by multiple objects
The controller property is used by controller documents, as described in
Section 2.1 Controller Documents, and by verification methods, as
described in Section 2.2 Verification Methods. When it is used in either
place, its purpose is essentially the same; that is, it expresses one or more
entities that are authorized to perform certain actions associated with the
resource with which it is associated.
In the case of the controller of a controller document, the
controller can update the content of the document. In the case of the
controller of a verification method, the controller can generate
proofs that satisfy the method.
To ensure explicit security guarantees, the
controller of a verification method cannot be inferred from the
controller document. It is necessary to explicitly express the identifier of
the controller of the key because the value of controller for a verification method is not necessarily the value of the controller for a
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 using verification material, 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
choose from, the more likely that interoperability will be achieved. 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.
Example 7: Verification methods using publicKeyJwk and publicKeyMultibase
{
"@context": "https://www.w3.org/ns/controller/v1",
"id": "https://controller.example/123456789abcdefghi",
"verificationMethod": [{
"id": "https://controller.example/123#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
"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-1",
"type": "Multikey",
"controller": "https://controller.example/123456789abcdefghi",
"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
-
The value of the
type property MUST be a string that is set to
Multikey.
- publicKeyMultibase
-
The
publicKeyMultibase property is OPTIONAL. If present, its value MUST be a
Multibase encoded value as described in Section 2.4 Multibase.
- secretKeyMultibase
-
The
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:
Example 8: Multikey encoding of a Ed25519 public key
{
"@context": "https://www.w3.org/ns/controller/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
-
The value of the
type property MUST be a string that is set to
JsonWebKey.
- publicKeyJwk
-
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 JWK Thumbprint [RFC7638] using the SHA-256 (SHA2-256) hash function of the public key.
See the first key in
Example 7 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
-
The
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:
Example 9: JSON Web Key encoding of a secp384r1 (P-384) public key
{
"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 "EC", which means
"Elliptic Curve". 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 and y properties specify
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.
Example 10: JSON Web Key encoding of a secp384r1 (P-384) secret key
{
"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 and y properties, which still specify
the point on the P-384 curve that is associated with the public key).
A verification relationship is an expression that one or more
verification methods are authorized to verify proofs made on behalf of
the subject.
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 referred to by the appropriate verification relationship property in the controller document.
The verification relationship between the subject 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 associated with the authentication property cannot be used to
engage in key agreement protocols — the value of the
keyAgreement property needs to be used for
that.
If a referenced verification method definition 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 interoperability,
any such properties used SHOULD be registered in the list of
DID Document Property Extensions.
The authentication verification relationship is used to specify how the
subject is expected to be authenticated, for purposes such as logging
into a website or engaging in any sort of challenge-response protocol. The
processing performed following authentication is application-specific.
- authentication
-
The
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.
Example 12: Authentication property
containing three verification methods
{
"@context": "https://www.w3.org/ns/controller/v1",
"id": "https://controller.example/123456789abcdefghi",
"authentication": [
"https://controller.example/123456789abcdefghi#keys-1",
{
"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"
}
],
}
This is useful to any entity verifying authentication that needs to check
whether an entity that is attempting to authenticate is presenting a valid
proof of authentication. When such an authentication-verifying entity 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 (for example, 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 on behalf
of the controller document's base identifier.
The assertionMethod verification relationship is used to
specify verification methods that a controller authorizes for use
when expressing assertions or claims, such as in verifiable credentials.
- assertionMethod
-
The
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.
Example 13: Assertion method property
containing two verification methods
{
"@context": "https://www.w3.org/ns/controller/v1",
"id": "https://controller.example/123456789abcdefghi",
"assertionMethod": [
"https://controller.example/123456789abcdefghi#keys-1",
{
"id": "https://controller.example/123456789abcdefghi#keys-2",
"type": "Multikey",
"controller": "https://controller.example/123456789abcdefghi",
"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
}
],
}
The keyAgreement verification relationship is used to
specify how an entity can perform encryption 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
-
The
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.
Example 14: Key agreement property
containing two verification methods
{
"@context": "https://www.w3.org/ns/controller/v1",
"id": "https://controller.example/123456789abcdefghi",
"keyAgreement": [
"https://controller.example/123456789abcdefghi#keys-1",
{
"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
-
The
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, for example, 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.
Example 15: Capability invocation property
containing two verification methods
{
"@context": "https://www.w3.org/ns/controller/v1",
"id": "https://controller.example/123456789abcdefghi",
"capabilityInvocation": [
"https://controller.example/123456789abcdefghi#keys-1",
{
"id": "https://controller.example/123456789abcdefghi#keys-2",
"type": "Multikey",
"controller": "https://controller.example/123456789abcdefghi",
"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
}
],
}
The capabilityDelegation verification relationship is used to specify a
mechanism that might be used to delegate a cryptographic
capability to another party. The mechanism, such as an
Authorization Capability
or a UCAN, and
the processing performed following delegation, such as accessing a specific HTTP
API, is application-specific.
- capabilityDelegation
-
The
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.
Example 16: Capability Delegation property
containing two verification methods
{
"@context": "https://www.w3.org/ns/controller/v1",
"id": "https://controller.example/123456789abcdefghi",
"capabilityDelegation": [
"https://controller.example/123456789abcdefghi#keys-1",
{
"id": "https://controller.example/123456789abcdefghi#keys-2",
"type": "JsonWebKey",
"controller": "https://controller.example/123456789abcdefghi",
"publicKeyJwk": {
"kty": "OKP",
"crv": "Ed25519",
"x": "O2onvM62pC1io6jQKm8Nc2UyFXcd4kOmOsBIoYtZ2ik"
}
},
{
"id": "https://controller.example/123456789abcdefghi#keys-3",
"type": "Multikey",
"controller": "https://controller.example/123456789abcdefghi",
"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
}
],
}
A Multibase value encodes a binary value as a
base-encoded
string. The value starts with 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
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 hashing algorithm, 2) a cryptographic digest
length in bytes, and 3) the value of the cryptographic digest. 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 (encoded as a varint), the cryptographic digest
length in bytes (encoded as a varint), and the cryptographic digest 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 cryptographic digest length in bytes, and 3) extract
the raw cryptographic digest 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.
Issue 2: (AT RISK) Hash values might change during Candidate Recommendation
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.
The terms defined in this specification are also part of the
RDF vocabulary namespace [RDF-CONCEPTS]
https://w3id.org/security#.
For any TERM, the relevant URL is of the form
https://w3id.org/security#TERM or https://w3id.org/security#TERMmethod.
Implementations that use RDF processing and rely on this specification MUST use these URLs.
When dereferencing the
https://w3id.org/security# URL,
the media type of the data that is returned depends on HTTP content negotiation. These are as follows:
| Media Type |
Description and Hash |
|
application/ld+json
|
The vocabulary in JSON-LD format [JSON-LD11].
SHA2-256 Digest: 0825e3f71462e105e85ea144e2eb1521c2755e6679bd2eb459a9a796c56b18e8
|
|
text/turtle
|
The vocabulary in Turtle format [TURTLE].
SHA2-256 Digest: 2fefc7e645fdfa34491c772d0e9c2eed9f95cde3b205e4667abe876580be7f7d
|
|
text/html
|
The vocabulary in HTML+RDFa Format [HTML-RDFA].
SHA2-256 Digest: 0f989a247fb87f514640f1080ad40713b6c950edeb1d29e8c5b45f647699b3d4
|
It is possible to confirm the cryptographic digests above by running
a command like the following (replacing <MEDIA_TYPE> and <DOCUMENT_URL>
with the appropriate values) through a modern UNIX-like OS command line interface:
curl -sL -H "Accept: <MEDIA_TYPE>" <DOCUMENT_URL> | openssl dgst -sha256
Implementations that perform JSON-LD processing MUST treat the following
JSON-LD context URL as already resolved, where the resolved document matches
the corresponding hash value below:
| Context URL and Hash |
|---|
URL: https://www.w3.org/ns/controller/v1
SHA2-256 Digest:
ea216ecc1cb02cd39b693dba2250141e270ba0bf95890be107dd9a9e8e43de85
|
It is possible to confirm the cryptographic digests listed above by running a
command like the following through a modern UNIX-like OS command line interface: curl -sL -H
"Accept: application/ld+json" https://www.w3.org/ns/controller/v1 | openssl dgst -sha256
The security vocabulary terms that the JSON-LD contexts listed above resolve
to are in the https://w3id.org/security#
namespace. See also 4.1 Vocabulary for further details.
Note
Applications or specifications may define mappings to the
vocabulary URLs using their own JSON-LD contexts. For example, these mappings are part
of the https://w3id.org/security/data-integrity/v2 context,
defined by the Verifiable Credential Data Integrity 1.0 specification, or the https://www.w3.org/ns/did/v1 context,
defined by the Decentralized Identifiers (DIDs) v1.0 specification.
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 authentication are processed and its
value, such as Multikey or JsonWebKey, are used.
When an application is processing a controller document, if an @context
property is not provided in the document or the terms used in the document are
not mapped by existing values in the @context property, implementations MUST
inject or append an @context property with a value of
https://www.w3.org/ns/controller/v1 or one or more contexts with at least the
same declarations, such as the Decentralized Identifier v1.1 context
(https://www.w3.org/ns/did/v1).
Example 21: A controller document without an @context property
{
"id": "https://controller.example/101",
"verificationMethod": [{
"id": "https://controller.example/101#key-203947",
"type": "JsonWebKey",
"controller": "https://controller.example/101",
"publicKeyJwk": {
"kid": "key-203947",
"kty": "EC",
"crv": "P-256",
"alg": "ES256",
"x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
"y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0"
}
}],
"authentication": ["#key-203947"]
}
Implementations that do not intend to use JSON-LD MAY choose to not include an
@context declaration at the top-level of the document. Whether or not the
@context value or JSON-LD processors are used, the semantics for all properties
and values expressed in conforming documents interpreted by conforming processors are the same. Any differences in semantics between documents
processed in either mode are either implementation or specification bugs.
This section defines datatypes that are used by this specification.
Multibase-encoded strings are used to encode binary
data into printable formats, such as ASCII, 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:
- The URL denoting this datatype
-
https://w3id.org/security#multibase
- The lexical space
-
Any string that starts with a and the rest of the
characters consist of allowable characters in the respective base-encoding
alphabet.
- The value space
-
The standard mathematical concept of all integer numbers.
- The lexical-to-value mapping
-
Any element of the lexical space is mapped to the value space by base-decoding
the value based on the base-decoding alphabet associated with the first
in the lexical string.
- The canonical mapping
-
The canonical mapping consists of using the lexical-to-value mapping.
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.
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.
Even in cases where the subject referred to by an identifier proves
control, the interpretation of the subject remains contextual and
potentially ambiguous.
For example, a school might issue a verifiable credential about the teacher
of Intro to Computer Science, using
https://controller.example/abc as a subject identifier, saying
"https://controller.example/abc is the teacher of
Intro to Computer Science" and
"https://controller.example/abc controls access to the school's computer lab.
See them to request access".
In this usage, it is ambiguous whether https://controller.example/abc refers
to a specific teacher or to whomever is the current teacher. Only with further
statements might we be able to discern the difference. But it's still tricky.
For example the subject in the following statement remains ambiguous:
Example 22: Statement about the name of https://controller.example/abc as RDF Triples
<https://controller.example/abc>
<https://schema.org/name>
"Bob Smith" .
If https://controller.example/abc refers to a specific human being, then the
statement is taken as an attestation about the particular human identified by
that name. However, if https://controller.example/abc is used to refer to the
_current_ teacher, it is also valid if the current teacher does have that
name. In this case, the ambiguity is immaterial.
However, in a statement like the following, the difference becomes vital.
Example 23: Legal statements the convicted status of https://controller.example/abc as RDF Triples
<https://controller.example/abc>
<http://law.example/convicted>
<http://calaw.example/PenalCode647b> .
The statement in English could be "The person referred to by
https://controller.example/abc has been convicted of California Penal Code
647b." But which person(s) did we mean? Did we mean to say one, some, or all of
the teachers of computer science at the school have been convicted of violating
PenalCode647b? Or is it meant to say that a particular individual teacher,
perhaps the one named "Bob Smith", has been convicted of said crime?
The challenge is particularly difficult in situations where the subject is
fundamentally uninvolved in the issuance of the verifiable credential.
For example, an identifier might be used by a school to refer to a teacher,
and students and or parents might use that identifier to make statements
about the teacher, with neither the teacher nor the school involved. In these
cases, it is easy to imagine that the subtle nuance of the school's intended
meaning, for example, "any current teacher of the computer science class", gets
lost and the identifier gets misused by parents and students to refer to a
specific teacher, quite likely in contexts where neither the school nor the
teacher is aware of the conversation.
In natural language, these ambiguities are often easily ignored or corrected. In
digital media, it is vital that context be evaluated to establish the intended
referent, especially when identifiers are used in different contexts by
different issuers, for example, on an official school website by the school,
but in an unofficial social networking app by parents and students.
In short, the context in which identifiers are created and used has to be
considered when relying on any particular interpretation of the subject of
any particular identifier.
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 materials 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:
-
Verification method rotation is a proactive security measure.
-
It is generally considered a best practice to perform verification method
rotation on a regular basis.
-
Higher security environments tend to employ more frequent verification method
rotation.
-
Verification method rotation manifests only as changes to the current or
latest version of a controller document.
-
When a verification method has been active for a long time, or used for
many operations, a controller might wish to perform a rotation.
-
Frequent rotation of a verification method might be frustrating for
parties that are forced to continuously renew or refresh associated credentials.
-
Proofs or signatures that rely on verification methods that are not
present in the latest version of a controller document are not impacted by
rotation. In these cases, verification software might require additional
information, such as when a particular verification method was
expected to be valid as well as access to a verifiable data registry
containing a historical record, to determine the validity of the proof or
signature. This option might not be available in all systems.
-
A controller performs a rotation when it adds a new verification
method that is meant to replace an existing verification method after
some time.
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:
-
Verification method revocation is a reactive security measure.
-
It is considered a best practice to support key revocation.
-
A controller is expected to immediately revoke any verification
method that is known to be compromised.
-
Verification method revocation can only be embodied in changes to
the latest version of a controller document; it cannot retroactively adjust
previous versions.
-
If a verification method is no longer exclusively accessible to the
controller or parties trusted to act on behalf of the controller,
it is expected to be revoked immediately to reduce the risk of
compromises such as masquerading, theft, and fraud.
-
Revocation is expected to be understood as a controller expressing that
proofs or signatures associated with a revoked verification method
created after its revocation should be treated as invalid. It could also imply a
concern that existing proofs or signatures might have been created by an
attacker, but this is not necessarily the case. Verifiers, however, might still
choose to accept or reject any such proofs or signatures at their own
discretion.
-
Even if a verification method is present in a controller document,
additional information, such as a public key revocation certificate, or an
external allow or deny list, could be used to determine whether a
verification method has been revoked.
-
The day-to-day operation of any software relying on a compromised
verification method, such as an individual's operating system, antivirus,
or endpoint protection software, could be impacted when the verification
method is publicly revoked.
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 that 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],
when present. To protect against compromise,
controller document consumers using JSON-LD 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.
As described in Section 2.1.2 Controllers, this specification includes a
mechanism by which to delegate change control of a controller document to
an entity that is described in an external controller document through the
use of the controller property.
Delegating change control addresses a number of use cases including those
where the care of an entity is the responsibility of some other entity or
entities, as well as those where some entity desires that another entity
provide account recovery services, among other use cases. In such scenarios,
it can be beneficial to allow the guardian to manage the rotation of their
own key material. It can also be beneficial for the delegator to associate
a cryptographic hash of the remote controller document to "pin" the
remote document to a known good value.
While this document does not specify a particular mechanism for
cryptographically protected URLs, the relatedResource property in
Verifiable Credentials Data Model v2.0 and the digestMultibase property in
Verifiable Credential Data Integrity 1.0 could be employed by a mechanism that can provide
such protection.
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.
The specification authors would like to thank the contributors to the
W3C Decentralized Identifiers (DIDs) v1.0 specification upon which this work
is based.
The Working Group gratefully acknowledges the work that led to the creation of
this specification, and extends sincere appreciation to those individuals that
worked on technologies and specifications that deeply influenced our work. In
particular, this includes the work of Phil Zimmerman, Jon Callas, Lutz
Donnerhacke, Hal Finney, David Shaw, and Rodney Thayer on Pretty Good Privacy
(PGP) in the 1990s and 2000s.
In the mid-2010s, preliminary implementations of what would become Decentralized
Identifiers were
built in collaboration with Jeremie Miller's Telehash project and the W3C
Web Payments Community Group's work led by Dave Longley and Manu Sporny. Around
a year later, the XDI.org Registry Working Group
began exploring decentralized technologies for replacing its existing
identifier registry. Some of the first
written
papers
exploring the concept of Decentralized Identifiers can be traced back to the
first several Rebooting the Web of Trust workshops convened by Christopher
Allen. That work led to a key collaboration between Christopher Allen, Drummond
Reed, Les Chasen, Manu Sporny, and Anil John. Anil saw promise in the technology
and allocated the initial set of government funding to explore the space.
Without the support of Anil John and his guidance through the years, it is
unlikely that Decentralized Identifiers would be where they are today. Further
refinement at the Rebooting the Web of Trust workshops led to the first
implementers documentation, edited by Drummond Reed, Les Chasen, Christopher
Allen, and Ryan Grant. Contributors included Manu Sporny, Dave Longley, Jason
Law, Daniel Hardman, Markus Sabadello, Christian Lundkvist, and Jonathan
Endersby. This initial work was then merged into the W3C Credentials Community
Group, incubated further, and then transitioned to the W3C Decentralized
Identifiers Working Group for global standardization. That work was then used
as the basis for this, more generalized and less decentralized, specification.
Portions of the work on this specification have been funded by the United States
Department of Homeland Security's (US DHS) Science and Technology Directorate
under contracts HSHQDC-16-R00012-H-SB2016-1-002, and HSHQDC-17-C-00019, as well
as the US DHS Silicon Valley Innovation Program under contracts
70RSAT20T00000003, 70RSAT20T00000010/P00001, 70RSAT20T00000029,
70RSAT20T00000030, 70RSAT20T00000033, 70RSAT20T00000045,
70RSAT21T00000016/P00001, 70RSAT23T00000005, 70RSAT23C00000030, and
70RSAT23R00000006. The content of this specification does not necessarily
reflect the position or the policy of the U.S. Government and no official
endorsement should be inferred.
Portions of the work on this specification have also been funded by the European
Union's StandICT.eu program under sub-grantee contract number CALL05/19. The
content of this specification does not necessarily reflect the position or the
policy of the European Union and no official endorsement should be inferred.
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.
Work on this specification has also been supported by the
Rebooting the Web of Trust community
facilitated by Christopher Allen, Shannon Appelcline, Kiara Robles, Brian
Weller, Betty Dhamers, Kaliya Young, Kim Hamilton Duffy, Manu Sporny, Drummond
Reed, Joe Andrieu, Heather Vescent, Samantha Chase, Andrew Hughes, Erica
Connell, Shigeya Suzuki, and Zaïda Rivai. Development of this specification has
also been supported by the
W3C Credentials Community Group, which
has been Chaired by Kim Hamilton Duffy, Joe Andrieu, Christopher Allen, Heather
Vescent, and Wayne Chang. The participants in the Internet Identity Workshop,
facilitated by Phil Windley, Kaliya Young, Doc Searls, and Heidi Nobantu Saul,
also supported this work through numerous working sessions designed to debate,
improve, and educate participants about this specification.
The Working Group thanks the following individuals for their contributions to
this specification (in alphabetical order, Github handles start with @ and
are sorted as last names): Denis Ah-Kang, Nacho Alamillo, Christopher Allen, Joe
Andrieu, Antonio, Phil Archer, George Aristy, Baha, Juan Benet, BigBlueHat, Dan
Bolser, Chris Boscolo, Pelle Braendgaard, Daniel Buchner, Daniel Burnett, Juan
Caballero, @cabo, Tim Cappalli, Melvin Carvalho, David Chadwick, Wayne Chang,
Sam Curren, Hai Dang, Tim Daubenschütz, Oskar van Deventer, Kim Hamilton Duffy,
Arnaud Durand, Ken Ebert, Veikko Eeva, @ewagner70, Carson Farmer, Nikos Fotiou,
Gabe, Gayan, @gimly-jack, @gjgd, Ryan Grant, Peter Grassberger, Adrian Gropper,
Amy Guy, Daniel Hardman, Kyle Den Hartog, Philippe Le Hegaret, Ivan Herman,
Michael Herman, Alen Horvat, Dave Huseby, Marcel Jackisch, Mike Jones, Andrew
Jones, Tom Jones, jonnycrunch, Gregg Kellogg, Michael Klein, @kdenhartog-sybil1,
Paul Knowles, @ktobich, David I. Lehn, Charles E. Lehner, Michael Lodder,
@mooreT1881, Dave Longley, Tobias Looker, Wolf McNally, Robert Mitwicki, Mircea
Nistor, Grant Noble, Mark Nottingham, @oare, Darrell O'Donnell, Vinod Panicker,
Dirk Porsche, Praveen, Mike Prorock, @pukkamustard, Drummond Reed, Julian
Reschke, Yancy Ribbens, Justin Richer, Rieks, @rknobloch, Mikeal Rogers,
Evstifeev Roman, Troy Ronda, Leonard Rosenthol, Michael Ruminer, Markus
Sabadello, Cihan Saglam, Samu, Rob Sanderson, Wendy Seltzer, Mehran Shakeri,
Jaehoon (Ace) Shim, Samuel Smith, James M Snell, SondreB, Manu Sporny, @ssstolk,
Orie Steele, Shigeya Suzuki, Sammotic Switchyarn, @tahpot, Oliver Terbu, Ted
Thibodeau Jr., Joel Thorstensson, Tralcan, Henry Tsai, Rod Vagg, Mike Varley,
Kaliya "Identity Woman" Young, Eric Welton, Fuqiao Xue, @Yue, Dmitri Zagidulin,
@zhanb, and Brent Zundel.