-
-
-
-A controller document specifies one or more relationships between
-an identifier and a set of verification methods and/or service
-endpoints. The controller document SHOULD
-contain verification relationships that explicitly permit the use of
-certain verification methods for specific purposes.
-
-
-
-
-
Example 1: Controller Document using publicKeyJwk
-
{
- "id": "https://controller.example/101",
- "verificationMethod": [{
- "id": "https://controller.example/101#key-20240828",
- "type": "JsonWebKey",
- "controller": "https://controller.example/101",
- "publicKeyJwk": {
- "kid": "key-20240828",
- "kty": "EC",
- "crv": "P-256",
- "alg": "ES256",
- "x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
- "y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0"
- }
-
- }],
- "authentication": ["#key-20240828"]
-}
-
-
-
Example 2: Controller Document using publicKeyMultibase and JSON-LD
-
{
- "@context": "https://www.w3.org/ns/controller/v1",
- "id": "https://controller.example",
- "authentication": [{
- "id": "https://controller.example#authn-key-123",
- "type": "Multikey",
- "controller": "https://controller.example",
- "publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
- }]
-}
-
Note: Property names used in map of different types
-The property names id, type, and controller can be present in map of
-different types with possible differences in constraints.
-
-The following sections define the properties in a controller document,
-including whether these properties are required or optional. These properties
-describe relationships between the subject and the value of the
-property.
-
-
-
-The following tables contain informative references for the core properties
-defined by this specification, with expected values, and whether or not they are
-required. The property names in the tables are linked to the normative
-definitions and more detailed descriptions of each property.
-
-
-
-
-
- | Property |
- Required? |
- Value constraints |
- Definition |
-
-
-
-
- id |
- yes |
-
-A string that conforms to the URL syntax.
- |
- 2.1.1 Subjects |
-
-
- controller |
- no |
-
-A string or a
-set of
-strings, each of which conforms to the URL
-syntax.
- |
- 2.1.2 Controllers |
-
-
- alsoKnownAs |
- no |
-
-A set of
-strings, each of which conforms to the URL
-syntax.
- |
- 2.1.3 Also Known As |
-
-
- service |
- no |
-
-A set of service
-maps.
- |
- 2.1.4 Services |
-
-
- verificationMethod |
- no |
-
-A set of
-verification method maps.
- |
- 2.2 Verification Methods |
-
-
- authentication |
- no |
-
-A set of strings, each of which conforms to
-the URL syntax, or a set of
-verification method maps.
- |
- 2.3.1 Authentication |
-
-
- assertionMethod |
- no |
-
-A set of strings, each of which conforms to
-the URL syntax, or a set of
-verification method maps.
- |
- 2.3.2 Assertion |
-
-
- keyAgreement |
- no |
-
-A set of strings, each of which conforms to
-the URL syntax, or a set of
-verification method maps.
- |
- 2.3.3 Key Agreement |
-
-
- capabilityInvocation |
- no |
-
-A set of strings, each of which conforms to
-the URL syntax, or a set of
-verification method maps.
- |
- 2.3.4 Capability Invocation |
-
-
- capabilityDelegation |
- no |
-
-A set of strings, each of which conforms to
-the URL syntax, or a set of
-verification method maps.
- |
- 2.3.5 Capability Delegation |
-
-
-
-
-
-
-
-
-
-
-A controller of a controller document is any entity capable of making changes to that
-controller document. Whoever can update
-the content of the resource returned from dereferencing the controller
-document's canonical URL is, by definition, a controller of the
-document and its canonical identifier. Proofs that satisfy a
-controller document's verification methods are taken as cryptographic
-assurance that the controller of the identifier created those proofs.
-
-
-
- - controller
- -
-The
controller property is OPTIONAL. If it is possible to represent
-the legitimate controllers of the document as URLs, the document SHOULD
-list URLs identifying those controllers.
-
- Note: Presumed Control
-It is possible to list a verification method which is
-functionally under the control of someone other than the controller
-of the controller document. For example, a document controller could
-set a public key under another party's control as an authentication
-verification method. This would enable the other party to authenticate
-on behalf of this identifier (because their public key is listed in
-an authentication verification method) without enabling that party
-to update the controller document. However, since the document
-controller explicitly listed that key for authentication, the
-proof in question is taken as created by the document controller, as
-it was created by their explicit assignee. This is especially useful
-when the "other party" is a device under the control of the document
-controller, but with a distinct cryptographic authority, i.e., it
-has its own keystore and can generate proofs. That pattern enables
-different devices, each using their own cryptographic material, to
-generate verifiable proofs that are taken as proofs created by
-controller of the identifier.
-
-Each entry in the controller property MUST identify
-an entity capable of updating the canonical version
-of the controller document.
-Subsequent requests for this controller document through its
-canonical location will always receive the latest version.
-
-
-If the controller property is not present, then control of the document
-is determined entirely by its storage location.
-
-
-
-
-
-
Example 4: Controller document with a controller property
-
{
- "@context": "https://www.w3.org/ns/controller/v1",
- "id": "https://controller1.example/123",
- "controller": "https://controllerB.example/abc",
-}
-
-While the identifier used for a controller is unambiguous, this does not
-imply that a single entity is always the controller, nor that a controller
-only has a single identifier. A controller might be a single entity, or a
-collection of entities, such as a partnership. A controller might also use
-multiple identifiers to refer to itself, for purposes such as privacy or
-delineating operational boundaries within an organization. Similarly, a
-controller might control many verification methods. For these reasons,
-no assumptions are to be made about a controller being a single entity nor
-controlling only a single verification method.
-
-
-
-
-
-
-
-
-
-A subject can have multiple identifiers that are used for different purposes
-or at different times. The assertion that two or more identifiers (or other types
-of URI) refer to the same subject can be made using the
-alsoKnownAs property.
-
-
-
- - alsoKnownAs
- -
-The
alsoKnownAs property is OPTIONAL. If present, its value MUST
-be a set where each item in the
-set is a URI conforming to [RFC3986].
-
- -
-This relationship is a statement that the subject of this identifier is
-also identified by one or more other identifiers.
-
-
-
- Note: Equivalence and alsoKnownAs
-
-Applications might choose to consider two identifiers related by alsoKnownAs
-to be equivalent if the alsoKnownAs relationship expressed in the
-controller document of one subject is also expressed in the reverse direction
-(i.e., reciprocated) in the controller document of the other subject. It is
-best practice not to consider them
-equivalent in the absence of this reciprocating relationship. In other words,
-the presence of an alsoKnownAs assertion does not prove that this assertion
-is true. Therefore, it is strongly advised that a requesting party obtain
-independent verification of an alsoKnownAs assertion.
-
-
-Given that the subject might use different identifiers for different
-purposes, such as enhanced privacy protection, an expectation of strong
-equivalence between the two identifiers, or taking action to
-merge the information from the two corresponding controller documents, is
-not necessarily appropriate, even with a reciprocal relationship.
-
-
-Services are used in controller documents to express ways of
-communicating with the controller, or associated entities, in relation to
-the controlled identifier. A service can be
-any type of service the controller wants to advertise for further discovery,
-authentication, authorization, or interaction.
-
-
-
-Due to privacy concerns, revealing public information through services, such
-as social media accounts, personal websites, and email addresses, is
-discouraged. Further exploration of privacy concerns can be found in sections
-6.1 Keep Personal Data Private and 6.6 Service Privacy. The information
-associated with services is often service specific. For example, the
-information associated with an encrypted messaging service can express how to
-initiate the encrypted link before messaging begins.
-
-
-
-Services are expressed using the service property, which is described
-below:
-
-
-
- - service
- -
-
-The service property is OPTIONAL. If present, the associated value MUST be a
-set of services, where each service is
-described by a map. Each service map MUST contain id, type, and
-serviceEndpoint properties. Each service extension MAY include additional
-properties and MAY further restrict the properties associated with the
-extension.
-
-
- - id
- -
-The
id property is OPTIONAL. If present, its value MUST be a URL
-conforming to URL Standard. A conforming document MUST NOT include multiple
-service entries with the same id.
-
- - type
- -
-The
type property is REQUIRED. Its value MUST be a
-string or a
-set of
-strings. To maximize interoperability,
-the service type and its associated properties SHOULD be registered in the
-Verifiable Credential Extensions.
-
- - serviceEndpoint
- -
-The
serviceEndpoint property is REQUIRED. The value of the serviceEndpoint
-property MUST be a single string, a single
-map, or a set
-composed of one or more
-strings and/or
-maps. Each string
-value MUST be a valid URL conforming to URL Standard.
-
-
-
-
-
-For more information regarding privacy and security considerations related to
-services see 6.6 Service Privacy, 6.1 Keep Personal Data Private,
-6.4 Controller Document Correlation Risks, and
-5.11 Service Endpoints for Authentication and Authorization.
-
-
-
-
{
- "service": [{
- "type": "ExampleSocialMediaService",
- "serviceEndpoint": "https://warbler.example/sal674"
- }]
-}
-
-A controller document can express verification methods, such as
-cryptographic public keys, which can be used to authenticate or
-authorize interactions with the controller or associated parties. For
-example, a cryptographic public key can be used as a verification
-method with respect to a digital signature; in such use, it verifies that
-the signer could use the associated cryptographic private key. Verification
-methods might take many parameters. An example of this is a set of five
-cryptographic keys from which any three are required to contribute to a
-cryptographic threshold signature.
-
-
-
- - verificationMethod
- -
-
-The verificationMethod property is OPTIONAL. If present, the value
-MUST be a set of verification
-methods, where each verification method is expressed using a map. The verification method map MUST include the id,
-type, controller, and specific verification material
-properties that are determined by the value of type and are defined
-in 2.2.1 Verification Material. A verification method MAY
-include additional properties.
-
-
-
-
- - id
- -
-
-The value of the id property for a verification method
-MUST be a string that
-conforms to the [URL] syntax.
-
-
- - type
- -
-The value of the
type property MUST be a string that references exactly one verification
-method type. This specification defines the types JsonWebKey (see Section
-2.2.3 JsonWebKey) and Multikey (see Section 2.2.2 Multikey).
-
- - controller
- -
-The value of the
controller property MUST be a string that conforms to the [URL] syntax.
-
-
- - expires
- -
-The
expires property is OPTIONAL.
-
-If provided, it MUST be an
-[XMLSCHEMA11-2] dateTimeStamp string specifying when the
-verification method SHOULD cease to be used. Once the value is set, it is
-not expected to be updated, and systems depending on the value are expected to
-not verify any proofs associated with the verification method at or after
-the time of expiration.
-
- - revoked
- -
-The
revoked property is OPTIONAL.
-
-If present, it MUST be an [XMLSCHEMA11-2]
-dateTimeStamp string specifying when the verification method
-MUST NOT be used. Once the value is set, it is not expected to be
-updated, and systems depending on the value are expected to not verify any
-proofs associated with the verification method at or after the time of
-revocation.
-
-
-
-
-
-
-
-
Example 6: Example verification method structure
-
{
- "@context": [
- "https://www.w3.org/ns/controller/v1",
- "https://www.w3.org/ns/credentials/v2",
- "https://w3id.org/security/jwk/v1",
- "https://w3id.org/security/data-integrity/v2"
- ]
- "id": "https://controller.example/123456789abcdefghi",
-
- "verificationMethod": [{
- "id": ,
- "type": ,
- "controller": ,
- "publicKeyJwk":
- }, {
- "id": ,
- "type": ,
- "controller": ,
- "publicKeyMultibase":
- }]
-}
-
Note: The `controller` property is used by multiple objects
-The controller property is used by controller documents, as described in
-Section 2.1 Controller Documents, and by verification methods, as
-described in Section 2.2 Verification Methods. When it is used in either
-place, its purpose is essentially the same; that is, it expresses one or more
-entities that are authorized to perform certain actions associated with the
-resource with which it is associated.
-
-In the case of the controller of a controller document, the
-controller can update the content of the document. In the case of the
-controller of a verification method, the controller can generate
-proofs that satisfy the method.
-
-
-To ensure explicit security guarantees, the
-controller of a verification method cannot be inferred from the
-controller document. It is necessary to explicitly express the identifier of
-the controller of the key because the value of controller for a verification method is not necessarily the value of the controller for a
-controller document.
-
-
-
-
-
-
-Verification material is any information that is used by a process that applies
-a verification method. The type of a verification method is
-expected to be used to determine its compatibility with such processes. Examples
-of verification methods include JsonWebKey and Multikey.
-A cryptographic suite specification is responsible for specifying the
-verification method type and its associated verification material
-format. For examples using verification material, see
-Securing Verifiable Credentials using JOSE and COSE,
-the Data Integrity ECDSA
-Cryptosuites and
-the Data Integrity EdDSA Cryptosuites.
-
-
-
-To increase the likelihood of interoperable implementations, this specification
-limits the number of formats for expressing verification material in a
-controller document. The fewer formats that implementers have to
-choose from, the more likely that interoperability will be achieved. This
-approach attempts to strike a delicate balance between easing implementation
-and providing support for formats that have historically had broad deployment.
-
-
-
-A verification method MUST NOT contain multiple verification material
-properties for the same material. For example, expressing key material in a
-verification method using both publicKeyJwk and
-publicKeyMultibase at the same time is prohibited.
-
-
-
-Implementations MAY convert keys between formats as desired for operational purposes or
-to interface with cryptographic libraries. As an internal implementation detail, such
-conversion MUST NOT affect the external representation of key material.
-
-
-
-An example of a controller document containing verification
-methods using both properties above is shown below.
-
-
-
-
-
Example 7: Verification methods using publicKeyJwk and publicKeyMultibase
-
{
- "@context": "https://www.w3.org/ns/controller/v1",
- "id": "https://controller.example/123456789abcdefghi",
-
- "verificationMethod": [{
- "id": "https://controller.example/123#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
- "type": "JsonWebKey",
- "controller": "https://controller.example/123456789abcdefghi",
- "publicKeyJwk": {
- "crv": "Ed25519",
- "x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOyPVQaO3FxVeQ",
- "kty": "OKP",
- "kid": "_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A"
- }
- }, {
- "id": "https://controller.example/123456789abcdefghi#keys-1",
- "type": "Multikey",
- "controller": "https://controller.example/123456789abcdefghi",
- "publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
- }],
-
-}
-
-The Multikey data model is a specific type of verification method that
-encodes key types into a single binary stream that is then encoded as a
-Multibase value as described in Section 2.4 Multibase.
-
-
-
-When specifying a Multikey, the object takes the following form:
-
-
-
- - type
- -
-The value of the
type property MUST contain the string Multikey.
-
- - publicKeyMultibase
- -
-The
publicKeyMultibase property is OPTIONAL. If present, its value MUST be a
-Multibase encoded value as described in Section 2.4 Multibase.
-
- - secretKeyMultibase
- -
-The
secretKeyMultibase property is OPTIONAL. If present, its value MUST be a
-Multibase encoded value as described in Section 2.4 Multibase.
-
-
-
-
-The example below expresses an Ed25519 public key using the format defined
-above:
-
-
-
-
-
Example 8: Multikey encoding of a Ed25519 public key
-
{
- "@context": ["https://w3id.org/security/multikey/v1"],
- "id": "https://controller.example/123456789abcdefghi#keys-1",
- "type": "Multikey",
- "controller": "https://controller.example/123456789abcdefghi",
- "publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
-}
-
-The public key values are expressed using the rules in the table below:
-
-
-
-
- | Key type |
- Description |
-
|---|
-
-
- | ECDSA 256-bit public key |
-
-The Multikey encoding of a P-256 public key MUST start with the two-byte prefix
-0x8024 (the varint expression of 0x1200) followed by the 33-byte compressed
-public key data. The resulting 35-byte value MUST then be encoded using the
-base-58-btc alphabet, according to Section 2.4 Multibase, and then
-prepended with the base-58-btc Multibase header (z).
- |
-
-
- | ECDSA 384-bit public key |
-
-The encoding of a P-384 public key MUST start with the two-byte prefix 0x8124
-(the varint expression of 0x1201) followed by the 49-byte compressed public
-key data. The resulting 51-byte value is then encoded using the base-58-btc
-alphabet, according to Section 2.4 Multibase, and then prepended with the
-base-58-btc Multibase header (z).
- |
-
-
- | Ed25519 256-bit public key |
-
-The encoding of an Ed25519 public key MUST start with the two-byte prefix
-0xed01 (the varint expression of 0xed), followed by the 32-byte public key
-data. The resulting 34-byte value MUST then be encoded using the base-58-btc
-alphabet, according to Section 2.4 Multibase, and then prepended with the
-base-58-btc Multibase header (z).
- |
-
-
- | BLS12-381 381-bit public key |
-
-The encoding of an BLS12-381 public key in the G2 group MUST start with
-the two-byte prefix 0xeb01 (the varint expression of 0xeb), followed
-by the 96-byte compressed public key data. The resulting 98-byte value MUST
-then be encoded using the base-58-btc alphabet, according to Section
-2.4 Multibase, and then prepended with the base-58-btc Multibase header
-(z).
- |
-
-
-
-
-
-The secret key values are expressed using the rules in the table below:
-
-
-
-
- | Key type |
- Description |
-
|---|
-
-
- | ECDSA 256-bit secret key |
-
-The Multikey encoding of a P-256 secret key MUST start with the two-byte prefix
-0x8626 (the varint expression of 0x1306) followed by the 32-byte
-secret key data. The resulting 34-byte value MUST then be encoded using the
-base-58-btc alphabet, according to Section 2.4 Multibase, and then
-prepended with the base-58-btc Multibase header (z).
- |
-
-
- | ECDSA 384-bit secret key |
-
-The encoding of a P-384 secret key MUST start with the two-byte prefix 0x8726
-(the varint expression of 0x1307) followed by the 48-byte secret
-key data. The resulting 50-byte value is then encoded using the base-58-btc
-alphabet, according to Section 2.4 Multibase, and then prepended with the
-base-58-btc Multibase header (z).
- |
-
-
- | Ed25519 256-bit secret key |
-
-The encoding of an Ed25519 secret key MUST start with the two-byte prefix
-0x8026 (the varint expression of 0x1300), followed by the 32-byte secret key
-data. The resulting 34-byte value MUST then be encoded using the base-58-btc
-alphabet, according to Section 2.4 Multibase, and then prepended with the
-base-58-btc Multibase header (z).
- |
-
-
- | BLS12-381 381-bit secret key |
-
-The encoding of an BLS12-381 secret key in the G2 group MUST start with
-the two-byte prefix 0x8030 (the varint expression of 0x130a), followed
-by the 96-byte compressed public key data. The resulting 98-byte value MUST
-then be encoded using the base-58-btc alphabet, according to Section
-2.4 Multibase, and then prepended with the base-58-btc Multibase header
-(z).
- |
-
-
-
-
-
-
-Developers are advised to not accidentally publish a representation of a secret
-key. Implementations that adhere to this specification will raise errors in the
-event of a Multikey header value that is not in the public key header table
-above, or when reading a Multikey value that is expected to be a public key,
-such as one published in a controller document, that does not start with a known
-public key header.
-
-
-
-When defining values for use with publicKeyMultibase and secretKeyMultibase,
-specification authors MAY define additional header values for other key types in
-other specifications and MUST NOT define alternate encodings for key types
-already defined by this specification.
-
-
-
-
-
-
-
-The JSON Web Key (JWK) data model is a specific type of verification method
-that uses the JWK specification [RFC7517] to encode key types into a
-set of parameters.
-
-
-
-When specifing a JsonWebKey, the object takes the following form:
-
-
-
- - type
- -
-The value of the
type property MUST contain the string JsonWebKey.
-
- - publicKeyJwk
- -
-
-The publicKeyJwk property is OPTIONAL. If present, its value MUST
-be a map representing a JSON Web Key that
-conforms to [RFC7517]. The map MUST NOT
-include any members of the private information class, such as d, as described
-in the JWK
-Registration Template. It is RECOMMENDED that verification methods that use
-JWKs [RFC7517] to represent their public keys use the value of kid as
-their fragment identifier. It is RECOMMENDED that JWK kid values are set to
-the JWK Thumbprint [RFC7638] using the SHA-256 (SHA2-256) hash function of the public key.
-See the first key in
-Example 7 for an example of a
-public key with a compound key identifier.
-
-
-As specified in Section 4.4 of the JWK specification,
-the OPTIONAL alg property identifies the algorithm intended for use with the public key,
-and SHOULD be included to prevent security issues that can arise when using the same
-key with multiple algorithms. As specified in
-Section 6.2.1.1 of the JWA specification, describing a key using an elliptic curve,
-the REQUIRED crv property is used to identify the particular curve type of the public key.
-As specified in Section 4.1.4 of the JWS specification,
-the OPTIONAL kid property is a hint used to help discover the key; if present, the kid value SHOULD
-match, or be included in, the id property of the encapsulating JsonWebKey object,
-as part of the path, query, or fragment of the URL.
-
-
-
- - secretKeyJwk
- -
-The
secretKeyJwk property is OPTIONAL. If present, its value MUST be a map representing a JSON Web Key that conforms
-to [RFC7517].
-It MUST NOT be used if the data structure containing it is public or may be revealed to parties other than the legitimate holders of the secret key.
-
-
-
-
-An example of an object that conforms to JsonWebKey is provided below:
-
-
-
-
-
Example 9: JSON Web Key encoding of a secp384r1 (P-384) public key
-
{
- "id": "https://controller.example/123456789abcdefghi#key-1",
- "type": "JsonWebKey",
- "controller": "https://controller.example/123456789abcdefghi",
- "publicKeyJwk": {
- "kid": "key-1",
- "kty": "EC",
- "crv": "P-384",
- "alg": "ES384",
- "x": "1F14JSzKbwxO-Heqew5HzEt-0NZXAjCu8w-RiuV8_9tMiXrSZdjsWqi4y86OFb5d",
- "y": "dnd8yoq-NOJcBuEYgdVVMmSxonXg-DU90d7C4uPWb_Lkd4WIQQEH0DyeC2KUDMIU"
- }
-}
-
-In the example above, the publicKeyJwk value contains the JSON Web Key.
-The kty property encodes the key type of "EC", which means
-"Elliptic Curve". The alg property identifies the algorithm intended
-for use with the public key, which in this case is ES384. The crv property identifies
-the particular curve type of the public key, P-384. The x and y properties specify
-the point on the P-384 curve that is associated with the public key.
-
-
-
-The publicKeyJwk property MUST NOT contain any property marked as
-"Private" or "Secret" in any registry contained in the JOSE Registries [JOSE-REGISTRIES], including "d".
-
-
-
-The JSON Web Key data model is also capable of encoding secret keys, sometimes
-referred to as private keys.
-
-
-
-
-
Example 10: JSON Web Key encoding of a secp384r1 (P-384) secret key
-
{
- "id": "https://controller.example/123456789abcdefghi#key-1",
- "type": "JsonWebKey",
- "controller": "https://controller.example/123456789abcdefghi",
- "secretKeyJwk": {
- "kty": "EC",
- "crv": "P-384",
- "alg": "ES384",
- "d": "fGwges0SX1mj4eZamUCL4qtZijy9uT15fI4gKTuRvre4Kkoju2SHM4rlFOeKVraH",
- "x": "1F14JSzKbwxO-Heqew5HzEt-0NZXAjCu8w-RiuV8_9tMiXrSZdjsWqi4y86OFb5d",
- "y": "dnd8yoq-NOJcBuEYgdVVMmSxonXg-DU90d7C4uPWb_Lkd4WIQQEH0DyeC2KUDMIU"
- }
-}
-
-The private key example above is almost identical to the previous example of the
-public key, except that the information is stored in the secretKeyJwk property
-(rather than the publicKeyJwk), and the private key value is encoded in the d
-property thereof (alongside the x and y properties, which still specify
-the point on the P-384 curve that is associated with the public key).
-
-
-
-
-
-
-
-
-
-
-
-A verification relationship expresses the relationship between the
-controller and a verification method.
-
-
-Different verification relationships enable the associated
-verification methods to be used for different purposes. It is up to a
-verifier to ascertain the validity of a verification attempt by
-checking that the verification method used is contained in the
-appropriate verification relationship property of the
-controller document.
-
-
-The verification relationship between the controller and the
-verification method is explicit in the controller document.
-Verification methods that are not associated with a particular
-verification relationship cannot be used for that verification relationship. For example, a verification method in the value of
-the authentication property cannot be used to engage in
-key agreement protocols with the controller — the value of the
-keyAgreement property needs to be used
-for that.
-
-
-The controller document does not express revoked keys using a verification
-relationship. If a referenced verification method is not in the latest
-controller document used to dereference it, then that verification method is
-considered invalid or revoked.
-
-
-The following sections define several useful verification relationships.
-A controller document MAY include any of these, or other properties, to
-express a specific verification relationship. To maximize
-interoperability, any such properties used SHOULD be registered in the
-VC Specifications Directory.
-
-
-
-
-
-
-The authentication verification relationship is used to specify how the
-subject is expected to be authenticated, for purposes such as logging
-into a website or engaging in any sort of challenge-response protocol. The
-processing performed following authentication is application-specific.
-
-
-
- - authentication
- -
-The
authentication property is OPTIONAL. If present, its
-value MUST be a set of one or more
-verification methods. Each verification method MAY be embedded or
-referenced.
-
-
-
-
-
-
Example 12: Authentication property
- containing three verification methods
-
{
- "@context": [
- "https://www.w3.org/ns/controller/v1",
- "https://www.w3.org/ns/credentials/v2",
- "https://w3id.org/security/multikey/v1"
- ],
- "id": "https://controller.example/123456789abcdefghi",
-
- "authentication": [
-
- "https://controller.example/123456789abcdefghi#keys-1",
-
-
- {
- "id": "https://controller.example/123456789abcdefghi#keys-2",
- "type": "JsonWebKey",
- "controller": "https://controller.example/123456789abcdefghi",
- "publicKeyJwk": {
- "crv": "Ed25519",
- "x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOyPVQaO3FxVeQ",
- "kty": "OKP",
- "kid": "_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A"
- }
- },
- {
- "id": "https://controller.example/123456789abcdefghi#keys-3",
- "type": "Multikey",
- "controller": "https://controller.example/123456789abcdefghi",
- "publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
- }
- ],
-
-}
-
-This is useful to any entity verifying authentication that needs to check
-whether an entity that is attempting to authenticate is presenting a valid
-proof of authentication. When such an authentication-verifying entity receives
-some data (in some protocol-specific format) that contains a proof that was made
-for the purpose of "authentication", and that says that an entity is identified
-by the id, then that verifier checks to ensure that the proof can be
-verified using a verification method (for example, public key) listed
-under authentication in the controller document.
-
-
-Note that the verification method indicated by the
-authentication property of a controller document can
-only be used to authenticate on behalf
-of the controller document's base identifier.
-
-
-
-
-
-
-
-The assertionMethod verification relationship is used to
-specify verification methods that a controller authorizes for use
-when expressing assertions or claims, such as in verifiable credentials.
-
-
-
- - assertionMethod
- -
-The
assertionMethod property is OPTIONAL. If present, its associated
-value MUST be a set of one or
-more verification methods. Each verification method MAY
-be embedded or referenced.
-
-
-
-
-This property is useful, for example, during the processing of a
-verifiable credential by a verifier.
-
-
-
-
-
-
Example 13: Assertion method property
- containing two verification methods
-
{
- "@context": [
- "https://www.w3.org/ns/controller/v1",
- "https://www.w3.org/ns/credentials/v2",
- "https://w3id.org/security/multikey/v1"
- ],
- "id": "https://controller.example/123456789abcdefghi",
-
- "assertionMethod": [
-
- "https://controller.example/123456789abcdefghi#keys-1",
-
-
-
- {
- "id": "https://controller.example/123456789abcdefghi#keys-2",
- "type": "Multikey",
- "controller": "https://controller.example/123456789abcdefghi",
- "publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
- }
- ],
-
-}
-
-The keyAgreement verification relationship is used to
-specify how an entity can perform encryption in order to transmit
-confidential information intended for the controller, such as for
-the purposes of establishing a secure communication channel with the recipient.
-
-
-
- - keyAgreement
- -
-The
keyAgreement property is OPTIONAL. If present, the associated
-value MUST be a set of one or more
-verification methods. Each verification method MAY be embedded or
-referenced.
-
-
-
-
-An example of when this property is useful is when encrypting a message intended
-for the controller. In this case, the counterparty uses the
-cryptographic public key information in the verification method to
-wrap a decryption key for the recipient.
-
-
-
-
-
Example 14: Key agreement property
- containing two verification methods
-
{
- "@context": "https://www.w3.org/ns/controller/v1",
- "id": "https://controller.example/123456789abcdefghi",
-
- "keyAgreement": [
- "https://controller.example/123456789abcdefghi#keys-1",
-
-
-
- {
- "id": "https://controller.example/123#keys-2",
- "type": "Multikey",
- "controller": "https://controller.example/123",
- "publicKeyMultibase": "zDnaerx9CtbPJ1q36T5Ln5wYt3MQYeGRG5ehnPAmxcf5mDZpv"
- },
- {
- "id": "https://controller.example/123#keys-3",
- "type": "JsonWebKey",
- "controller": "https://controller.example/123",
- "publicKeyJwk": {
- "kty": "OKP",
- "crv": "X25519",
- "x": "W_Vcc7guviK-gPNDBmevVw-uJVamQV5rMNQGUwCqlH0"
- }
- }
- ],
-
-}
-
-The capabilityInvocation verification relationship is used
-to specify a verification method that might be used by the
-controller to invoke a cryptographic capability, such as the
-authorization to update the controller document.
-
-
-
- - capabilityInvocation
- -
-The
capabilityInvocation property is OPTIONAL. If present, the
-associated value MUST be a set of
-one or more verification methods. Each verification method MAY be
-embedded or referenced.
-
-
-
-
-An example of when this property is useful is when a controller needs to
-access a protected HTTP API that requires authorization in order to use it. In
-order to authorize when using the HTTP API, the controller
-uses a capability that is associated with a particular URL that is
-exposed via the HTTP API. The invocation of the capability could be
-expressed in a number of ways, for example, as a digitally signed
-message that is placed into the HTTP Headers.
-
-
-The server providing the HTTP API is the verifier of the capability and
-it would need to verify that the verification method referred to by the
-invoked capability exists in the capabilityInvocation
-property of the controller document. The verifier would also check to make sure
-that the action being performed is valid and the capability is appropriate for
-the resource being accessed. If the verification is successful, the server has
-cryptographically determined that the invoker is authorized to access the
-protected resource.
-
-
-
-
-
Example 15: Capability invocation property
- containing two verification methods
-
{
- "@context": [
- "https://www.w3.org/ns/controller/v1",
- "https://w3id.org/security/multikey/v1"
- ],
- "id": "https://controller.example/123456789abcdefghi",
-
- "capabilityInvocation": [
-
- "https://controller.example/123456789abcdefghi#keys-1",
-
-
-
- {
- "id": "https://controller.example/123456789abcdefghi#keys-2",
- "type": "Multikey",
- "controller": "https://controller.example/123456789abcdefghi",
- "publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
- }
- ],
-
-}
-
-The capabilityDelegation verification relationship is used to specify a
-mechanism that might be used to delegate a cryptographic
-capability to another party. The mechanism, such as an
-Authorization Capability
-or a UCAN, and
-the processing performed following delegation, such as accessing a specific HTTP
-API, is application-specific.
-
-
-
- - capabilityDelegation
- -
-The
capabilityDelegation property is OPTIONAL. If present, the
-associated value MUST be a set of
-one or more verification methods. Each verification method MAY be
-embedded or referenced.
-
-
-
-
-An example of when this property is useful is when a controller chooses
-to delegate their capability to access a protected HTTP API to a party other
-than themselves. In order to delegate the capability, the controller
-would use a verification method associated with the
-capabilityDelegation verification relationship to
-cryptographically sign the capability over to another controller. The
-delegate would then use the capability in a manner that is similar to the
-example described in 2.3.4 Capability Invocation.
-
-
-
-
-
Example 16: Capability Delegation property
- containing two verification methods
-
{
- "@context": [
- "https://www.w3.org/ns/controller/v1",
- "https://w3id.org/security/multikey/v1"
- ],
- "id": "https://controller.example/123456789abcdefghi",
-
- "capabilityDelegation": [
-
- "https://controller.example/123456789abcdefghi#keys-1",
-
-
-
- {
- "id": "https://controller.example/123456789abcdefghi#keys-2",
- "type": "JsonWebKey",
- "controller": "https://controller.example/123456789abcdefghi",
- "publicKeyJwk": {
- "kty": "OKP",
- "crv": "Ed25519",
- "x": "O2onvM62pC1io6jQKm8Nc2UyFXcd4kOmOsBIoYtZ2ik"
- }
- },
- {
- "id": "https://controller.example/123456789abcdefghi#keys-3",
- "type": "Multikey",
- "controller": "https://controller.example/123456789abcdefghi",
- "publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
- }
- ],
-
-}
-
-A Multibase value encodes a binary value as a
-base-encoded
-string. The value starts with a single character header, which identifies
-the base and encoding alphabet used to encode a binary value, followed by the
-encoded binary value (using that base and alphabet). The common
- values and their associated base
-encoding alphabets, as provided below, are normative:
-
-
-
-
-
- | Multibase Header |
- Description |
-
-
-
-
-
- u |
-
-The base-64-url-no-pad alphabet is used to encode the bytes. The base-alphabet
-consists of the following characters, in order:
-ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_
- |
-
-
- z |
-
-The base-58-btc alphabet is used to encode the bytes. The base-alphabet consists
-of the following characters, in order:
-123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz
- |
-
-
-
-
-
-Other Multibase encoding values MAY be used, but interoperability is not
-guaranteed between implementations using such values.
-
-
-
-To base-encode a binary value into a Multibase string, an implementation MUST
-apply the algorithm in Section 3.1 Base Encode to the binary value,
-with the desired base encoding and alphabet from the table above, ensuring to
-prepend the associated Multibase header from the table above to the result.
-Any algorithm with equivalent output MAY be used.
-
-
-
-To base-decode a Multibase string, an implementation MUST apply the algorithm
-in Section 3.2 Base Decode to the string following the first
-character (Multibase header), with the alphabet associated with the
-Multibase header. Any algorithm with equivalent output MAY be used.
-
-
-
-
-
-
-
-
-A Multihash value starts with a binary header, which includes 1) an identifier
-for the specific cryptographic hashing algorithm, 2) a cryptographic digest
-length in bytes, and 3) the value of the cryptographic digest. The normative
-Multihash header values defined by this specification, and their associated
-output sizes and associated specifications, are provided below:
-
-
-
-
-
- | Multihash Identifier |
- Multihash Header |
- Description |
-
-
-
-
-
- sha2-256 |
- 0x12 |
-
-SHA-2 with 256 bits (32 bytes) of output, as defined by [RFC6234].
- |
-
-
- sha2-384 |
- 0x20 |
-
-SHA-2 with 384 bits (48 bytes) of output, as defined by [RFC6234].
- |
-
-
- sha3-256 |
- 0x16 |
-
-SHA-3 with 256 bits (32 bytes) of output, as defined by [SHA3].
- |
-
-
- sha3-384 |
- 0x15 |
-
-SHA-3 with 384 bits (48 bytes) of output, as defined by [SHA3].
- |
-
-
-
-
-
-Other Multihash encoding values MAY be used, but interoperability is not
-guaranteed between implementations.
-
-
-
-To encode to a Multihash value, an implementation MUST concatenate the
-associated Multihash header (encoded as a varint), the cryptographic digest
-length in bytes (encoded as a varint), and the cryptographic digest value, in
-that order.
-
-
-
-To decode a Multihash value, an implementation MUST 1) remove the prepended
-Multihash header value, which identifies the type of cryptographic hashing
-algorithm, 2) remove the cryptographic digest length in bytes, and 3) extract
-the raw cryptographic digest value which MUST match the expected output length
-associated with the Multihash header as well as the output length provided in
-the Multihash value itself.
-
-
-
-
-
-
-
-
-
- Issue 2: (AT RISK) Hash values might change during Candidate Recommendation
- This section lists cryptographic hash values that might change during the
- Candidate Recommendation phase based on implementer feedback that requires
- the referenced files to be modified.
-
- The terms defined in this specification are also part of the
- RDF vocabulary namespace [RDF-CONCEPTS]
- https://w3id.org/security#.
- For any TERM, the relevant URL is of the form
- https://w3id.org/security#TERM or https://w3id.org/security#TERMmethod.
- Implementations that use RDF processing and rely on this specification MUST use these URLs.
-
-
-
- When dereferencing the
- https://w3id.org/security# URL,
- the media type of the data that is returned depends on HTTP content negotiation. These are as follows:
-
-
-
-
-
- | Media Type |
- Description and Hash |
-
-
-
-
- |
- application/ld+json
- |
-
- The vocabulary in JSON-LD format [JSON-LD11].
-
- SHA2-256 Digest: 0825e3f71462e105e85ea144e2eb1521c2755e6679bd2eb459a9a796c56b18e8
- |
-
-
- |
- text/turtle
- |
-
- The vocabulary in Turtle format [TURTLE].
-
- SHA2-256 Digest: 2fefc7e645fdfa34491c772d0e9c2eed9f95cde3b205e4667abe876580be7f7d
- |
-
-
- |
- text/html
- |
-
- The vocabulary in HTML+RDFa Format [HTML-RDFA].
-
-
- SHA2-256 Digest: 0f989a247fb87f514640f1080ad40713b6c950edeb1d29e8c5b45f647699b3d4
- |
-
-
-
-
-
- It is possible to confirm the cryptographic digests above by running
- a command like the following (replacing <MEDIA_TYPE> and <DOCUMENT_URL>
- with the appropriate values) through a modern UNIX-like OS command line interface:
- curl -sL -H "Accept: <MEDIA_TYPE>" <DOCUMENT_URL> | openssl dgst -sha256
-
-
-
-
-
-
- Implementations that perform JSON-LD processing MUST treat the following
- JSON-LD context URL as already resolved, where the resolved document matches
- the corresponding hash value below:
-
-
-
-
- | Context URL and Hash |
-
|---|
-
-
-
- URL: https://www.w3.org/ns/controller/v1
- SHA2-256 Digest:
ea216ecc1cb02cd39b693dba2250141e270ba0bf95890be107dd9a9e8e43de85
- |
-
-
-
-
-
- It is possible to confirm the cryptographic digests listed above by running a
- command like the following through a modern UNIX-like OS command line interface: curl -sL -H
- "Accept: application/ld+json" https://www.w3.org/ns/controller/v1 | openssl dgst -sha256
-
-
-
- The security vocabulary terms that the JSON-LD contexts listed above resolve
- to are in the https://w3id.org/security#
- namespace. See also 4.1 Vocabulary for further details.
-
-
- Note
- Applications or specifications may define mappings to the
- vocabulary URLs using their own JSON-LD contexts. For example, these mappings are part
- of the https://w3id.org/security/data-integrity/v2 context,
- defined by the Verifiable Credential Data Integrity 1.0 specification, or the https://www.w3.org/ns/did/v1 context,
- defined by the Decentralized Identifiers (DIDs) v1.0 specification.
-
-The @context property is used to ensure that implementations are using the
-same semantics when terms in this specification are processed. For example, this
-can be important when properties like authentication are processed and its
-value, such as Multikey or JsonWebKey, are used.
-
-
-
-When an application is processing a controller document, if an @context
-property is not provided in the document or the terms used in the document are
-not mapped by existing values in the @context property, implementations MUST
-inject or append an @context property with a value of
-https://www.w3.org/ns/controller/v1 or one or more contexts with at least the
-same declarations, such as the Decentralized Identifier v1.1 context
-(https://www.w3.org/ns/did/v1).
-
-
-
-
-
Example 21: A controller document without an @context property
-
{
- "id": "https://controller.example/101",
- "verificationMethod": [{
- "id": "https://controller.example/101#key-203947",
- "type": "JsonWebKey",
- "controller": "https://controller.example/101",
- "publicKeyJwk": {
- "kid": "key-203947",
- "kty": "EC",
- "crv": "P-256",
- "alg": "ES256",
- "x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
- "y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0"
- }
- }],
- "authentication": ["#key-203947"]
-}
-
-Implementations that do not intend to use JSON-LD MAY choose to not include an
-@context declaration at the top-level of the document. Whether or not the
-@context value or JSON-LD processors are used, the semantics for all properties
-and values expressed in conforming documents interpreted by conforming processors are the same. Any differences in semantics between documents
-processed in either mode are either implementation or specification bugs.
-
-
-
-
-
-
-
-
-
-This section defines datatypes that are used by this specification.
-
-
-
-
-
-
-Multibase-encoded strings are used to encode binary
-data into printable formats, such as ASCII, which are useful in environments
-that cannot directly represent binary values. This specification makes use of
-this encoding. In environments that support data types for string values, such
-as RDF [RDF-CONCEPTS], Multibase-encoded content
-is indicated using a literal value whose datatype is set to
-https://w3id.org/security#multibase.
-
-
-
-The multibase datatype is defined as follows:
-
-
-
- - The URL denoting this datatype
- -
-
https://w3id.org/security#multibase
-
- - The lexical space
- -
-Any string that starts with a and the rest of the
-characters consist of allowable characters in the respective base-encoding
-alphabet.
-
- - The value space
- -
-The standard mathematical concept of all integer numbers.
-
- - The lexical-to-value mapping
- -
-Any element of the lexical space is mapped to the value space by base-decoding
-the value based on the base-decoding alphabet associated with the first
- in the lexical string.
-
- - The canonical mapping
- -
-The canonical mapping consists of using the lexical-to-value mapping.
-
-
-
-
-
-
-
-
- This section is non-normative.
-
-
-
-This section contains a variety of security considerations that people using
-this specification are advised to consider before deploying this
-technology in a production setting. This technologies described in this
-document are designed to operate under the threat model used by many IETF
-standards and documented in [RFC3552]. This section elaborates upon a number
-of the considerations in [RFC3552], as well as other considerations that are
-unique to this specification.
-
-
-
-
-
-
-Binding an entity in the digital world or the physical world to an identifier, to
-a controller document, or to cryptographic material requires the use of
-security protocols contemplated by this specification. The following sections
-describe some possible scenarios and how an entity therein might prove control
-over an identifier or a controller document for the purposes of authentication or
-authorization.
-
-
-
-
-
-
-
-
-An identifier or controller document do not inherently carry any
-personal data and
-it is strongly advised that non-public entities do not publish personal data in
-controller documents.
-
-
-
-It can be useful to express a binding of an identifier to a person's or
-organization's physical identity in a way that is provably asserted by a
-trusted authority, such as a government. This specification provides
-the 2.3.2 Assertion verification relationship for these
-purposes. This feature can enable interactions that are private and can be
-considered legally enforceable under one or more jurisdictions; establishing
-such bindings has to be carefully balanced against privacy considerations (see
-6. Privacy Considerations).
-
-
-
-The process of binding an identifier to something in the physical world, such as
-a person or an organization — for example, by using verifiable
-credentials with the same subject as that identifier — is contemplated
-by this specification and further defined in Verifiable Credentials Data Model v2.0.
-
-
-
-
-
-
-Even in cases where the subject referred to by an identifier proves
-control, the interpretation of the subject remains contextual and
-potentially ambiguous.
-
-
-
-For example, a school might issue a verifiable credential about the teacher
-of Intro to Computer Science, using
-https://controller.example/abc as a subject identifier, saying
-"https://controller.example/abc is the teacher of
-Intro to Computer Science" and
-"https://controller.example/abc controls access to the school's computer lab.
-See them to request access".
-
-
-
-In this usage, it is ambiguous whether https://controller.example/abc refers
-to a specific teacher or to whomever is the current teacher. Only with further
-statements might we be able to discern the difference. But it's still tricky.
-For example the subject in the following statement remains ambiguous:
-
-
-
-
-
Example 22: Statement about the name of https://controller.example/abc as RDF Triples
-
<https://controller.example/abc>
- <https://schema.org/name>
- "Bob Smith" .
-
-If https://controller.example/abc refers to a specific human being, then the
-statement is taken as an attestation about the particular human identified by
-that name. However, if https://controller.example/abc is used to refer to the
-_current_ teacher, it is also valid if the current teacher does have that
-name. In this case, the ambiguity is immaterial.
-
-
-
-However, in a statement like the following, the difference becomes vital.
-
-
-
-
-
Example 23: Legal statements the convicted status of https://controller.example/abc as RDF Triples
-
<https://controller.example/abc>
- <http://law.example/convicted>
- <http://calaw.example/PenalCode647b> .
-
-The statement in English could be "The person referred to by
-https://controller.example/abc has been convicted of California Penal Code
-647b." But which person(s) did we mean? Did we mean to say one, some, or all of
-the teachers of computer science at the school have been convicted of violating
-PenalCode647b? Or is it meant to say that a particular individual teacher,
-perhaps the one named "Bob Smith", has been convicted of said crime?
-
-
-
-The challenge is particularly difficult in situations where the subject is
-fundamentally uninvolved in the issuance of the verifiable credential.
-For example, an identifier might be used by a school to refer to a teacher,
-and students and or parents might use that identifier to make statements
-about the teacher, with neither the teacher nor the school involved. In these
-cases, it is easy to imagine that the subtle nuance of the school's intended
-meaning, for example, "any current teacher of the computer science class", gets
-lost and the identifier gets misused by parents and students to refer to a
-specific teacher, quite likely in contexts where neither the school nor the
-teacher is aware of the conversation.
-
-
-In natural language, these ambiguities are often easily ignored or corrected. In
-digital media, it is vital that context be evaluated to establish the intended
-referent, especially when identifiers are used in different contexts by
-different issuers, for example, on an official school website by the school,
-but in an unofficial social networking app by parents and students.
-
-
-In short, the context in which identifiers are created and used has to be
-considered when relying on any particular interpretation of the subject of
-any particular identifier.
-
-
-
-
-
-
-
-In a decentralized architecture, there might not be centralized authorities to
-enforce cryptographic material or cryptographic digital signature expiration
-policies. Therefore, it is with supporting software such as verification
-libraries that requesting parties validate that cryptographic materials were not
-expired at the time they were used. Requesting parties might employ their own
-expiration policies in addition to inputs into their verification processes. For
-example, some requesting parties might accept authentications from five minutes
-in the past, while others with access to high precision time sources might
-require authentications to be time stamped within the last 500 milliseconds.
-
-
-There are some requesting parties that have legitimate needs to extend the use
-of already-expired cryptographic material, such as verifying legacy
-cryptographic digital signatures. In these scenarios, a requesting party might
-instruct their verification software to ignore cryptographic key material
-expiration or determine if the cryptographic key material was expired at the
-time it was used.
-
-
-
-
-
-
-
-Rotation is a management process that enables the secret cryptographic material
-associated with an existing verification method to be deactivated or
-destroyed once a new verification method has been added to the
-controller document. Going forward, any new proofs that a
-controller would have generated using the old secret cryptographic
-material can now instead be generated using the new cryptographic material and
-can be verified using the new verification method.
-
-
-
-Rotation is a useful mechanism for protecting against verification method
-compromise, since frequent rotation of a verification method by the controller
-reduces the value of a single compromised verification method to an attacker.
-Performing revocation immediately after rotation is useful for verification
-methods that a controller designates for short-lived verifications, such as
-those involved in encrypting messages and authentication.
-
-
-
-The following considerations might be of use when contemplating the use of
-verification method rotation:
-
-
-
- -
-Verification method rotation is a proactive security measure.
-
- -
-It is generally considered a best practice to perform verification method
-rotation on a regular basis.
-
- -
-Higher security environments tend to employ more frequent verification method
-rotation.
-
- -
-Verification method rotation manifests only as changes to the current or
-latest version of a controller document.
-
- -
-When a verification method has been active for a long time, or used for
-many operations, a controller might wish to perform a rotation.
-
- -
-Frequent rotation of a verification method might be frustrating for
-parties that are forced to continuously renew or refresh associated credentials.
-
- -
-Proofs or signatures that rely on verification methods that are not
-present in the latest version of a controller document are not impacted by
-rotation. In these cases, verification software might require additional
-information, such as when a particular verification method was
-expected to be valid as well as access to a verifiable data registry
-containing a historical record, to determine the validity of the proof or
-signature. This option might not be available in all systems.
-
- -
-A controller performs a rotation when it adds a new verification
-method that is meant to replace an existing verification method after
-some time.
-
-
-
-
-
-
-
-
-Revocation is a management process that enables the secret cryptographic
-material associated with an existing verification method to be
-deactivated such that it ceases to be a valid form of creating new
-proofs.
-
-
-Revocation is a useful mechanism for reacting to a verification method
-compromise. Performing revocation immediately after rotation is useful for
-verification methods that a controller designates for short-lived verifications,
-such as those involved in encrypting messages and authentication.
-
-
-
-Compromise of the secrets associated with a verification method allows
-the attacker to use them according to the verification relationship
-expressed by controller in the controller document, for example, for
-authentication. The attacker's use of the secrets might be indistinguishable
-from the legitimate controller's use starting from
-the time the verification method was registered, to the time it was
-revoked.
-
-
-
-
-The following considerations might be of use when contemplating the use of
-verification method revocation:
-
-
-
- -
-Verification method revocation is a reactive security measure.
-
-
- -
-It is considered a best practice to support key revocation.
-
-
- -
-A controller is expected to immediately revoke any verification
-method that is known to be compromised.
-
-
- -
-Verification method revocation can only be embodied in changes to
-the latest version of a controller document; it cannot retroactively adjust
-previous versions.
-
-
- -
-If a verification method is no longer exclusively accessible to the
-controller or parties trusted to act on behalf of the controller,
-it is expected to be revoked immediately to reduce the risk of
-compromises such as masquerading, theft, and fraud.
-
-
- -
-Revocation is expected to be understood as a controller expressing that
-proofs or signatures associated with a revoked verification method
-created after its revocation should be treated as invalid. It could also imply a
-concern that existing proofs or signatures might have been created by an
-attacker, but this is not necessarily the case. Verifiers, however, might still
-choose to accept or reject any such proofs or signatures at their own
-discretion.
-
-
- -
-Even if a verification method is present in a controller document,
-additional information, such as a public key revocation certificate, or an
-external allow or deny list, could be used to determine whether a
-verification method has been revoked.
-
-
- -
-The day-to-day operation of any software relying on a compromised
-verification method, such as an individual's operating system, antivirus,
-or endpoint protection software, could be impacted when the verification
-method is publicly revoked.
-
-
-
-
-
-
-
-Although verifiers might choose not to accept proofs or signatures from a
-revoked verification method, knowing whether a verification was made with a
-revoked verification method is trickier than it might seem. Some auditing
-systems provide the ability to look back at the state of an identifier at a
-point in time, or at a particular version of the controller document.
-When such a feature is combined with a reliable way to determine the time or
-identifier version that existed when a cryptographically verifiable statement
-was made, then revocation does not undo that statement. This can be the basis
-for using digital signatures to make binding commitments; for example, to sign
-a mortgage.
-
-
-If these conditions are met, revocation is not retroactive; it only nullifies
-future use of the method.
-
-
-However, in order for such semantics to be safe, the second condition — an
-ability to know what the state of the controller document was at the time
-the assertion was made — is expected to apply. Without that guarantee,
-someone could discover a revoked key and use it to make cryptographically
-verifiable statements with a simulated date in the past.
-
-
-Some auditing systems only allow the retrieval of the current state of a
-identifier. When this is true, or when the state of an identifier at the time of
-a cryptographically verifiable statement cannot be reliably determined, then the
-only safe course is to disallow any consideration of state with respect to time,
-except the present moment. Identifier ecosystems that take this approach
-essentially provide cryptographically verifiable statements as ephemeral tokens
-that can be invalidated at any time by the controller.
-
-
-
-
-
-
-
-
-
-Encryption algorithms have been known to fail due to advances in cryptography
-and computing power. Implementers are advised to assume that any encrypted data
-placed in a controller document might eventually be made available in clear text
-to the same audience to which the encrypted data is available. This is
-particularly pertinent if the controller document is public.
-
-
-Encrypting all or parts of a controller document is not an appropriate
-means to protect data in the long term. Similarly, placing encrypted data in
-a controller document is not an appropriate means to protect personal data.
-
-
-Given the caveats above, if encrypted data is included in a controller document,
-implementers are advised to not associate any correlatable information
-that could be used to infer a relationship between the encrypted data
-and an associated party. Examples of correlatable information include
-public keys of a receiving party, identifiers to digital assets known to be
-under the control of a receiving party, or human readable descriptions of a
-receiving party.
-
-
-
-
-
-
-
-Controller documents that include links to external machine-readable
-content such as images, web pages, or schemas are vulnerable to tampering. It is
-strongly advised that external links are integrity protected using mechanisms to
-secure related resources such as those described in the Verifiable Credentials Data Model v2.0
-specification. External links are to be avoided if they cannot be integrity
-protected and the controller document's integrity is dependent on the
-external link.
-
-
-One example of an external link where the integrity of the controller
-document itself could be affected is the JSON-LD Context [JSON-LD11],
-when present. To protect against compromise,
-controller document consumers using JSON-LD are advised to cache
-local static copies of JSON-LD contexts and/or verify the integrity of external
-contexts against a cryptographic hash that is known to be associated with a safe
-version of the external JSON-LD Context.
-
-
-
-
-
-
-
-As described in Section 2.1.2 Controllers, this specification includes a
-mechanism by which to delegate change control of a controller document to
-an entity that is described in an external controller document through the
-use of the controller property.
-
-
-
-Delegating change control addresses a number of use cases including those
-where the care of an entity is the responsibility of some other entity or
-entities, as well as those where some entity desires that another entity
-provide account recovery services, among other use cases. In such scenarios,
-it can be beneficial to allow the guardian to manage the rotation of their
-own key material. It can also be beneficial for the delegator to associate
-a cryptographic hash of the remote controller document to "pin" the
-remote document to a known good value.
-
-
-
-While this document does not specify a particular mechanism for
-cryptographically protected URLs, the relatedResource property in
-Verifiable Credentials Data Model v2.0 and the digestMultibase property in
-Verifiable Credential Data Integrity 1.0 could be employed by a mechanism that can provide
-such protection.
-
-
-
-
-
-
-
-
-Additional information about the security context of authentication events is
-often required for compliance reasons, especially in regulated areas such as the
-financial and public sectors. This information is often referred to as a Level
-of Assurance (LOA). Examples include the protection of secret cryptographic
-material, the identity proofing process, and the form-factor of the
-authenticator.
-
-
-
-
-Payment services (PSD 2) and
-eIDAS introduce such requirements to the security context. Level of
-assurance frameworks are classified and defined by regulations and
-standards such as
-eIDAS, NIST 800-63-3 and ISO/IEC
-29115:2013, including their requirements for the security context, and
-making recommendations on how to achieve them. This might include strong user
-authentication where FIDO2/WebAuthn can fulfill the
-requirement.
-
-
-
-Some regulated scenarios require the implementation of a specific level of
-assurance. Since verification relationships used to perform
-assertion and authentication might be
-used in some of these situations, information about the applied security context
-might need to be expressed and provided to a verifier. Whether and how
-to encode this information in the controller document data model is out
-of scope for this specification. Interested readers might note that 1) the
-information could be transmitted using Verifiable Credentials
-[VC-DATA-MODEL-2.0], and 2) the controller document data model can be
-extended to incorporate this information.
-
-
-
-
-
-
-
-If a controller document publishes a service intended for authentication
-or authorization of the subject (see Section 2.1.4 Services), it is the
-responsibility of the service provider, subject, and/or requesting party
-to comply with the requirements of the authentication and/or authorization
-protocols supported by that service endpoint.
-
-
-
-
-
- This section is non-normative.
-
-
-
-The specification authors would like to thank the contributors to the
-
-W3C Decentralized Identifiers (DIDs) v1.0 specification upon which this work
-is based.
-
-
-
-The Working Group gratefully acknowledges the work that led to the creation of
-this specification, and extends sincere appreciation to those individuals that
-worked on technologies and specifications that deeply influenced our work. In
-particular, this includes the work of Phil Zimmerman, Jon Callas, Lutz
-Donnerhacke, Hal Finney, David Shaw, and Rodney Thayer on Pretty Good Privacy
-(PGP) in the 1990s and 2000s.
-
-
-
-In the mid-2010s, preliminary implementations of what would become Decentralized
-Identifiers were
-built in collaboration with Jeremie Miller's Telehash project and the W3C
-Web Payments Community Group's work led by Dave Longley and Manu Sporny. Around
-a year later, the XDI.org Registry Working Group
-
-began exploring decentralized technologies for replacing its existing
-identifier registry. Some of the first
-written
-papers
-exploring the concept of Decentralized Identifiers can be traced back to the
-first several Rebooting the Web of Trust workshops convened by Christopher
-Allen. That work led to a key collaboration between Christopher Allen, Drummond
-Reed, Les Chasen, Manu Sporny, and Anil John. Anil saw promise in the technology
-and allocated the initial set of government funding to explore the space.
-Without the support of Anil John and his guidance through the years, it is
-unlikely that Decentralized Identifiers would be where they are today. Further
-refinement at the Rebooting the Web of Trust workshops led to the first
-implementers documentation, edited by Drummond Reed, Les Chasen, Christopher
-Allen, and Ryan Grant. Contributors included Manu Sporny, Dave Longley, Jason
-Law, Daniel Hardman, Markus Sabadello, Christian Lundkvist, and Jonathan
-Endersby. This initial work was then merged into the W3C Credentials Community
-Group, incubated further, and then transitioned to the W3C Decentralized
-Identifiers Working Group for global standardization. That work was then used
-as the basis for this, more generalized and less decentralized, specification.
-
-
-
-Portions of the work on this specification have been funded by the United States
-Department of Homeland Security's (US DHS) Science and Technology Directorate
-under contracts HSHQDC-16-R00012-H-SB2016-1-002, and HSHQDC-17-C-00019, as well
-as the US DHS Silicon Valley Innovation Program under contracts
-70RSAT20T00000003, 70RSAT20T00000010/P00001, 70RSAT20T00000029,
-70RSAT20T00000030, 70RSAT20T00000033, 70RSAT20T00000045,
-70RSAT21T00000016/P00001, 70RSAT23T00000005, 70RSAT23C00000030, and
-70RSAT23R00000006. The content of this specification does not necessarily
-reflect the position or the policy of the U.S. Government and no official
-endorsement should be inferred.
-
-
-
-Portions of the work on this specification have also been funded by the European
-Union's StandICT.eu program under sub-grantee contract number CALL05/19. The
-content of this specification does not necessarily reflect the position or the
-policy of the European Union and no official endorsement should be inferred.
-
-
-
-We would also like to thank the base-x software library contributors and the
-Bitcoin Core developers who wrote the original code, shared under an MIT
-License, found in Section 3.1 Base Encode and Section 3.2 Base Decode.
-
-
-
-Work on this specification has also been supported by the
-Rebooting the Web of Trust community
-facilitated by Christopher Allen, Shannon Appelcline, Kiara Robles, Brian
-Weller, Betty Dhamers, Kaliya Young, Kim Hamilton Duffy, Manu Sporny, Drummond
-Reed, Joe Andrieu, Heather Vescent, Samantha Chase, Andrew Hughes, Erica
-Connell, Shigeya Suzuki, and Zaïda Rivai. Development of this specification has
-also been supported by the
-W3C Credentials Community Group, which
-has been Chaired by Kim Hamilton Duffy, Joe Andrieu, Christopher Allen, Heather
-Vescent, and Wayne Chang. The participants in the Internet Identity Workshop,
-facilitated by Phil Windley, Kaliya Young, Doc Searls, and Heidi Nobantu Saul,
-also supported this work through numerous working sessions designed to debate,
-improve, and educate participants about this specification.
-
-
-
-The Working Group thanks the following individuals for their contributions to
-this specification (in alphabetical order, Github handles start with @ and
-are sorted as last names): Denis Ah-Kang, Nacho Alamillo, Christopher Allen, Joe
-Andrieu, Antonio, Phil Archer, George Aristy, Baha, Juan Benet, BigBlueHat, Dan
-Bolser, Chris Boscolo, Pelle Braendgaard, Daniel Buchner, Daniel Burnett, Juan
-Caballero, @cabo, Tim Cappalli, Melvin Carvalho, David Chadwick, Wayne Chang,
-Sam Curren, Hai Dang, Tim Daubenschütz, Oskar van Deventer, Kim Hamilton Duffy,
-Arnaud Durand, Ken Ebert, Veikko Eeva, @ewagner70, Carson Farmer, Nikos Fotiou,
-Gabe, Gayan, @gimly-jack, @gjgd, Ryan Grant, Peter Grassberger, Adrian Gropper,
-Amy Guy, Daniel Hardman, Kyle Den Hartog, Philippe Le Hegaret, Ivan Herman,
-Michael Herman, Alen Horvat, Dave Huseby, Marcel Jackisch, Mike Jones, Andrew
-Jones, Tom Jones, jonnycrunch, Gregg Kellogg, Michael Klein, @kdenhartog-sybil1,
-Paul Knowles, @ktobich, David I. Lehn, Charles E. Lehner, Michael Lodder,
-@mooreT1881, Dave Longley, Tobias Looker, Wolf McNally, Robert Mitwicki, Mircea
-Nistor, Grant Noble, Mark Nottingham, @oare, Darrell O'Donnell, Vinod Panicker,
-Dirk Porsche, Praveen, Mike Prorock, @pukkamustard, Drummond Reed, Julian
-Reschke, Yancy Ribbens, Justin Richer, Rieks, @rknobloch, Mikeal Rogers,
-Evstifeev Roman, Troy Ronda, Leonard Rosenthol, Michael Ruminer, Markus
-Sabadello, Cihan Saglam, Samu, Rob Sanderson, Wendy Seltzer, Mehran Shakeri,
-Jaehoon (Ace) Shim, Samuel Smith, James M Snell, SondreB, Manu Sporny, @ssstolk,
-Orie Steele, Shigeya Suzuki, Sammotic Switchyarn, @tahpot, Oliver Terbu, Ted
-Thibodeau Jr., Joel Thorstensson, Tralcan, Henry Tsai, Rod Vagg, Mike Varley,
-Kaliya "Identity Woman" Young, Eric Welton, Fuqiao Xue, @Yue, Dmitri Zagidulin,
-@zhanb, and Brent Zundel.
-
-
-
-
-
-
-
-