Controller Documents 1.0

Abstract

A controller document contains cryptographic material and identifies service endpoints that can be used to verify proofs from, and interact with, the controller of an identifier.

This section is non-normative.

Controller documents enable the verification of proofs created by the controller of an identifier. They provide verification methods that express public cryptographic material, such as public keys, for verifying proofs created by the controller of the identifier for specific purposes, such as authentication, attestation, key agreement (for encryption), and capability invocation and delegation. Controller documents also provide services related to the identifier, for example to request additional information for verification.

In other words, the controller document contains the information necessary to communicate with, and/or prove that specific actions were taken by, the controller of an identifier, including material for cryptographic proofs and service endpoints for additional communications.

It is expected that other specifications, such as Decentralized Identifiers (DIDs) v1.0, will profile the features that are defined in this specification, requiring and/or recommending the use of some and prohibiting and/or deprecating the use of others.

The use cases below illustrate the need for this specification. While many other related use cases exist, such as those in Use Cases and Requirements for Decentralized Identifiers and Verifiable Credentials Use Cases, those described below are the main scenarios that this specification is designed to address.

Lemmy runs multiple enterprise portals that manage large amounts of sensitive data submitted by people working for a variety of organizations. He would like to use identifiers for entities in the databases that are provided by his customers and do not depend on easily phishable information such as email addresses and passwords.

Lemmy would like to ensure that his customers prove control over their identifiers — for example, by using public/private key cryptography — in order to increase security related to who is allowed to access and update each organization's data.

Stef, who operates a high security service, would like to ensure that certain cryptographic keys used by his customers can only be used for specific purposes (such as encryption, authorization, and/or authentication) to enable different levels of access and protection for each type of cryptographic key.

Marge, a software developer, would like to publicly advertise ways in which other people on the Web can reach her through various communication services she uses based on her globally unique identifier(s).

Cory, a systems architect, would like to extend the use cases described in this section in a way that provides new functionality without creating conflicts with extensions being added by others.

Neru would like to issue digital credentials on behalf of her company that contain claims about their employees. The claims that are made need to use identifiers that are cryptographically attributable back to Neru's company and need to allow for the holder's of those credentials to be able to cryptographically authenticate themselves when they present the credential.

The following requirements are derived from the use cases described earlier in this specification. Additional requirements which could lead to a more decentralized solution can be found in Use Cases and Requirements for Decentralized Identifiers.

1. Guaranteed Unique Identifier: Identifiers are globally unique with no possibility of duplication.
2. Proof of Control: It is possible to prove that the entity claiming control over the identifier is indeed its controller.
3. Associated cryptographic material: The identifier is tightly coupled with cryptographic material that an entity can use to prove control over that identifier.
4. Streamlined key rotation: Entities denoted by designated identifiers can update authentication materials without direct intervention by requesting parties and with minimal individual interaction.
5. Service endpoint discovery: These identifiers allow requesting parties to look up available service endpoints for interacting with the subject of the identifier.
6. Delegation of control: The controller of the identifier is able to delegate that control, in full and/or in part, to a third party.
7. Cryptographically future-proof: These identifiers and associated information are capable of being updated as technology evolves. Current cryptographic techniques are known to be susceptible to quantum computational attacks. Future-proofed identifiers provide a means by which to continue using the same identifier with updated, advanced authentication and/or authorization technologies.
8. Cryptographic authentication and communication: These identifiers enable the use of cryptographic techniques that can be employed to authenticate individuals and/or to secure communications with the subject of the identifier, typically using public-private key pairs.
9. Legally recognizable identification: These identifiers can be used as a basis for credentials and transactions that can be recognized as legally valid under one or more jurisdictions.
10. Human-centered interoperability: Decentralized identifiers need to be easy to use by people with no technical expertise or specialist knowledge.

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 defines the terms used in this specification. A link to the relevant definition is included whenever one of these terms appears in this specification.

authentication

A process by which an entity can prove to a verifier that it has a specific attribute or controls a specific secret.

authorization

A process by which an entity can prove to a verifier that it is allowed to perform a specific activity.

controller

An entity that is authorized to perform an action with a specific resource, such as update a controller document or use a cryptographic key to generate a digital signature.

controller document

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.

cryptographic suite

A means of using specific cryptographic primitives to achieve a particular security goal. These suites can specify verification methods, digital signature types, their identifiers, and other related properties.

private key

Cryptographic material that can be used to generate digital proofs.

public key

Cryptographic material that can be used to verify digital proofs created with a corresponding private key.

subject

The entity identified by the id property in a controller document. Anything can be a subject: person, group, organization, physical thing, digital thing, logical thing, etc.

verification method

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

verification relationship

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.

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

The identifier for a particular subject is expressed using the id property in the controller document.

id: The value of 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.

Example 3

{
  "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: The 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.

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

Note: Authentication versus Authorization

Note that the definition of authentication is different from the definition of authorization. Generally speaking, authentication answers the question of "Who is this?" while authorization answers the question of "Are they allowed to perform this action?". The authentication property in this specification is used to, unsurprisingly, perform authentication while the other verification relationships such as capabilityDelegation and capabilityInvocation are used to perform authorization. Since successfully performing authorization might have more serious effects on a system, controllers are urged to use different verification methods when performing authentication versus authorization and provide stronger access protection for verification methods used for authorization versus authentication. 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: 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 subject or associated entities. A service can be any type of service the subject 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.10 Service Endpoints for Authentication and Authorization.

Example 5: Usage of the service property

{
  "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 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.

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.
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",
    "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": ...
  }]
}

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 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. 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", // external (property value)
    "controller": "https://controller.example/123456789abcdefghi",
    "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": "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 contain the string 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://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

The value of the type property MUST contain the string 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).

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.

Example 11: Embedding and referencing verification methods

    {
...

      "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 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: 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",
    "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
    "https://controller.example/123456789abcdefghi#keys-1",
    // this method is *only* approved for authentication, 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 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 (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 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",
    "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
    "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 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",
    // 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: 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, 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.

Example 15: Capability invocation property containing two verification methods

{
  "@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: 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",
    "https://w3id.org/security/multikey/v1"
  ],
  "id": "https://controller.example/123456789abcdefghi",
  ...
  "capabilityDelegation": [
    // this method can be used to perform capability delegation
    "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 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 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 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.

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.

Initialize the following variables; zeroes to 0, length to 0, begin to 0, and end to the length of bytes.
Set begin and zeroes to the number of leading 0 byte values in bytes.
Set baseValue to an empty byte array that is the size of the final base-expanded value. Calculate the final size of baseValue by dividing log(256) by log(targetBase) and then multiplying the length of bytes minus the leading zeroes. Add 1 to the value of size.
Process each byte in bytes as byte starting at offset begin:
1. Set the carry value to byte.
2. Perform base-expansion by starting at the end of the baseValue array. Initialize an iterator i to 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.
  1. Multiply the value in baseValue[basePosition] by 256 and add it to carry.
  2. Set the value at baseValue[basePosition] to the remainder after dividing carry by targetBase.
  3. Set the value of carry to carry divided by targetBase ensuring that integer division is used to perform the division.
  4. Decrement basePosition by 1 and increment i by 1.
3. Set length to i and increment begin by 1.
Set the baseEncodingPosition to size minus length. While the baseEncodingPosition does not equal size and the baseValue[baseEncodingPosition] does not equal 0, increment baseEncodingPosition. This step skips the leading zeros in the base-encoded result.
Initialize the baseEncoding by repeating the first entry in the baseAlphabet by the value of zeroes (the number of leading zeroes in bytes).
Convert the rest of the baseValue to the base-encoding. While the baseEncodingPosition is less than size, increment the baseEncodingPosition: Set baseEncodedValue to baseValue[baseEncodingPosition]. Append baseAlphabet[baseEncodedValue] to baseEncoding.
Return baseEncoding as the base-encoded value.

Example 17: An implementation of the general base-encoding algorithm above in Javascript

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.

Initialize a baseMap mapping by associating each character in baseAlphabet to its integer position in the baseAlphabet string.
Initialize the following variables; sourceOffset to 0, zeroes to 0, and decodedLength to 0.
Set zeroes and sourceOffset to the number of leading baseAlphabet[0] values in sourceEncoding.
Set decodedBytes to an empty byte array that is the size of the final base-converted value. Calculate the size of decodedBytes by dividing log(sourceBase) by log(256) and then multiplying by the length of sourceEncoding minus the leading zeroes. Add 1 to the value of size.
Process each character in sourceEncoding as character starting at offset sourceOffset:
1. Set the carry value to the integer value in the baseMap that is associated with character.
2. Perform base-decoding by starting at the end of the decodedBytes array. Initialize an iterator i to 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:
  1. Add the result of multiplying sourceBase by decodedBytes[byteOffset] to carry.
  2. Set decodedBytes[byteOffset] to the remainder of dividing carry by 256.
  3. Set carry to carry divided by 256, ensuring that integer division is used to perform the division.
  4. Decrement byteOffset by 1 and increment i by 1.
3. Set decodedLength to i and increment sourceOffset by 1.
Set the decodedOffset to decodedSize minus decodedLength. While the decodedOffset does not equal the decodedSize and decodedBytes[decodedOffset] equals 0, increment decodedOffset by 1. This step skips the leading zeros in the final base-decoded byte array.
Set the size of the finalBytes array to zeroes plus, decodedSize minus decodedOffset. Initialize the first zeroes bytes in finalBytes to 0.
Starting at an offset equal to the number of zeroes in finalBytes plus 1, copy all bytes in decodedBytes, up to decodedSize, starting at offset decodedOffset to finalBytes.

Example 18: An implementation of the general base-decoding algorithm above in Javascript

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 identifier (vmIdentifier), a verification relationship (verificationRelationship), and a set of dereferencing options (options). A verification method is produced as output.

If vmIdentifier is not a valid URL, an error MUST be raised and SHOULD convey an error type of INVALID_VERIFICATION_METHOD_URL.
Let controllerDocumentUrl be the result of parsing vmIdentifier according to the rules of the URL scheme and extracting the primary resource identifier (without the fragment identifier).
Let vmFragment be the result of parsing vmIdentifier according to the rules of the URL scheme and extracting the secondary resource identifier (the fragment identifier).
Let controllerDocument be the result of dereferencing controllerDocumentUrl, according to the rules of the URL scheme and using the supplied options.
If controllerDocument is not a conforming controller document, an error MUST be raised and SHOULD convey an error type of INVALID_CONTROLLER_DOCUMENT.
If controllerDocument.id does not match the controllerDocumentUrl, an error MUST be raised and SHOULD convey an error type of INVALID_CONTROLLER_DOCUMENT_ID.
Let verificationMethod be the result of dereferencing the vmFragment from the controllerDocument according to the rules of the media type of the controllerDocument.
If verificationMethod is not a conforming verification method, an error MUST be raised and SHOULD convey an error type of INVALID_VERIFICATION_METHOD.
If the absolute URL value of verificationMethod.id does not equal vmIdentifier, an error MUST be raised and SHOULD convey an error type of INVALID_VERIFICATION_METHOD.
If the absolute URL value of verificationMethod.controller does not equal controllerDocumentUrl, an error MUST be raised and SHOULD convey an error type of INVALID_VERIFICATION_METHOD.
If verificationMethod is not associated, either by reference (URL) or by value (object), with the verification relationship array in the controllerDocument identified by verificationRelationship, an error MUST be raised and SHOULD convey an error type of INVALID_RELATIONSHIP_FOR_VERIFICATION_METHOD.
Return verificationMethod as the verification method.

The following example provides a minimum conformant controller document containing a minimum conformant verification method as required by the algorithm in this section:

Example 19: Minimum conformant controller document

{
  "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"]
}

Note: Controller documents can contain references to external verification methods

Verification method identifiers are expressed as strings that are URLs, or via the id property, whose value is a URL. It is possible for a controller document to express a verification method, through a verification relationship, that exists in a place that is external to the controller document. As described in Section 5.8 Integrity Protection of Controllers, specifying a verification method that is external to a controller document is a valid use of this specification. It is vital that this verification method is retrieved from the external controller document.

When retrieving any verification method the algorithm above is used to ensure that the verification method is retrieved from the correct controller document. The algorithm also ensures that this controller document refers to the verification method (via a verification relationship) and that the verification method refers to the controller document (via the verification method's controller property). Failure to use this algorithm, or an equivalent one that performs these checks, can lead to security compromises where an attacker poisons a cache by claiming control of a victim's verification method.

Example 20: Referencing an external verification method for `capabilityInvocation`

{
  "id": "https://controller.example/123",
  "capabilityInvocation": ["https://external.example/xyz#key-789"]
}

In the example above, the algorithm described in this section will use the https://external.example/xyz#key-789 URL value as the verification method identifier. The algorithm will then confirm that the verification method exists in the external controller document and that the appropriate relationships exist as described earlier in this section.

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:

The 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.
The code value MUST be the integer code described in the table below (in parentheses, beside the type name).
The title value SHOULD provide a short but specific human-readable string for the error.
The detail value SHOULD provide a longer human-readable string for the error.

INVALID_VERIFICATION_METHOD_URL (-21): The verificationMethod value in a proof was malformed. See Section 3.3 Retrieve Verification Method.
INVALID_CONTROLLER_DOCUMENT_ID (-22): The id value in a controller document was malformed. See Section 3.3 Retrieve Verification Method.
INVALID_CONTROLLER_DOCUMENT (-23): The controller document was malformed. See Section 3.3 Retrieve Verification Method.
INVALID_VERIFICATION_METHOD (-24): The verification method in a controller document was malformed. See Section 3.3 Retrieve Verification Method.
INVALID_RELATIONSHIP_FOR_VERIFICATION_METHOD (-25): The verification method in a controller document was not associated using the expected verification relationship as expressed in the proofPurpose property in the proof. See Section 3.3 Retrieve Verification Method.

Media Type	Description and Hash
application/ld+json	The vocabulary in JSON-LD format [JSON-LD11]. SHA2-256 Digest: `10a012489a3abe38f9871b986f27fbfa49a54d8d9edbe857a60bb2ce7baed416`
text/turtle	The vocabulary in Turtle format [TURTLE]. SHA2-256 Digest: `2f7e055d789cbde920ac0279bfd147f56e07140811abcf273a8d8164a4afdfcb`
text/html	The vocabulary in HTML+RDFa Format [HTML-RDFA]. SHA2-256 Digest: `eeea4710c7cb7640bb70f9d016e86eab7dc06ab804dc70057cc7c05cce1f8489`

Context URL and Hash
URL: https://www.w3.org/ns/controller/v1 SHA2-256 Digest: `ea216ecc1cb02cd39b693dba2250141e270ba0bf95890be107dd9a9e8e43de85`

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

Multiformats enable self-describing data; if data is known to be a Multiformat, its exact type can be determined by reading a few compact header bytes that are expressed at the beginning of the data. Multibase, Multihash, and Multikey are types of Multiformats that are defined by this specification.

The Multiformats specifications exist because application developers appropriately choose different base-encoding functions, cryptographic hashing functions, and cryptographic key formats, among other things, based on different use cases and their requirements. No single base-encoding function, cryptographic hashing function, or cryptographic key format in the world has ever satisfied all requirement sets. Multiformats provides an alternative means by which to encode and/or detect any base-encoding, cryptographic hash, or cryptographic key format in self-documenting data and documents.

To increase interoperability, specification authors are urged to minimize the number of Multiformats — optimally, choosing only one — to be used for any particular application or ecosystem.

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.

If a controller document publishes a service intended for authentication or authorization of the subject (see Section 2.1.4 Services), it is the responsibility of the service provider, subject, and/or requesting party to comply with the requirements of the authentication and/or authorization protocols supported by that service endpoint.

Controller Documents 1.0

Abstract

Status of This Document

1. Introduction

1.1 Use Cases

Globally Unique Identifiers

Cryptographic Verification

Cryptographic Purpose

Service Engagement

Extensibility

Issue and Present Claims

1.2 Requirements

1.3 Conformance

1.4 Terminology

2. Data Model

2.1 Controller Documents

2.1.1 Subjects

2.1.2 Controllers

2.1.3 Also Known As

2.1.4 Services

2.2 Verification Methods

2.2.1 Verification Material

2.2.2 Multikey

2.2.3 JsonWebKey

2.2.4 Referring to Verification Methods

2.3 Verification Relationships

2.3.1 Authentication

2.3.2 Assertion

2.3.3 Key Agreement

2.3.4 Capability Invocation

2.3.5 Capability Delegation

2.4 Multibase

2.5 Multihash

3. Algorithms

3.1 Base Encode

3.2 Base Decode

3.3 Retrieve Verification Method

3.4 Processing Errors

4. Contexts and Vocabularies

4.1 Vocabulary

4.2 JSON-LD context

4.2.1 Context Injection

4.3 Datatypes

4.3.1 The multibase Datatype

5. Security Considerations

5.1 Proving Control and Binding

5.1.1 Proving Control of an Identifier and/or Controller Document

5.1.2 Binding to Physical Identity

5.2 Key and Signature Expiration

5.3 Verification Method Rotation

5.4 Verification Method Revocation

5.4.1 Revocation Semantics

5.5 Choosing a Multiformat

5.6 Encrypted Data in Controller Documents

5.7 Content Integrity Protection

5.8 Integrity Protection of Controllers

5.9 Level of Assurance

5.10 Service Endpoints for Authentication and Authorization

6. Privacy Considerations

6.1 Keep Personal Data Private

6.2 Relationship to the Same-Origin Policy

6.3 Identifier Correlation Risks

6.4 Controller Document Correlation Risks

6.5 Subject Classification

6.6 Service Privacy

7. Accessibility Considerations

7.1 Presenting Time Values

A. Examples

A.1 Multikey Examples

A.2 JsonWebKey Examples

B. Revision History

C. Acknowledgements

D. References

D.1 Normative references

D.2 Informative references

4.3.1 The `multibase` Datatype