Controlled Identifier Document 1.0

Abstract

A controlled identifier document contains cryptographic material and lists service endpoints for the purposes of verifying cryptographic proofs from, and interacting with, the controller of an identifier.

This section is non-normative.

Controlled identifier documents identify a subject and provide verification methods that express public cryptographic material, such as public keys , for verifying proofs created on behalf of the subject for specific purposes, such as authentication, attestation, key agreement (for encryption), and capability invocation and delegation. Controlled identifier documents also list service endpoints related to an identifier ; for example, from which to request additional information for verification.

In other words, the controlled identifier 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 proofs and service endpoints for additional communications.

A controlled identifier document specifies verification relationships and service endpoints for a single identifier, for which the current controlled identifier document is taken as authoritative.

It is expected that other specifications 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.

Issue 2 : Clarify that profiles of this document will happen

The W3C TAG review noted that they would like to see language that clarifies that this document would be useful to authors that would like to profile its usage. The DID Core specification is one such document that does that, but citing it directly received objections. This issue notes that the WG intends to resolve the text below into something that we can achieve consensus on:

For example, the Decentralized Identifiers Specification is expected to define DID documents as a profile of controlled identifier documents, where the DID is the identifier, DID documents are controlled identifier documents, and resolution is the process of retrieving the canonical DID document for a DID.

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 controlled identifier 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 controlled identifier 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.
controlled identifier: A type of identifier that can be proven to be under the control of an entity.
controlled identifier document: A document that contains cryptographic material and lists service endpoints that can be used for verifying proofs from, and interacting with, the controller of an identifier.
controller: An entity that is capable of performing an action with a specific resource, such as updating a controlled identifier document or generating a proof using a verification method .
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 proofs .
proof: A mathematical demonstration that confirms the validity of an assertion. The demonstration consists of a set of properties and values that enable a verifier to cryptographically validate the assertion. A digital signature is a type of proof.
public key: Cryptographic material that can be used to verify proofs created with a corresponding private key .
subject: An entity, such as a person, group, organization, physical thing, digital thing, or logical thing that is referred to by the value of an id property in a controlled identifier document . Subjects identified in a controlled identifier document are also used as a subjects in other contexts, such as during authentication or in verifiable credentials .
verification method: A method and its parameters, used 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 used the associated cryptographic private key.
verification relationship: An expression that one or more verification methods are authorized to verify proofs made on behalf of the subject . One example of a verification relationship is 2.3.1 Authentication .

A controlled identifier document specifies one or more relationships between an identifier and a set of verification methods and/or service endpoints. The controlled identifier document SHOULD contain verification relationships that explicitly permit the use of certain verification methods for specific purposes.

Example 1 : Controlled Identifier 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 : Controlled Identifier Document using publicKeyMultibase and JSON-LD

{
  "@context": "https://www.w3.org/ns/cid/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 controlled identifier document , including whether these properties are required or optional. These properties describe relationships between the subject and the value of the property.

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

Property	Required?	Value constraints	Definition
`id`	yes	A string that conforms to the URL syntax.	2.1.1 Subjects
`controller`	no	A string or a set of strings , each of which conforms to the URL syntax.	2.1.2 Controllers
`alsoKnownAs`	no	A set of strings , each of which conforms to the URL syntax.	2.1.3 Also Known As
`service`	no	A set of service maps .	2.1.4 Services
`verificationMethod`	no	A set of verification method maps .	2.2 Verification Methods
`authentication`	no	A set of strings , each of which conforms to the URL syntax, or a set of verification method maps .	2.3.1 Authentication
`assertionMethod`	no	A set of strings , each of which conforms to the URL syntax, or a set of verification method maps .	2.3.2 Assertion
`keyAgreement`	no	A set of strings , each of which conforms to the URL syntax, or a set of verification method maps .	2.3.3 Key Agreement
`capabilityInvocation`	no	A set of strings , each of which conforms to the URL syntax, or a set of verification method maps .	2.3.4 Capability Invocation
`capabilityDelegation`	no	A set of strings , each of which conforms to the URL syntax, or a set of verification method maps .	2.3.5 Capability Delegation

A subject is expressed using the id property in a controlled identifier document . The value of an id property is referred to as an identifier .

id: The value of id property MUST be a string that conforms to the rules in the URL Standard .

A controlled identifier document MUST contain an id value in the topmost map .

Example 3

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

The value of the id property in the topmost map of the controlled identifier document is called the base identifier for the controlled identifier document . The URL for retrieving the current, authoritative controlled identifier document for a given identifier is called the canonical URL for the controlled identifier document . Dereferencing the canonical URL MUST return the current authoritative controlled identifier document . The returned document's base identifier MUST be the same as the canonical URL ; if it is anything else, then the returned document is not an authoritative controlled identifier document and the identifier SHOULD be treated as invalid. Every controlled identifier document is stored and retrieved according to the canonical URL of the document, which MUST also be the base identifier of the document.

Note : Identifiers are context-dependent

It is expected that the subject referred to by an id in a controlled identifier document will be consistent over time, such that any verifiable credentials that use them can be interpreted as referring to the same entity. For example, it is preferred that an issuer of a verifiable credential require that a subject demonstrate proof of control over their identifier before issuing a credential with that identifier as subject , creating assurance that the same entity was involved in the issuance of each credential with that identifier as subject .

However, there are valid cases where that practice is either impossible or unreasonable; for example, when a parent requests a verifiable credential for their child. There are also cases where an issuer simply makes a mistake or intentionally issues a false statement. All of these possibilities are considered when evaluating the security impacts of reliance on a given identifier for any given purpose. See Section 5.2 Identifier Ambiguity .

A controller of a controlled identifier document is any entity capable of making changes to that controlled identifier document . Whoever can update the content of the resource returned from dereferencing the controller document's canonical URL is, by definition, a controller of the document and its canonical identifier. Proofs that satisfy a controlled identifier document 's verification methods are taken as cryptographic assurance that the controller of the identifier created those proofs .

Note : Identifier Controller versus Document Controller

The controller of the controlled identifier document is taken to be the controller of the document's canonical identifier , also known as its URL. That is, whoever can update the controlled identifier document is both the document controller and the identifier controller . Updating the document is how you control the identifier . These terms can be used interchangeably. Controlling the canonical controlled identifier document for an identifier is the same as controlling the identifier .

controller

The


controller

property is OPTIONAL . If it is possible to represent the legitimate controllers of the document as URLs, the document SHOULD list URLs identifying those controllers.

Note : Presumed Control

It is possible to list a verification method which is functionally under the control of someone other than the controller of the controlled identifier document . For example, a document controller could set a public key under another party's control as an authentication verification method. This would enable the other party to authenticate on behalf of this identifier (because their public key is listed in an authentication verification method) without enabling that party to update the controlled identifier document . However, since the document controller explicitly listed that key for authentication, the proof in question is taken as created by the document controller , as it was created by their explicit assignee. This is especially useful when the "other party" is a device under the control of the document controller, but with a distinct cryptographic authority, i.e., it has its own keystore and can generate proofs . That pattern enables different devices, each using their own cryptographic material, to generate verifiable proofs that are taken as proofs created by controller of the identifier.

If present, its value MUST be a string or a set of strings , each of which conforms to the rules in the URL Standard .

Each entry in the controller property MUST identify an entity capable of updating the canonical version of the controlled identifier document . Subsequent requests for this controlled identifier document through its canonical location will always receive the latest version.

If the controller property is not present, then control of the document is determined entirely by its storage location.

Example 4 : Controlled identifier document with a controller property

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

While the identifier used for a controller is unambiguous, this does not imply that a single entity is always the controller , nor that a controller only has a single identifier. A controller might be a single entity, or a collection of entities, such as a partnership. A controller might also use multiple identifiers to refer to itself, for purposes such as privacy or delineating operational boundaries within an organization. Similarly, a controller might control many verification methods . For these reasons, no assumptions are to be made about a controller being a single entity nor controlling only a single verification method .

Note : Authentication versus Authorization

Note that the definition of authentication is different from the definition of authorization . Generally speaking, authentication answers the question of "Do we know who this is?" 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 controlled identifier document of one subject is also expressed in the reverse direction (i.e., reciprocated) in the controlled identifier 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 controlled identifier documents , is not necessarily appropriate, even with a reciprocal relationship.

Services are used in controlled identifier documents to express ways of communicating with the controller , or associated entities, in relation to the controlled identifier . A service can be any type of service the controller wants to advertise for further discovery, authentication, authorization, or interaction.

Due to privacy concerns, revealing public information through services , such as social media accounts, personal websites, and email addresses, is discouraged. Further exploration of privacy concerns can be found in sections 6.1 Keep Personal Data Private and 6.6 Service Privacy . The information associated with services is often service specific. For example, the information associated with an encrypted messaging service can express how to initiate the encrypted link before messaging begins.

Services are expressed using the service property, which is described below:

service

The service property is OPTIONAL . If present, the associated value MUST be a set of services , where each service is described by a map . Each service map MUST contain id, type, and serviceEndpoint properties. Each service extension MAY include additional properties and MAY further restrict the properties associated with the extension.

id: The id property is OPTIONAL . If present, its value MUST be a URL conforming to URL Standard . A conforming document MUST NOT include multiple service entries with the same id.
type: The type property is REQUIRED . Its value MUST be a string or a set of strings . To maximize interoperability, the service type and its associated properties SHOULD be registered in the Verifiable Credential Extensions .
serviceEndpoint: The serviceEndpoint property is REQUIRED . The value of the serviceEndpoint property MUST be a single string , a single map , or a set composed of one or more strings and/or maps . Each string value MUST be a valid URL conforming to URL Standard .

For more information regarding privacy and security considerations related to services see 6.6 Service Privacy , 6.1 Keep Personal Data Private , 6.4 Controlled Identifier Document Correlation Risks , and 5.11 Service Endpoints for Authentication and Authorization .

Example 5 : Usage of the service property

{
  "service": [{
    "type": "ExampleSocialMediaService",
    "serviceEndpoint": "https://warbler.example/sal674"
  }]
}

A controlled identifier document can express verification methods , such as cryptographic public keys , which can be used to verify proofs , such as those used to authenticate or authorize interactions with the controller or associated parties. For example, a cryptographic public key can be used as a verification method with respect to a digital signature; in such use, it verifies that the signer could use the associated cryptographic private key. Verification methods might take many parameters. An example of this is a set of five cryptographic keys from which any three are required to contribute to a cryptographic threshold signature.

"Verification" and "proof" are intended to apply broadly. For example, a cryptographic public key might be used during Diffie-Hellman key exchange to negotiate a shared symmetric key for encryption. This guarantees the integrity of the key agreement process. It is thus another type of verification method, even though descriptions of the process might not use the words "verification" or "proof."

A verification method is defined in a controlled identifier document using the map below and is referred to as the verification method definition :

verificationMethod

The verificationMethod property is OPTIONAL . If present, the value MUST be a set of verification methods , where each verification method is expressed using a map . The verification method map MUST include the id, type, controller, and specific verification material properties that are determined by the value of type and are defined in 2.2.1 Verification Material . A verification method MAY include additional properties.

id: The value of the id property for a verification method MUST be a string that conforms to the [ URL ] syntax. This value is called the verification method identifier and can also be used in a proof to refer to a specific instance of a verification method , which is called the verification method definition .
type: The value of the type property MUST be a string that references exactly one verification method type. This specification defines the types JsonWebKey (see Section 2.2.3 JsonWebKey ) and Multikey (see Section 2.2.2 Multikey ).
controller: The value of the controller property MUST be a string that conforms to the [ URL ] syntax.
expires: The expires property is OPTIONAL . If provided, it MUST be an [ XMLSCHEMA11-2 ] dateTimeStamp string specifying when the verification method SHOULD cease to be used. Once the value is set, it is not expected to be updated, and systems depending on the value are expected to not verify any proofs associated with the verification method at or after the time of expiration.
revoked: The revoked property is OPTIONAL . If present, it MUST be an [ XMLSCHEMA11-2 ] dateTimeStamp string specifying when the verification method MUST NOT be used. Once the value is set, it is not expected to be updated, and systems depending on the value are expected to not verify any proofs associated with the verification method at or after the time of revocation.

Example 6 : Example verification method structure

{
  "@context": "https://www.w3.org/ns/cid/v1",
  "id": "https://controller.example/123456789abcdefghi",
  ...
  "verificationMethod": [{
    "id": ...,
    "type": ...,
    "controller": ...,
    "publicKeyJwk": ...
  }, {
    "id": ...,
    "type": ...,
    "controller": ...,
    "publicKeyMultibase": ...
  }]
}

Note : The `controller` property is used by multiple objects

The controller property is used by controlled identifier documents , as described in Section 2.1 Controlled Identifier Documents , and by verification methods , as described in Section 2.2 Verification Methods . When it is used in either place, its purpose is essentially the same; that is, it expresses one or more entities that are authorized to perform certain actions associated with the resource with which it is associated.

In the case of the controller of a controlled identifier document , the controller can update the content of the document. In the case of the controller of a verification method , the controller can generate proofs that satisfy the method.

To ensure explicit security guarantees, the controller of a verification method cannot be inferred from the controlled identifier 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 controlled identifier 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 controlled identifier 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 controlled identifier 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/cid/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 be a string that is set to Multikey.
publicKeyMultibase: The publicKeyMultibase property is OPTIONAL . If present, its value MUST be a Multibase encoded value as described in Section 2.4 Multibase .
secretKeyMultibase: The secretKeyMultibase property is OPTIONAL . If present, its value MUST be a Multibase encoded value as described in Section 2.4 Multibase .

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

Example 8 : Multikey encoding of a Ed25519 public key

{
  "@context": "https://www.w3.org/ns/cid/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` ).
SM2 256-bit public key	The encoding of an SM2 public key MUST start with the two-byte prefix `0x8624` (the varint expression of `0x1206` ) 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` ).

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` ).
SM2 256-bit secret key	The encoding of an SM2 secret key MUST start with the two-byte prefix `0x9026` (the varint expression of `0x1310` ) 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` ).

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 controlled identifier document, that does not start with a known public key header.

When defining values for use with publicKeyMultibase and secretKeyMultibase, specification authors MAY define additional header values for other key types in other specifications and MUST NOT define alternate encodings for key types already defined by this specification.

The JSON Web Key (JWK) data model is a specific type of verification method that uses the JWK specification [ RFC7517 ] to encode key types into a set of parameters.

When specifing a JsonWebKey, the object takes the following form:

type

The value of the


type

property MUST be a string that is set to


JsonWebKey

publicKeyJwk

The publicKeyJwk property is OPTIONAL . If present, its value MUST be a map representing a JSON Web Key that conforms to [ RFC7517 ]. The map MUST NOT include any members of the private information class, such as d, as described in the JWK Registration Template . It is RECOMMENDED that verification methods that use JWKs [ RFC7517 ] to represent their public keys use the value of kid as their fragment identifier. It is RECOMMENDED that JWK kid values are set to the JWK Thumbprint [ RFC7638 ] using the SHA-256 (SHA2-256) hash function of the public key . See the first key in Example 7 for an example of a public key with a compound key identifier.

As specified in Section 4.4 of the JWK specification , the OPTIONAL alg property identifies the algorithm intended for use with the public key, and SHOULD be included to prevent security issues that can arise when using the same key with multiple algorithms. As specified in Section 6.2.1.1 of the JWA specification , describing a key using an elliptic curve, the REQUIRED crv property is used to identify the particular curve type of the public key. As specified in Section 4.1.4 of the JWS specification , the OPTIONAL kid property is a hint used to help discover the key; if present, the kid value SHOULD match, or be included in, the id property of the encapsulating JsonWebKey object, as part of the path, query, or fragment of the URL.

secretKeyJwk

The


secretKeyJwk

property is OPTIONAL . If present, its value MUST be a map representing a JSON Web Key that conforms to [ RFC7517 ]. It MUST NOT be used if the data structure containing it is public or may be revealed to parties other than the legitimate holders of the secret key.

An example of an object that conforms to JsonWebKey is provided below:

Example 9 : JSON Web Key encoding of a secp384r1 (P-384) public key

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

In the example above, the publicKeyJwk value contains the JSON Web Key. The kty property encodes the key type of "EC", which means "Elliptic Curve". The alg property identifies the algorithm intended for use with the public key, which in this case is ES384. The crv property identifies the particular curve type of the public key, P-384. The x and y properties specify the point on the P-384 curve that is associated with the public key.

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

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

Example 10 : JSON Web Key encoding of a secp384r1 (P-384) secret key

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

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

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 controlled identifier document or from another controlled identifier 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 is an expression that one or more verification methods are authorized to verify proofs made on behalf of the subject.

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

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

If a referenced verification method definition is not in the latest controlled identifier document used to dereference it, then that verification method is considered invalid or revoked.

The following sections define several useful verification relationships . A controlled identifier document MAY include any of these, or other properties, to express a specific verification relationship . To maximize interoperability, any such properties used SHOULD be registered in the list of DID Document Property Extensions .

The authentication verification relationship is used to specify how the subject is expected to be authenticated , for purposes such as logging into a website or engaging in any sort of challenge-response protocol. The processing performed following authentication is application-specific.

authentication: The authentication property is OPTIONAL . If present, its value MUST be a set of one or more verification methods . Each verification method MAY be embedded or referenced.

Example 12 : Authentication property containing three verification methods

{
  "@context": "https://www.w3.org/ns/cid/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"
    }
  ],
  ...
}

This is useful to any entity verifying authentication that needs to check whether an entity that is attempting to authenticate is presenting a valid proof of authentication. When such an authentication-verifying entity receives some data (in some protocol-specific format) that contains a proof that was made for the purpose of "authentication", and that says that an entity is identified by the id, then that verifier checks to ensure that the proof can be verified using a verification method (for example, public key ) listed under authentication in the controlled identifier document .

Note that the verification method indicated by the authentication property of a controlled identifier document can only be used to authenticate on behalf of the controlled identifier document 's base identifier .

The assertionMethod verification relationship is used to specify verification methods that a controller authorizes for use when expressing assertions or claims, such as in verifiable credentials.

assertionMethod: The assertionMethod property is OPTIONAL . If present, its associated value MUST be a set of one or more verification methods . Each verification method MAY be embedded or referenced.

This property is useful, for example, during the processing of a verifiable credential by a verifier.

Example 13 : Assertion method property containing two verification methods

{
  "@context": "https://www.w3.org/ns/cid/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/cid/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 controlled identifier document .

capabilityInvocation: The capabilityInvocation property is OPTIONAL . If present, the associated value MUST be a set of one or more verification methods . Each verification method MAY be embedded or referenced.

An example of when this property is useful is when a controller needs to access a protected HTTP API that requires authorization in order to use it. In order to authorize when using the HTTP API, the controller uses a capability that is associated with a particular URL that is exposed via the HTTP API. The invocation of the capability could be expressed in a number of ways, for example, as a digitally signed message that is placed into the HTTP Headers.

The server providing the HTTP API is the verifier of the capability and it would need to verify that the verification method referred to by the invoked capability exists in the capabilityInvocation property of the controlled identifier 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/cid/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 to delegate a cryptographic capability to another party. The mechanism, such as an Authorization Capability or a UCAN , and the processing performed following delegation, such as accessing a specific HTTP API, is application-specific.

capabilityDelegation: The capabilityDelegation property is OPTIONAL . If present, the associated value MUST be a set of one or more verification methods . Each verification method MAY be embedded or referenced.

An example of when this property is useful is when a controller chooses to delegate their capability to access a protected HTTP API to a party other than themselves. In order to delegate the capability, the controller would use a verification method associated with the capabilityDelegation verification relationship to cryptographically sign the capability over to another controller . The delegate would then use the capability in a manner that is similar to the example described in 2.3.4 Capability Invocation .

Example 16 : Capability Delegation property containing two verification methods

{
  "@context": "https://www.w3.org/ns/cid/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 controlled identifier document , an error MUST be raised and SHOULD convey an error type of INVALID_CONTROLLED_IDENTIFIER_DOCUMENT .
If controllerDocument. id does not match the controllerDocumentUrl, an error MUST be raised and SHOULD convey an error type of INVALID_CONTROLLED_IDENTIFIER_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 controlled identifier document containing a minimum conformant verification method as required by the algorithm in this section:

Example 19 : Minimum conformant controlled identifier 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 : Controlled identifier 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 controlled identifier document to express a verification method , through a verification relationship , that exists in a place that is external to the controlled identifier document . As described in Section 5.9 Integrity Protection of Controllers , specifying a verification method that is external to a controlled identifier document is a valid use of this specification. It is vital that this verification method is retrieved from the external controlled identifier document .

When retrieving any verification method the algorithm above is used to ensure that the verification method is retrieved from the correct controlled identifier document . The algorithm also ensures that this controlled identifier document refers to the verification method (via a verification relationship ) and that the verification method refers to the controlled identifier 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 controlled identifier 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,~~ URLs and ~~error codes~~ descriptions 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 MUST be present and it 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_CONTROLLED_IDENTIFIER_DOCUMENT_ID ~~(-22)~~: The id value in a controlled identifier document was malformed. See Section 3.3 Retrieve Verification Method .
INVALID_CONTROLLED_IDENTIFIER_DOCUMENT ~~(-23)~~: The controlled identifier document was malformed. See Section 3.3 Retrieve Verification Method .
INVALID_VERIFICATION_METHOD ~~(-24)~~: The verification method in a controlled identifier document was malformed. See Section 3.3 Retrieve Verification Method .
INVALID_RELATIONSHIP_FOR_VERIFICATION_METHOD ~~(-25)~~: The verification method in a controlled identifier 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: `3b7de8b1b0a66b6c4f31c58cbb3eb2ab587f130f67bfa0aee8b09afea4432171 e659cfbacfe7e59bcb96b67bebbc2d70cebafa5b5e5fb69ef339520b16aabe16`
text/turtle	The vocabulary in Turtle format [ TURTLE ]. SHA2-256 Digest: `62d4dd951c7ba5c331b39e190756b8ca9add8a645dee870949fe326a41e37518 9e1643b08191917162822043405732ef820d94ea672fc3592844786d11bd1dd9`
text/html	The vocabulary in HTML+RDFa Format [ HTML-RDFA ]. SHA2-256 Digest: `d25047d0ad97cf81965d03ea9e6738cd2c39253d15b225aa887bf624a873c34d 117fbbdd0c2e9196bd3b7bc67c729e1af285d8a2c5d78ce7b41273a9ca905518`

Context URL and Hash
URL: https://www.w3.org/ns/cid/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 controlled identifier 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 controlled identifier document for the purposes of authentication or authorization.

Proving control over an identifier and/or a controlled identifier document is useful when accessing remote systems. Cryptographic digital signatures enable certain security protocols related to controlled identifier 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 controlled identifier document do not inherently carry any personal data and it is strongly advised that non-public entities do not publish personal data in controlled identifier documents .

It can be useful to express a binding of an identifier to a person's or organization's physical identity in a way that is provably asserted by a trusted authority, such as a government. This specification provides the 2.3.2 Assertion verification relationship for these purposes. This feature can enable interactions that are private and can be considered legally enforceable under one or more jurisdictions; establishing such bindings has to be carefully balanced against privacy considerations (see 6. Privacy Considerations ).

The process of binding an identifier to something in the physical world, such as a person or an organization — for example, by using verifiable credentials with the same subject as that identifier — is contemplated by this specification and further defined in Verifiable Credentials Data Model v2.0 .

Even in cases where the subject referred to by an identifier proves control, the interpretation of the subject remains contextual and potentially ambiguous.

For example, a school might issue a verifiable credential about the teacher of Intro to Computer Science , using https://controller.example/abc as a subject identifier , saying " https://controller.example/abc is the teacher of Intro to Computer Science " and " https://controller.example/abc controls access to the school's computer lab. See them to request access".

In this usage, it is ambiguous whether https://controller.example/abc refers to a specific teacher or to whomever is the current teacher. Only with further statements might we be able to discern the difference. But it's still tricky. For example the subject in the following statement remains ambiguous:

Example 22 : Statement about the name of https://controller.example/abc as RDF Triples

<https://controller.example/abc>
  <https://schema.org/name>
"Bob
Smith"
.

If https://controller.example/abc refers to a specific human being, then the statement is taken as an attestation about the particular human identified by that name. However, if https://controller.example/abc is used to refer to the _current_ teacher, it is also valid if the current teacher does have that name . In this case, the ambiguity is immaterial.

However, in a statement like the following, the difference becomes vital.

Example 23 : Legal statements the convicted status of https://controller.example/abc as RDF Triples

<https://controller.example/abc>
  <http://law.example/convicted>
<http://calaw.example/PenalCode647b>
.

The statement in English could be "The person referred to by https://controller.example/abc has been convicted of California Penal Code 647b." But which person(s) did we mean? Did we mean to say one, some, or all of the teachers of computer science at the school have been convicted of violating PenalCode647b ? Or is it meant to say that a particular individual teacher, perhaps the one named "Bob Smith", has been convicted of said crime?

The challenge is particularly difficult in situations where the subject is fundamentally uninvolved in the issuance of the verifiable credential . For example, an identifier might be used by a school to refer to a teacher, and students and or parents might use that identifier to make statements about the teacher, with neither the teacher nor the school involved. In these cases, it is easy to imagine that the subtle nuance of the school's intended meaning, for example, "any current teacher of the computer science class", gets lost and the identifier gets misused by parents and students to refer to a specific teacher, quite likely in contexts where neither the school nor the teacher is aware of the conversation.

In natural language, these ambiguities are often easily ignored or corrected. In digital media, it is vital that context be evaluated to establish the intended referent, especially when identifiers are used in different contexts by different issuers , for example, on an official school website by the school, but in an unofficial social networking app by parents and students.

In short, the context in which identifiers are created and used has to be considered when relying on any particular interpretation of the subject of any particular identifier .

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

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

Rotation is a management process that enables the secret cryptographic material associated with an existing verification method to be deactivated or destroyed once a new verification method has been added to the controlled identifier 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 controlled identifier 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 controlled identifier 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 controlled identifier 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 controlled identifier 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 controlled identifier 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 controlled identifier 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 controlled identifier 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 controlled identifier 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 controlled identifier document is public.

Encrypting all or parts of a controlled identifier document is not an appropriate means to protect data in the long term. Similarly, placing encrypted data in a controlled identifier document is not an appropriate means to protect personal data.

Given the caveats above, if encrypted data is included in a controlled identifier 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.

Controlled identifier 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 controlled identifier document 's integrity is dependent on the external link.

One example of an external link where the integrity of the controlled identifier document itself could be affected is the JSON-LD Context [ JSON-LD11 ], when present. To protect against compromise, controlled identifier 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 controlled identifier document to an entity that is described in an external controlled identifier 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 controlled identifier 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 proof ing 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 controlled identifier 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 controlled identifier document data model can be extended to incorporate this information.

If a controlled identifier 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.

Type name:	application
Subtype name:	controller
Required parameters:	None
Encoding considerations:	Resources that use the `application/cid` media type are required to conform to all of the requirements for the `application/json` media type and are therefore subject to the same encoding considerations specified in Section 11 of The JavaScript Object Notation (JSON) Data Interchange Format .
Security considerations:	As defined in the Controlled Identifier Document v1.0 .
Contact:	W3C Verifiable Credentials Working Group public-vc-wg@w3.org

Controlled Identifier Document 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 Controlled Identifier 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 Controlled Identifier Document

5.1.2 Binding to Physical Identity

5.2 Identifier Ambiguity

5.3 Key and Signature Expiration

5.4 Verification Method Rotation

5.5 Verification Method Revocation

5.5.1 Revocation Semantics

5.6 Choosing a Multiformat

5.7 Encrypted Data in Controlled Identifier Documents

5.8 Content Integrity Protection

5.9 Integrity Protection of Controllers

5.10 Level of Assurance

5.11 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 Controlled Identifier Document Correlation Risks

6.5 Subject Classification

6.6 Service Privacy

7. Accessibility Considerations

7.1 Presenting Time Values

A. IANA Considerations

A.1 application/cid

B. Examples

B.1 Multikey Examples

B.2 JsonWebKey Examples

C. Revision History

D. Acknowledgements

E. References

E.1 Normative references

E.2 Informative references

4.3.1 The `multibase` Datatype