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.

Data Model

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.

Add examples of common Controller documents.

The property names `id`, `type`, and `controller` can be present in map of different types with possible differences in constraints.

Controller Documents

The following sections define the properties in a [=controller document=], including whether these properties are required or optional. These properties describe relationships between the [=subject=] and the value of the property.

The following tables contain informative references for the core properties defined by this specification, with expected values, and whether or not they are required. The property names in the tables are linked to the normative definitions and more detailed descriptions of each property.

Property	Required?	Value constraints
`id`	yes	A string that conforms to the URL syntax defined in Section [[[#subjects]]].
`alsoKnownAs`	no	A set of strings that conform to the rules of [[RFC3986]] for URIs as defined in Section [[[#also-known-as]]].
`controller`	no	A string or a set of strings, each of which conforms to the URL syntax defined in the [[[URL]]] as defined in Section [[[#controllers]]].
`verificationMethod`	no	A set of [=verification method=] maps that conform to the rules in Section [[[#verification-methods]]].
`authentication`	no	A set of [=verification method=] maps that conform to the rules in Section [[[#authentication]]]; or a a set of strings, each of which conforms to the URL syntax defined in the [[[URL]]].
`assertionMethod`	no	A set of [=verification method=] maps that conform to the rules in Section [[[#assertion]]]; or a a set of strings, each of which conforms to the URL syntax defined in the [[[URL]]].
`keyAgreement`	no	A set of [=verification method=] maps that conform to the rules in Section [[[#key-agreement]]]; or a a set of strings, each of which conforms to the URL syntax defined in the [[[URL]]].
`capabilityInvocation`	no	A set of [=verification method=] maps that conform to the rules in Section [[[#capability-invocation]]]; or a a set of strings, each of which conforms to the URL syntax defined in the [[[URL]]].
`capabilityDelegation`	no	A set of [=verification method=] maps that conform to the rules in Section [[[#capability-delegation]]]; or a a set of strings, each of which conforms to the URL syntax defined in the [[[URL]]].

Subjects

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

A [=controller document=] MUST contain an `id` value in the root map.

{
  "id": "https://controller.example/123"
}

The `id` property only denotes the identifier of the [=subject=] when it is present in the topmost map of the [=controller document=].

Controllers

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]]]. The corresponding [=controller document=](s) SHOULD contain [=verification relationships=] that explicitly permit the use of certain [=verification methods=] for specific purposes. If the `controller` property is not present, the value expressed by the `id` property MUST be treated as if it were also set as the value of the `controller` property.

When a `controller` property is present in a [=controller document=], its value expresses one or more identifiers. Any [=verification methods=] contained in the [=controller documents=] for those identifiers SHOULD be accepted as authoritative, such that proofs that satisfy those [=verification methods=] are considered equivalent to proofs provided by the [=subject=].

{
  "@context": "https://www.w3.org/ns/controller/v1",
  "id": "https://controller1.example/123",
  "controller": "https://controllerB.example/abc",
}

Note that authorization provided by the value of `controller` is separate from authentication as described in Section [[[#authentication]]]. This is particularly important for key recovery in the cases of cryptographic key loss, where the [=subject=] no longer has access to their keys, or cryptographic key compromise, where the [=controller=]'s trusted third parties need to override malicious activity by an attacker. See [[[#security-considerations]]] for information related to threat models and attack vectors.

Also Known As

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.

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.

Verification Methods

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 [[[#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.
controller: The value of the `controller` property MUST be a string that conforms to the [[URL]] syntax.
revoked: The `revoked` property is OPTIONAL. If present, it MUST be an [[XMLSCHEMA11-2]] `dateTimeStamp` string specifying when the [=verification method=] SHOULD cease to be used. Once the value is set, it is not expected to be updated, and systems depending on the value are expected to not verify any proofs associated with the [=verification method=] at or after the time of revocation.

    {
      "@context": [
        "https://www.w3.org/ns/controller/v1",
        "https://www.w3.org/ns/credentials/v2",
        "https://w3id.org/security/jwk/v1",
        "https://w3id.org/security/data-integrity/v2"
      ]
      "id": "https://controller.example/123456789abcdefghi",
      ...
      "verificationMethod": [{
        "id": ...,
        "type": ...,
        "controller": ...,
        "publicKeyJwk": ...
      }, {
        "id": ...,
        "type": ...,
        "controller": ...,
        "publicKeyMultibase": ...
      }]
    }

The semantics of the `controller` property are the same when the subject of the relationship is the [=controller document=] as when the subject of the relationship is a [=verification method=], such as a cryptographic public key. Since a key can't control itself, and the key controller cannot be inferred from the [=controller document=], it is necessary to explicitly express the identity of the controller of the key. The difference is that the value of `controller` for a [=verification method=] is not necessarily a [=controller=]. [=Controllers=] are expressed using the `controller` property at the highest level of the [=controller document=].

Verification Material

Verification material is any information that is used by a process that applies a [=verification method=]. The `type` of a [=verification method=] is expected to be used to determine its compatibility with such processes. Examples of verification methods include `JsonWebKey` and `Multikey`. A [=cryptographic suite=] specification is responsible for specifying the [=verification method=] `type` and its associated verification material format. For examples, see Securing Verifiable Credentials using JOSE and COSE, the Data Integrity ECDSA Cryptosuites and the Data Integrity EdDSA Cryptosuites.

To increase the likelihood of interoperable implementations, this specification limits the number of formats for expressing verification material in a [=controller document=]. The fewer formats that implementers have to implement, the more likely it will be that they will support all of them. This approach attempts to strike a delicate balance between easing implementation and providing support for formats that have historically had broad deployment.

A [=verification method=] MUST NOT contain multiple verification material properties for the same material. For example, expressing key material in a [=verification method=] using both `publicKeyJwk` and `publicKeyMultibase` at the same time is prohibited.

Implementations MAY convert keys between formats as desired for operational purposes or to interface with cryptographic libraries. As an internal implementation detail, such conversion MUST NOT affect the external representation of key material.

An example of a [=controller document=] containing verification methods using both properties above is shown below.

    {
      "@context": [
        "https://www.w3.org/ns/controller/v1",
        "https://www.w3.org/ns/credentials/v2",
        "https://w3id.org/security/jwk/v1",
        "https://w3id.org/security/multikey/v1"
      ]
      "id": "https://controller.example/123456789abcdefghi",
      ...
      "verificationMethod": [{
        "id": "https://controller.example/123#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
        "type": "JsonWebKey", // external (property value)
        "controller": "https://controller.example/123",
        "publicKeyJwk": {
          "crv": "Ed25519", // external (property name)
          "x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOyPVQaO3FxVeQ", // external (property name)
          "kty": "OKP", // external (property name)
          "kid": "_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A" // external (property name)
        }
      }, {
        "id": "https://controller.example/123456789abcdefghi#keys-1",
        "type": "Multikey", // external (property value)
        "controller": "did:example:pqrstuvwxyz0987654321",
        "publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
      }],
      ...
    }

Multikey

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 [[[#multibase-0]]].

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 [[[#multibase-0]]].
secretKeyMultibase: The `secretKeyMultibase` property is OPTIONAL. If present, its value MUST be a Multibase encoded value as described in Section [[[#multibase-0]]].

The example below expresses an Ed25519 public key using the format defined above:

{
  "@context": ["https://w3id.org/security/multikey/v1"],
  "id": "https://controller.example/123456789abcdefghi#keys-1",
  "type": "Multikey",
  "controller": "https://controller.example/123456789abcdefghi",
  "publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
}

The public key values are expressed using the rules in the table below:

Key type	Description
ECDSA 256-bit public key	The Multikey encoding of a P-256 public key MUST start with the two-byte prefix `0x8024` (the varint expression of `0x1200`) followed by the 33-byte compressed public key data. The resulting 35-byte value MUST then be encoded using the base-58-btc alphabet, according to Section [[[#multibase-0]]], 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 [[[#multibase-0]]], 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 [[[#multibase-0]]], 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 [[[#multibase-0]]], 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 [[[#multibase-0]]], 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 [[[#multibase-0]]], 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 [[[#multibase-0]]], 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 [[[#multibase-0]]], 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.

JsonWebKey

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 public key fingerprint [[RFC7638]]. See the first key in [[[#example-various-verification-method-types]]] 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:

{
  "id": "https://controller.example/123456789abcdefghi#key-1",
  "type": "JsonWebKey",
  "controller": "https://controller.example/123456789abcdefghi",
  "publicKeyJwk": {
      "kid": "key-1",
      "kty": "EC",
      "crv": "P-384",
      "alg": "ES384",
      "x": "1F14JSzKbwxO-Heqew5HzEt-0NZXAjCu8w-RiuV8_9tMiXrSZdjsWqi4y86OFb5d",
      "y": "dnd8yoq-NOJcBuEYgdVVMmSxonXg-DU90d7C4uPWb_Lkd4WIQQEH0DyeC2KUDMIU"
    }
}

In the example above, the `publicKeyJwk` value contains the JSON Web Key. The `kty` property encodes the key type of "OKP", which means "Octet string key pairs". The `alg` property identifies the algorithm intended for use with the public key, which in this case is `ES384`. The `crv` property identifies the particular curve type of the public key, `P-384`. The `x` property specifies the point on the P-384 curve that is associated with the public key.

The `publicKeyJwk` property MUST NOT contain any property marked as "Private" or "Secret" in any registry contained in the JOSE Registries [[JOSE-REGISTRIES]], including "d".

The JSON Web Key data model is also capable of encoding secret keys, sometimes referred to as private keys.

{
  "id": "https://controller.example/123456789abcdefghi#key-1",
  "type": "JsonWebKey",
  "controller": "https://controller.example/123456789abcdefghi",
  "secretKeyJwk": {
      "kty": "EC",
      "crv": "P-384",
      "alg": "ES384",
      "d": "fGwges0SX1mj4eZamUCL4qtZijy9uT15fI4gKTuRvre4Kkoju2SHM4rlFOeKVraH",
      "x": "1F14JSzKbwxO-Heqew5HzEt-0NZXAjCu8w-RiuV8_9tMiXrSZdjsWqi4y86OFb5d",
      "y": "dnd8yoq-NOJcBuEYgdVVMmSxonXg-DU90d7C4uPWb_Lkd4WIQQEH0DyeC2KUDMIU"
    }
}

The private key example above is almost identical to the previous example of the public key, except that the information is stored in the `secretKeyJwk` property (rather than the `publicKeyJwk`), and the private key value is encoded in the `d` property thereof (alongside the `x` property, which still specifies the point on the Ed25519 curve that is associated with the public key).

Referring to Verification Methods

[=Verification methods=] can be embedded in or referenced from properties associated with various [=verification relationships=] as described in [[[#verification-relationships]]]. Referencing [=verification methods=] allows them to be used by more than one [=verification relationship=].

If the value of a [=verification method=] property is a map, the [=verification method=] has been embedded and its properties can be accessed directly. However, if the value is a URL string, the [=verification method=] has been included by reference and its properties will need to be retrieved from elsewhere in the [=controller document=] or from another [=controller document=]. This is done by dereferencing the URL and searching the resulting resource for a [=verification method=] map with an `id` property whose value matches the URL.

    {
...

      "authentication": [
        // this key is referenced and might be used by
        // more than one verification relationship
        "https://controller.example/123456789abcdefghi#keys-1",
        // this key is embedded and may *only* be used for authentication
        {
          "id": "https://controller.example/123456789abcdefghi#keys-2",
          "type": "Multikey", // external (property value)
          "controller": "https://controller.example/123456789abcdefghi",
          "publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
        }
      ],

...
    }

Verification Relationships

A [=verification relationship=] expresses the relationship between the [=controller=] and a [=verification method=].

Different [=verification relationships=] enable the associated [=verification methods=] to be used for different purposes. It is up to a verifier to ascertain the validity of a verification attempt by checking that the [=verification method=] used is contained in the appropriate [=verification relationship=] property of the [=controller document=].

The [=verification relationship=] between the [=controller=] and the [=verification method=] is explicit in the [=controller document=]. [=Verification methods=] that are not associated with a particular [=verification relationship=] cannot be used for that [=verification relationship=]. For example, a [=verification method=] in the value of the `[=authentication=]` property cannot be used to engage in key agreement protocols with the [=controller=] — the value of the `keyAgreement` property needs to be used for that.

The [=controller document=] does not express revoked keys using a verification relationship. If a referenced verification method is not in the latest [=controller document=] used to dereference it, then that verification method is considered invalid or revoked.

The following sections define several useful [=verification relationships=]. A [=controller document=] MAY include any of these, or other properties, to express a specific [=verification relationship=]. To maximize global interoperability, any such properties used SHOULD be registered in the VC Specifications Directory.

Authentication

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.

    {
      "@context": [
        "https://www.w3.org/ns/controller/v1",
        "https://www.w3.org/ns/credentials/v2",
        "https://w3id.org/security/multikey/v1"
      ],
      "id": "https://controller.example/123456789abcdefghi",
      ...
      "authentication": [
        // this method can be used to authenticate as did:...fghi
        "https://controller.example/123456789abcdefghi#keys-1",
        // this method is *only* approved for authentication, it may not
        // be used for any other proof purpose, so its full description is
        // embedded here rather than using only a reference
        {
          "id": "https://controller.example/123456789abcdefghi#keys-2",
          "type": "Multikey",
          "controller": "https://controller.example/123456789abcdefghi",
          "publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
        }
      ],
      ...
    }

If authentication is established, it is up to the application to decide what to do with that information.

This is useful to any authentication verifier that needs to check to see if an entity that is attempting to [=authenticate=] is, in fact, presenting a valid proof of authentication. When a verifier receives some data (in some protocol-specific format) that contains a proof that was made for the purpose of "authentication", and that says that an entity is identified by the `id`, then that verifier checks to ensure that the proof can be verified using a [=verification method=] (e.g., [=public key=]) listed under `authentication` in the [=controller document=].

Note that the [=verification method=] indicated by the `authentication` property of a [=controller document=] can only be used to [=authenticate=] the [=controller=]. To [=authenticate=] a different [=controller=], the entity associated with the value of `controller` needs to [=authenticate=] with its own [=controller document=] and associated `authentication` [=verification relationship=].

Assertion

The `assertionMethod` [=verification relationship=] is used to specify how the [=controller=] is expected to express claims, such as for the purposes of issuing a verifiable credential.

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

    {
      "@context": [
        "https://www.w3.org/ns/controller/v1",
        "https://www.w3.org/ns/credentials/v2",
        "https://w3id.org/security/multikey/v1"
      ],
      "id": "https://controller.example/123456789abcdefghi",
      ...
      "assertionMethod": [
        // this method can be used to assert statements as did:...fghi
        "https://controller.example/123456789abcdefghi#keys-1",
        // this method is *only* approved for assertion of statements, it is not
        // used for any other verification relationship, so its full description is
        // embedded here rather than using a reference
        {
          "id": "https://controller.example/123456789abcdefghi#keys-2",
          "type": "Multikey", // external (property value)
          "controller": "https://controller.example/123456789abcdefghi",
          "publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
        }
      ],
      ...
    }

Key Agreement

The `keyAgreement` [=verification relationship=] is used to specify how an entity can generate encryption material in order to transmit confidential information intended for the [=controller=], such as for the purposes of establishing a secure communication channel with the recipient.

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

    {
      "@context": "https://www.w3.org/ns/did/v1",
      "id": "https://controller.example/123456789abcdefghi",
      ...
      "keyAgreement": [
        // this method can be used to perform key agreement as did:...fghi
        "https://controller.example/123456789abcdefghi#keys-1",
        // this method is *only* approved for key agreement usage, 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/123#zC9ByQ8aJs8vrNXyDhPHHNNMSHPcaSgNpjjsBYpMMjsTdS",
          "type": "X25519KeyAgreementKey2019", // external (property value)
          "controller": "https://controller.example/123",
          "publicKeyMultibase": "z6LSn6p3HRxx1ZZk1dT9VwcfTBCYgtNWdzdDMKPZjShLNWG7"
        }
      ],
      ...
    }

Capability Invocation

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.

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

Capability Delegation

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 [[[#capability-invocation]]].

    {
      "@context": [
        "https://www.w3.org/ns/controller/v1",
        "https://w3id.org/security/multikey/v1"
      ],
      "id": "https://controller.example/123456789abcdefghi",
      ...
      "capabilityDelegation": [
        // this method can be used to perform capability delegation as did:...fghi
        "https://controller.example/123456789abcdefghi#keys-1",
        // this method is *only* approved for granting capabilities; it will not
        // be used for any other verification relationship, so its full description is
        // embedded here rather than using only a reference
        {
        "id": "https://controller.example/123456789abcdefghi#keys-2",
        "type": "Multikey", // external (property value)
        "controller": "https://controller.example/123456789abcdefghi",
        "publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
        }
      ],
      ...
    }

Multibase

A Multibase string includes a single character header which identifies the base and encoding alphabet used to encode a binary value, followed by the encoded binary value (using that base and alphabet). The common Multibase header values and their associated base encoding alphabets as provided below are normative:

Multibase Header	Description
`u`	The base-64-url-no-pad alphabet is used to encode the bytes. The base-alphabet consists of the following characters, in order: `ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_`
`z`	The base-58-btc alphabet is used to encode the bytes. The base-alphabet consists of the following characters, in order: `123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`

Other Multibase encoding values MAY be used, but interoperability is not guaranteed between implementations using such values.

To base-encode a binary value into a Multibase string, an implementation MUST apply the algorithm in Section [[[#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 [[[#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.

Multihash

A Multihash value starts with a binary header, which includes 1) an identifier for the specific cryptographic hash algorithm, 2) the length of the cryptographic hash, and 3) the value of the cryptographic hash. The normative Multihash header values defined by this specification, and their associated output sizes and associated specifications, are provided below:

Multihash Identifier	Multihash Header	Description
`sha2-256`	`0x12`	SHA-2 with 256 bits (32 bytes) of output, as defined by [[RFC6234]].
`sha2-384`	`0x20`	SHA-2 with 384 bits (48 bytes) of output, as defined by [[RFC6234]].
`sha3-256`	`0x16`	SHA-3 with 256 bits (32 bytes) of output, as defined by [[SHA3]].
`sha3-384`	`0x15`	SHA-3 with 384 bits (48 bytes) of output, as defined by [[SHA3]].

Other Multihash encoding values MAY be used, but interoperability is not guaranteed between implementations.

To encode to a Multihash value, an implementation MUST concatenate the associated Multihash header, the cryptographic hash length, and the cryptographic hash value, in that order.

To decode a Multihash value, an implementation MUST 1) remove the prepended Multihash header value, which identifies the type of cryptographic hashing algorithm, 2) remove the output length, and 3) extract the raw cryptographic hash value which MUST match the expected output length associated with the Multihash header as well as the output length provided in the Multihash value itself.

Algorithms

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.

Base Encode

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.

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;
}

Base Decode

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.

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;
}

Retrieve Verification Method

The following algorithm specifies how to safely retrieve a verification method, such as a cryptographic [=public key=], by using a [=verification method=] identifier. Required inputs are a [=verification method=] (verificationMethod), a proof purpose (proofPurpose), and a set of dereferencing options (options). A verification method is produced as output.

Let vmIdentifier be set to verificationMethod.
Let vmPurpose be set to proofPurpose.
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.id does not match the controllerDocumentUrl, an error MUST be raised and SHOULD convey an error type of INVALID_CONTROLLER_DOCUMENT_ID.
If controllerDocument is not a valid [=controller document=], an error MUST be raised and SHOULD convey an error type of INVALID_CONTROLLER_DOCUMENT.
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 valid [=verification method=], an error MUST be raised and SHOULD convey an error type of INVALID_VERIFICATION_METHOD.
If verificationMethod is not associated with the array of vmPurposes in the controllerDocument, either by reference (URL) or by value (object), an error MUST be raised and SHOULD convey an error type of INVALID_PROOF_PURPOSE_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:

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

Processing Errors

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 [[[#retrieve-verification-method]]].
INVALID_CONTROLLER_DOCUMENT_ID (-22): The `id` value in a [=controller document=] was malformed. See Section [[[#retrieve-verification-method]]].
INVALID_CONTROLLER_DOCUMENT (-23): The [=controller document=] was malformed. See Section [[[#retrieve-verification-method]]].
INVALID_VERIFICATION_METHOD (-24): The [=verification method=] in a [=controller document=] was malformed. See Section [[[#retrieve-verification-method]]].
INVALID_PROOF_PURPOSE_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 [[[#retrieve-verification-method]]].

URL, Media Type, and Content Digest
URL: https://w3id.org/security/data-integrity/v2 (application/ld+json) SHA2-256 Digest:
URL: https://w3id.org/security/multikey/v1 (application/ld+json) SHA2-256 Digest:
URL: https://w3id.org/security/jwk/v1 (application/ld+json) SHA2-256 Digest:

URL, Media Type, and Content Digest
URL: https://w3id.org/security (application/ld+json) SHA2-256 Digest:
URL: https://w3id.org/security (text/turtle) SHA2-256 Digest:
URL: https://w3id.org/security (text/html) SHA2-256 Digest:

Security Considerations

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.

Proving Control and Binding

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 of an Identifier and/or Controller Document

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 and [[[#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.

Binding to Physical Identity

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 [[[#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 [[[#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 [[[?VC-DATA-MODEL-2.0]]].

Key and Signature Expiration

In a decentralized architecture, there might not be centralized authorities to enforce cryptographic material or cryptographic digital signature expiration policies. Therefore, it is with supporting software such as verification libraries that requesting parties validate that cryptographic material were not expired at the time they were used. Requesting parties might employ their own expiration policies in addition to inputs into their verification processes. For example, some requesting parties might accept authentications from five minutes in the past, while others with access to high precision time sources might require authentications to be time stamped within the last 500 milliseconds.

There are some requesting parties that have legitimate needs to extend the use of already-expired cryptographic material, such as verifying legacy cryptographic digital signatures. In these scenarios, a requesting party might instruct their verification software to ignore cryptographic key material expiration or determine if the cryptographic key material was expired at the time it was used.

Verification Method Rotation

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 they add a new verification method that is meant to replace an existing [=verification method=] after some time.

Verification Method Revocation

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.

Revocation Semantics

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

Encrypted Data in Controller Documents

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.

Content Integrity Protection

[=Controller documents=] which include links to external machine-readable content such as images, web pages, or schemas are vulnerable to tampering. It is strongly advised that external links are integrity protected using mechanisms to secure related resources such as those described in the [[[?VC-DATA-MODEL-2.0]]] specification. External links are to be avoided if they cannot be integrity protected and the [=controller document=]'s integrity is dependent on the external link.

One example of an external link where the integrity of the controller document itself could be affected is the JSON-LD Context [[JSON-LD11]]. To protect against compromise, [=controller document=] consumers are advised to cache local static copies of JSON-LD contexts and/or verify the integrity of external contexts against a cryptographic hash that is known to be associated with a safe version of the external JSON-LD Context.

Level of Assurance

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.

Introduction

Terminology

Data Model

Controller Documents

Subjects

Controllers

Also Known As

Verification Methods

Verification Material

Multikey

JsonWebKey

Referring to Verification Methods

Verification Relationships

Authentication

Assertion

Key Agreement

Capability Invocation

Capability Delegation

Multibase

Multihash

Algorithms

Base Encode

Base Decode

Retrieve Verification Method

Processing Errors

Contexts and Vocabularies

Context Injection

Datatypes

The `multibase` Datatype

Security Considerations

Proving Control and Binding

Proving Control of an Identifier and/or Controller Document

Binding to Physical Identity

Key and Signature Expiration

Verification Method Rotation

Verification Method Revocation

Revocation Semantics

Encrypted Data in Controller Documents

Content Integrity Protection

Level of Assurance

Privacy Considerations

Keep Personal Data Private

Identifier Correlation Risks

Controller Document Correlation Risks

Subject Classification

Accessibility Considerations

Presenting Time Values

Examples

Multikey Examples

Revision History

Acknowledgements