A controller document is a set of data that specifies one or more
relationships between a controller and a set of data, such as a set of
public cryptographic keys.
Status of This Document
This section describes the status of this
document at the time of its publication. A list of current W3C
publications and the latest revision of this technical report can be found
in the W3C technical reports index at
https://www.w3.org/TR/.
Publication as a Working Draft does not
imply endorsement by W3C and its Members.
This is a draft document and may be updated, replaced or obsoleted by other
documents at any time. It is inappropriate to cite this document as other
than work in progress.
This document was produced by a group
operating under the
W3C Patent
Policy.
W3C maintains a
public list of any patent disclosures
made in connection with the deliverables of
the group; that page also includes
instructions for disclosing a patent. An individual who has actual
knowledge of a patent which the individual believes contains
Essential Claim(s)
must disclose the information in accordance with
section 6 of the W3C Patent Policy.
It is expected that other specifications using this specification
will profile the features that it defines,
requiring and/or recommending the use of some and
prohibiting and/or deprecating the use of others.
1.1 Conformance
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, and SHOULD in this document
are to be interpreted as described in
BCP 14
[RFC2119] [RFC8174]
when, and only when, they appear in all capitals, as shown here.
A conforming controller document is any concrete expression of the
data model that follows the relevant normative requirements in Sections
2. Data Model and 4. Contexts and Vocabularies.
A conforming 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.
1.2 Terminology
This section is non-normative.
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.
A set of data that specifies one or more relationships between a
controller and a set of data, such as a set of public cryptographic keys.
cryptographic suite
A means of using specific cryptographic primitives
to achieve a particular security goal. These suites can
specify verification methods, digital signature types,
their identifiers, and other related properties.
private key
Cryptographic material that can be used to generate digital proofs.
public key
Cryptographic material that can be used to verify digital proofs created with a
corresponding private key.
subject
The entity identified by the id property in a controller document.
Anything can be a subject: person, group, organization, physical thing, digital
thing, logical thing, etc.
verification method
A set of parameters that can be used together with a process to independently
verify a proof. For example, a cryptographic public key can be used as a
verification method with respect to a digital signature; in such use, it
verifies that the signer possessed the associated cryptographic private key.
"Verification" and "proof" in this definition are intended to apply broadly. For
example, a cryptographic public key might be used during Diffie-Hellman key
exchange to negotiate a shared symmetric key for encryption. This guarantees the
integrity of the key agreement process. It is thus another type of verification
method, even though descriptions of the process might not use the words
"verification" or "proof."
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.
2.1 Controller Documents
The following sections define the properties in a controller document,
including whether these properties are required or optional. These properties
describe relationships between the subject and the value of the
property.
The following tables contain informative references for the core properties
defined by this specification, with expected values, and whether or not they are
required. The property names in the tables are linked to the normative
definitions and more detailed descriptions of each property.
The controller property is OPTIONAL. If present, its value MUST
be a string or a set of strings, each of which conforms to the rules in
the URL Standard. The corresponding controller document(s) SHOULD
contain verification relationships that explicitly permit the use of
certain verification methods for specific purposes. If the controller
property is not present, the value expressed by the id property MUST be
treated as if it were also set as the value of the controller property.
When a controller property is present in a controller document, its
value expresses one or more identifiers. Any verification methods contained
in the controller documents for those identifiers SHOULD
be accepted as authoritative, such that proofs that satisfy those
verification methods are considered equivalent to proofs provided
by the subject.
Example 4: Controller document with a controller property
Note that authorization provided by the value of controller is
separate from authentication as described in Section 2.3.1 Authentication.
This is particularly important for key recovery in the cases of cryptographic key
loss, where the subject no longer has access to their keys, or cryptographic
key compromise, where the controller's trusted third parties need to
override malicious activity by an attacker. See 5. Security Considerations
for information related to threat models and attack vectors.
2.1.3 Also Known As
A subject can have multiple identifiers that are used for different purposes
or at different times. The assertion that two or more identifiers (or other types
of URI) refer to the same subject can be made using the
alsoKnownAs property.
alsoKnownAs
The alsoKnownAs property is OPTIONAL. If present, its value MUST
be a set where each item in the
set is a URI conforming to [RFC3986].
This relationship is a statement that the subject of this identifier is
also identified by one or more other identifiers.
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.
2.2 Verification Methods
A controller document can express verification methods, such as
cryptographic public keys, which can be used to authenticate or
authorize interactions with the controller or associated parties. For
example, a cryptographic public key can be used as a verification
method with respect to a digital signature; in such use, it verifies that
the signer could use the associated cryptographic private key. Verification
methods might take many parameters. An example of this is a set of five
cryptographic keys from which any three are required to contribute to a
cryptographic threshold signature.
The value of the type property MUST be a string that references exactly one verification
method type.
controller
The value of the controller property MUST be a string that conforms to the [URL] syntax.
revoked
The revoked property is OPTIONAL.
If present, it MUST be an [XMLSCHEMA11-2]
dateTimeStamp string specifying when the verification methodSHOULD cease to be used. Once the value is set, it is not expected to be
updated, and systems depending on the value are expected to not verify any
proofs associated with the verification method at or after the time of
revocation.
Note: Verification method controller(s) and controller(s)
The semantics of the controller property are the same when the
subject of the relationship is the controller document as when the subject of
the relationship is a verification method, such as a cryptographic public
key. Since a key can't control itself, and the key controller cannot be inferred
from the controller document, it is necessary to explicitly express the identity
of the controller of the key. The difference is that the value of
controller for a verification method is not
necessarily a controller. Controllers are expressed
using the controller property at the highest level of the
controller document.
To increase the likelihood of interoperable implementations, this specification
limits the number of formats for expressing verification material in a
controller document. The fewer formats that implementers have to
implement, the more likely it will be that they will support all of them. This
approach attempts to strike a delicate balance between easing implementation
and providing support for formats that have historically had broad deployment.
A verification methodMUST 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.
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 7: Multikey encoding of a Ed25519 public key
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.
2.2.3 JsonWebKey
The JSON Web Key (JWK) data model is a specific type of verification method
that uses the JWK specification [RFC7517] to encode key types into a
set of parameters.
When specifing a JsonWebKey, the object takes the following form:
type
The value of the type property MUST contain the string JsonWebKey.
publicKeyJwk
The publicKeyJwk property is OPTIONAL. If present, its value MUST
be a map representing a JSON Web Key that
conforms to [RFC7517]. The mapMUST 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 6 for an example of a
public key with a compound key identifier.
As specified in Section 4.4 of the JWK specification,
the OPTIONALalg 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 REQUIREDcrv 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 OPTIONALkid 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 8: JSON Web Key encoding of a secp384r1 (P-384) public key
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 9: JSON Web Key encoding of a secp384r1 (P-384) secret key
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).
If the value of a verification method property is a map, the verification method has been
embedded and its properties can be accessed directly. However, if the value is a
URL string, the verification method has
been included by reference and its properties will need to be retrieved from
elsewhere in the controller document or from another controller document. This
is done by dereferencing the URL and searching the resulting resource for a
verification methodmap with an
id property whose value matches the URL.
Example 10: 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"
}
],
...
}
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 authenticationverification relationship is used to
specify how the controller is expected to be authenticated, for
purposes such as logging into a website or engaging in any sort of
challenge-response protocol.
authentication
The authentication property is OPTIONAL. If present, its
value MUST be a set of one or more
verification methods. Each verification methodMAY be embedded or
referenced.
Example 11: Authentication property
containing three verification methods
{
"@context": [
"https://www.w3.org/ns/controller/v1",
"https://www.w3.org/ns/credentials/v2",
"https://w3id.org/security/multikey/v1"
],
"id": "https://controller.example/123456789abcdefghi",
...
"authentication": [
// this method can be used to authenticate as did:...fghi
"https://controller.example/123456789abcdefghi#keys-1",
// this method is *only* approved for authentication, so its// full description is embedded here rather than using only a reference
{
"id": "https://controller.example/123456789abcdefghi#keys-2",
"type": "JsonWebKey",
"controller": "https://controller.example/123456789abcdefghi",
"publicKeyJwk": {
"crv": "Ed25519",
"x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOyPVQaO3FxVeQ",
"kty": "OKP",
"kid": "_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A"
}
},
{
"id": "https://controller.example/123456789abcdefghi#keys-3",
"type": "Multikey",
"controller": "https://controller.example/123456789abcdefghi",
"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
}
],
...
}
If authentication is established, it is up to the application to decide what to
do with that information.
This is useful to any authentication verifier that needs to check to
see if an entity that is attempting to authenticate is, in fact,
presenting a valid proof of authentication. When a verifier receives
some data (in some protocol-specific format) that contains a proof that was made
for the purpose of "authentication", and that says that an entity is identified
by the id, then that verifier checks to ensure that the proof can be
verified using a verification method (e.g., public key) listed
under authentication in the controller document.
The assertionMethodverification relationship is used to
specify how the controller is expected to express claims, such as for
the purposes of issuing a verifiable credential.
assertionMethod
The assertionMethod property is OPTIONAL. If present, its associated
value MUST be a set of one or
more verification methods. Each verification methodMAY
be embedded or referenced.
This property is useful, for example, during the processing of a
verifiable credential by a verifier.
Example 12: Assertion method property
containing two verification methods
{
"@context": [
"https://www.w3.org/ns/controller/v1",
"https://www.w3.org/ns/credentials/v2",
"https://w3id.org/security/multikey/v1"
],
"id": "https://controller.example/123456789abcdefghi",
...
"assertionMethod": [
// this method can be used to assert statements as did:...fghi
"https://controller.example/123456789abcdefghi#keys-1",
// this method is *only* approved for assertion of statements, it is not// used for any other verification relationship, so its full description is// embedded here rather than using a reference
{
"id": "https://controller.example/123456789abcdefghi#keys-2",
"type": "Multikey", // external (property value)
"controller": "https://controller.example/123456789abcdefghi",
"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
}
],
...
}
2.3.3 Key Agreement
The keyAgreementverification 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 methodMAY 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 13: Key agreement property
containing two verification methods
{
"@context": "https://www.w3.org/ns/did/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 property is OPTIONAL. If present, the
associated value MUST be a set of
one or more verification methods. Each verification methodMAY be
embedded or referenced.
An example of when this property is useful is when a controller needs to
access a protected HTTP API that requires authorization in order to use it. In
order to authorize when using the HTTP API, the controller
uses a capability that is associated with a particular URL that is
exposed via the HTTP API. The invocation of the capability could be
expressed in a number of ways, e.g., as a digitally signed
message that is placed into the HTTP Headers.
The server providing the HTTP API is the verifier of the capability and
it would need to verify that the verification method referred to by the
invoked capability exists in the capabilityInvocation
property of the controller document. The verifier would also check to make sure
that the action being performed is valid and the capability is appropriate for
the resource being accessed. If the verification is successful, the server has
cryptographically determined that the invoker is authorized to access the
protected resource.
Example 14: Capability invocation property
containing two verification methods
{
"@context": [
"https://www.w3.org/ns/controller/v1",
"https://w3id.org/security/multikey/v1"
],
"id": "https://controller.example/123456789abcdefghi",
...
"capabilityInvocation": [
// this method can be used to invoke capabilities as https:...fghi
"https://controller.example/123456789abcdefghi#keys-1",
// this method is *only* approved for use in capability invocation; it will not// be used for any other verification relationship, so its full description is// embedded here rather than using only a reference
{
"id": "https://controller.example/123456789abcdefghi#keys-2",
"type": "Multikey", // external (property value)
"controller": "https://controller.example/123456789abcdefghi",
"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
}
],
...
}
2.3.5 Capability Delegation
The capabilityDelegationverification relationship is used
to specify a mechanism that might be used by the controller to delegate
a cryptographic capability to another party, such as delegating the authority
to access a specific HTTP API to a subordinate.
capabilityDelegation
The capabilityDelegation property is OPTIONAL. If present, the
associated value MUST be a set of
one or more verification methods. Each verification methodMAY 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
capabilityDelegationverification 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 15: Capability Delegation property
containing two verification methods
{
"@context": [
"https://www.w3.org/ns/controller/v1",
"https://w3id.org/security/multikey/v1"
],
"id": "https://controller.example/123456789abcdefghi",
...
"capabilityDelegation": [
// this method can be used to perform capability delegation as did:...fghi
"https://controller.example/123456789abcdefghi#keys-1",
// this method is *only* approved for granting capabilities; it will not// be used for any other verification relationship, so its full description is// embedded here rather than using only a reference
{
"id": "https://controller.example/123456789abcdefghi#keys-2",
"type": "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"
}
],
...
}
2.4 Multibase
A Multibase string includes a single character header which identifies the
base and encoding alphabet used to encode a binary value, followed by the
encoded binary value (using that base and alphabet). The common Multibase
header values and their associated base encoding alphabets as provided below
are normative:
Multibase Header
Description
u
The base-64-url-no-pad alphabet is used to encode the bytes. The base-alphabet
consists of the following characters, in order:
ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_
z
The base-58-btc alphabet is used to encode the bytes. The base-alphabet consists
of the following characters, in order:
123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz
Other Multibase encoding values MAY be used, but interoperability is not
guaranteed between implementations using such values.
To base-encode a binary value into a Multibase string, an implementation MUST
apply the algorithm in Section 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.
2.5 Multihash
A Multihash value starts with a binary header, which includes 1) an identifier
for the specific cryptographic hash algorithm, 2) the length of the
cryptographic hash, and 3) the value of the cryptographic hash. The normative
Multihash header values defined by this specification, and their associated
output sizes and associated specifications, are provided below:
Multihash Identifier
Multihash Header
Description
sha2-256
0x12
SHA-2 with 256 bits (32 bytes) of output, as defined by [RFC6234].
sha2-384
0x20
SHA-2 with 384 bits (48 bytes) of output, as defined by [RFC6234].
sha3-256
0x16
SHA-3 with 256 bits (32 bytes) of output, as defined by [SHA3].
sha3-384
0x15
SHA-3 with 384 bits (48 bytes) of output, as defined by [SHA3].
Other Multihash encoding values MAY be used, but interoperability is not
guaranteed between implementations.
To encode to a Multihash value, an implementation MUST concatenate the
associated Multihash header, the cryptographic hash length, and the
cryptographic hash value, in that order.
To decode a Multihash value, an implementation MUST 1) remove the prepended
Multihash header value, which identifies the type of cryptographic hashing
algorithm, 2) remove the output length, and 3) extract the raw cryptographic
hash value which MUST match the expected output length associated with the
Multihash header as well as the output length provided in the Multihash
value itself.
3. Algorithms
This section defines algorithms used by this specification including
instructions on how to base-encode and base-decode values, safely retrieve
verification methods, and produce processing errors over HTTP channels.
3.1 Base Encode
The following algorithm specifies how to encode an array of bytes, where each
byte represents a base-256 value, to a different base representation that uses a
particular base alphabet, such as base-64-url-no-pad or base-58-btc. The
required inputs are the bytes, targetBase, and
baseAlphabet. The output is a string that contains the base-encoded
value. All mathematical operations MUST be performed using integer arithmetic.
Alternatives to the algorithm provided below MAY be used as long as the
outputs of the alternative algorithm remain the same.
Initialize the following variables; zeroes to 0, length to
0, begin to 0, and end to the length of
bytes.
Set begin and zeroes to the number of leading 0 byte
values in bytes.
Set baseValue to an empty byte array that is the size of the final
base-expanded value. Calculate the final size of baseValue
by dividing log(256) by log(targetBase) and then multiplying the
length of bytes minus the leading zeroes. Add 1 to the
value of size.
Process each byte in bytes as byte starting at offset
begin:
Set the carry value to byte.
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.
Multiply the value in baseValue[basePosition] by 256 and add
it to carry.
Set the value at baseValue[basePosition] to the remainder after
dividing carry by targetBase.
Set the value of carry to carry divided by
targetBase ensuring that integer division is used to perform the
division.
Decrement basePosition by 1 and increment i by 1.
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 16: An implementation of the general base-encoding algorithm above in Javascript
functionbaseEncode(bytes, targetBase, baseAlphabet) {
let zeroes = 0;
let length = 0;
let begin = 0;
let end = bytes.length;
// count the number of leading bytes that are zerowhile(begin !== end && bytes[begin] === 0) {
begin++;
zeroes++;
}
// allocate enough space to store the target base valueconst baseExpansionFactor = Math.log(256) / Math.log(targetBase);
let size = Math.floor((end - begin) * baseExpansionFactor + 1);
let baseValue = newUint8Array(size);
// process the entire input byte arraywhile(begin !== end) {
let carry = bytes[begin];
// for each byte in the array, perform base-expansionlet 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 resultlet baseEncodingPosition = size - length;
while(baseEncodingPosition !== size &&
baseValue[baseEncodingPosition] === 0) {
baseEncodingPosition++;
}
// convert the base value to the base encodinglet baseEncoding = baseAlphabet.charAt(0).repeat(zeroes)
for(; baseEncodingPosition < size; ++baseEncodingPosition) {
baseEncoding += baseAlphabet.charAt(baseValue[baseEncodingPosition])
}
return baseEncoding;
}
3.2 Base Decode
The following algorithm specifies how to decode an array of bytes, where each
byte represents a base-encoded value, to a different base representation that
uses a particular base alphabet, such as base-64-url-no-pad or base-58-btc. The
required inputs are the sourceEncoding, sourceBase, and
baseAlphabet. The output is an array of bytes that contains the
base-decoded value. All mathematical operations MUST be performed using integer
arithmetic. Alternatives to the algorithm provided below MAY be used as long as
the outputs of the alternative algorithm remain the same.
Initialize a baseMap mapping by associating each character
in baseAlphabet to its integer position in the
baseAlphabet string.
Initialize the following variables; sourceOffset to 0,
zeroes to 0, and decodedLength to 0.
Set zeroes and sourceOffset to the number of leading
baseAlphabet[0] values in sourceEncoding.
Set decodedBytes to an empty byte array that is the size of the final
base-converted value. Calculate the size of decodedBytes
by dividing log(sourceBase) by log(256) and then multiplying by the
length of sourceEncoding minus the leading zeroes. Add 1 to the value
of size.
Process each character in sourceEncoding as character
starting at offset sourceOffset:
Set the carry value to the integer value in the baseMap
that is associated with character.
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:
Add the result of multiplying sourceBase by
decodedBytes[byteOffset] to carry.
Set decodedBytes[byteOffset] to the remainder of
dividing carry by 256.
Set carry to carry divided by 256, ensuring that integer
division is used to perform the division.
Decrement byteOffset by 1 and increment i by 1.
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 17: An implementation of the general base-decoding algorithm above in Javascript
functionbaseDecode(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 sourceEncodinglet sourceOffset = 0;
let zeroes = 0;
let decodedLength = 0;
while(sourceEncoding[sourceOffset] === baseAlphabet[0]) {
zeroes++;
sourceOffset++;
}
// allocate the decoded byte arrayconst baseContractionFactor = Math.log(sourceBase) / Math.log(256);
let decodedSize = Math.floor((
(sourceEncoding.length - sourceOffset) * baseContractionFactor) + 1);
let decodedBytes = newUint8Array(decodedSize);
// perform base-conversion on the source encodingwhile(sourceEncoding[sourceOffset]) {
// process each base-encoded numberlet carry = baseMap[sourceEncoding[sourceOffset]];
// convert the base-encoded number by performing base-expansionlet i = 0for(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 arraylet decodedOffset = decodedSize - decodedLength;
while(decodedOffset !== decodedSize && decodedBytes[decodedOffset] === 0) {
decodedOffset++;
}
// create the final byte array that has been base-decodedlet finalBytes = newUint8Array(zeroes + (decodedSize - decodedOffset));
let j = zeroes;
while(decodedOffset !== decodedSize) {
finalBytes[j++] = decodedBytes[decodedOffset++];
}
return finalBytes;
}
3.3 Retrieve Verification Method
The following algorithm specifies how to safely retrieve a verification method,
such as a cryptographic public key, by using a verification method
identifier. Required inputs are a
verification method (verificationMethod), a
verification relationship
(verificationRelationship), and a set of dereferencing
options (options). A
verification method is produced as output.
Let vmIdentifier be set to verificationMethod.
If vmIdentifier is not a valid URL, an error MUST be raised and SHOULD
convey an error type of
INVALID_VERIFICATION_METHOD_URL.
Let controllerDocumentUrl be the result of parsing
vmIdentifier according to the rules of the URL scheme and extracting
the primary resource identifier (without the fragment identifier).
Let vmFragment be the result of parsing vmIdentifier
according to the rules of the URL scheme and extracting the secondary
resource identifier (the fragment identifier).
Let controllerDocument be the result of dereferencing
controllerDocumentUrl, according to the rules
of the URL scheme and using the supplied options.
If controllerDocument.id does not match the
controllerDocumentUrl, an error MUST be raised and SHOULD
convey an error type of
INVALID_CONTROLLER_DOCUMENT_ID.
Let verificationMethod be the result of dereferencing the
vmFragment from the controllerDocument according to the
rules of the media type of the controllerDocument.
Return verificationMethod as the
verification method.
The following example provides a minimum conformant
controller document containing a minimum conformant
verification method as required by the algorithm in this section:
Example 18: Minimum conformant controller document
{
"id": "https://controller.example/123",
"verificationMethod": [{
"id": "https://controller.example/123#key-456",
"type": "ExampleVerificationMethodType",
"controller": "https://controller.example/123",
// public cryptographic material goes here
}],
"authentication": ["#key-456"]
}
3.4 Processing Errors
The algorithms described in this specification throw specific types of errors.
Implementers might find it useful to convey these errors to other libraries or
software systems. This section provides specific URLs, descriptions, and error
codes for the errors, such that an ecosystem implementing technologies described
by this specification might interoperate more effectively when errors occur.
When exposing these errors through an HTTP interface, implementers SHOULD use
[RFC9457] to encode the error data structure. If [RFC9457] is used:
The type value of the error object MUST be a URL that starts with the value
https://w3id.org/security# and ends with the value in the section listed
below.
The code value MUST be the integer code described in the table below
(in parentheses, beside the type name).
The title value SHOULD provide a short but specific human-readable string for
the error.
The detail value SHOULD provide a longer human-readable string for the error.
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.
Implementations that perform JSON-LD processing MUST treat the following
JSON-LD context URLs as already resolved, where the resolved document matches
the corresponding hash values below:
The security vocabulary terms that the JSON-LD contexts listed above resolve
to are in the https://w3id.org/security#
namespace. That is, all security terms in this vocabulary are of the form
https://w3id.org/security#TERM, where TERM is the name of a term.
Implementations that perform RDF processing MUST treat the following
JSON-LD vocabulary URL as already resolved, where the resolved document matches
the corresponding hash values below.
When dereferencing the
https://w3id.org/security# URL,
the data returned depends on HTTP content negotiation. These are as follows:
It is possible to confirm the digests listed above by running the following
command from a modern Unix command interface line:
curl -sL -H "Accept: <MEDIA_TYPE>" <DOCUMENT_URL> | openssl dgst -sha256.
Authors of application-specific vocabularies and specifications SHOULD ensure
that their JSON-LD context and vocabulary files are permanently cacheable
using the approaches to caching described above or a functionally equivalent
mechanism.
Implementations MAY load application-specific JSON-LD context files from the
network during development, but SHOULD permanently cache JSON-LD context files
used in conforming documents in production settings to increase their
security and privacy characteristics. Caching goals MAY be achieved through
approaches such as those described above or functionally equivalent mechanisms.
Some applications, such as digital wallets, that are capable of holding arbitrary
verifiable credentials or other data-integrity-protected documents, from
any issuer and using any contexts, might need to be able to load externally
linked resources, such as JSON-LD context files, in production settings. This is
expected to increase user choice, scalability, and decentralized upgrades in the
ecosystem over time. Authors of such applications are advised to read the
security and privacy sections of this document for further considerations.
The @context property is used by implementations that employ JSON-LD 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 type are processed and its values, such
as DataIntegrityProof, are used.
If an @context property is not provided in a document that is being secured or
verified, or any Data Integrity terms used in the document are not mapped by
existing values in the @context property, implementations using JSON-LD MUST inject or add
an @context property with a value of
https://www.w3.org/ns/controller/v1.
Context injection is expected to be unnecessary sometimes, such as when the Verifiable
Credential Data Model v2.0 context (https://www.w3.org/ns/credentials/v2)
exists as a value in the @context property, as that context maps all of the
necessary Data Integrity terms that were previously mapped by
https://w3id.org/security/data-integrity/v2.
4.2 Datatypes
This section defines datatypes that are used by this specification.
4.2.1 The multibase Datatype
Multibase-encoded strings are used to encode binary
data into ASCII-only formats, 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 Multibase character 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 Multibase character in the lexical string.
The canonical mapping
The canonical mapping consists of using the lexical-to-value mapping.
5. Security Considerations
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.
5.1 Proving Control and Binding
Binding an entity in the digital world or the physical world to an identifier, to
a controller document, or to cryptographic material requires the use of
security protocols contemplated by this specification. The following sections
describe some possible scenarios and how an entity therein might prove control
over an identifier or a controller document for the purposes of authentication or
authorization.
5.1.1 Proving Control of an Identifier and/or Controller Document
Proving control over an identifier and/or a controller document is useful
when accessing remote systems. Cryptographic digital signatures enable certain
security protocols related to controller documents
to be cryptographically verifiable. For these purposes, this specification
defines useful verification relationships in 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.
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 Assertionverification 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.
5.2 Key and Signature Expiration
In a decentralized architecture, there might not be centralized authorities to
enforce cryptographic material or cryptographic digital signature expiration
policies. Therefore, it is with supporting software such as verification
libraries that requesting parties validate that cryptographic 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.
5.3 Verification Method Rotation
Rotation is a management process that enables the secret cryptographic material
associated with an existing verification method to be deactivated or
destroyed once a new verification method has been added to the
controller document. Going forward, any new proofs that a
controller would have generated using the old secret cryptographic
material can now instead be generated using the new cryptographic material and
can be verified using the new verification method.
Rotation is a useful mechanism for protecting against verification method
compromise, since frequent rotation of a verification method by the controller
reduces the value of a single compromised verification method to an attacker.
Performing revocation immediately after rotation is useful for verification
methods that a controller designates for short-lived verifications, such as
those involved in encrypting messages and authentication.
The following considerations might be of use when contemplating the use of
verification method rotation:
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.
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 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.
5.4.1 Revocation Semantics
Although verifiers might choose not to accept proofs or signatures from a
revoked verification method, knowing whether a verification was made with a
revoked verification method is trickier than it might seem. Some auditing
systems provide the ability to look back at the state of an identifier at a
point in time, or at a particular version of the controller document.
When such a feature is combined with a reliable way to determine the time or
identifier version that existed when a cryptographically verifiable statement
was made, then revocation does not undo that statement. This can be the basis
for using digital signatures to make binding commitments; for example, to sign
a mortgage.
If these conditions are met, revocation is not retroactive; it only nullifies
future use of the method.
However, in order for such semantics to be safe, the second condition — an
ability to know what the state of the controller document was at the time
the assertion was made — is expected to apply. Without that guarantee,
someone could discover a revoked key and use it to make cryptographically
verifiable statements with a simulated date in the past.
Some auditing systems only allow the retrieval of the current state of a
identifier. When this is true, or when the state of an identifier at the time of
a cryptographically verifiable statement cannot be reliably determined, then the
only safe course is to disallow any consideration of state with respect to time,
except the present moment. Identifier ecosystems that take this approach
essentially provide cryptographically verifiable statements as ephemeral tokens
that can be invalidated at any time by the controller.
5.5 Encrypted Data in Controller Documents
Encryption algorithms have been known to fail due to advances in cryptography
and computing power. Implementers are advised to assume that any encrypted data
placed in a controller document might eventually be made available in clear text
to the same audience to which the encrypted data is available. This is
particularly pertinent if the controller document is public.
Encrypting all or parts of a controller document is not an appropriate
means to protect data in the long term. Similarly, placing encrypted data in
a controller document is not an appropriate means to protect personal data.
Given the caveats above, if encrypted data is included in a controller document,
implementers are advised to not associate any correlatable information
that could be used to infer a relationship between the encrypted data
and an associated party. Examples of correlatable information include
public keys of a receiving party, identifiers to digital assets known to be
under the control of a receiving party, or human readable descriptions of a
receiving party.
5.6 Content Integrity Protection
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.
5.7 Level of Assurance
Additional information about the security context of authentication events is
often required for compliance reasons, especially in regulated areas such as the
financial and public sectors. This information is often referred to as a Level
of Assurance (LOA). Examples include the protection of secret cryptographic
material, the identity proofing process, and the form-factor of the
authenticator.
Payment services (PSD 2) and
eIDAS introduce such requirements to the security context. Level of
assurance frameworks are classified and defined by regulations and
standards such as
eIDAS, NIST 800-63-3 and ISO/IEC
29115:2013, including their requirements for the security context, and
making recommendations on how to achieve them. This might include strong user
authentication where FIDO2/WebAuthn can fulfill the
requirement.
Some regulated scenarios require the implementation of a specific level of
assurance. Since verification relationships used to perform
assertion and authentication might be
used in some of these situations, information about the applied security context
might need to be expressed and provided to a verifier. Whether and how
to encode this information in the controller document data model is out
of scope for this specification. Interested readers might note that 1) the
information could be transmitted using Verifiable Credentials
[VC-DATA-MODEL-2.0], and 2) the controller document data model can be
extended to incorporate this information.
6. Privacy Considerations
This section is non-normative.
Since controller documents are designed to be administered directly by
the controller, it is critically important to apply the principles of
Privacy by Design [PRIVACY-BY-DESIGN] to all aspects of the
controller document. All seven of these principles have been applied
throughout the development of this specification. The design used in this
specification does not assume that there is a registrar, hosting company, nor
other intermediate service provider to recommend or apply additional privacy
safeguards. Privacy in this specification is preventive, not remedial, and is an
embedded default. The following sections cover privacy considerations that
implementers might find useful when building systems that utilize controller
documents.
6.1 Keep Personal Data Private
If a controller document is about a specific individual and is
public-facing, it is critical that the controller documents
contain no personal data. Personal data can instead be transmitted through other
means such as 1) verifiable credentials [VC-DATA-MODEL-2.0], or 2)
other private communication channels.
6.2 Identifier Correlation Risks
Identifiers can be used for the purpose of correlation.
Controllers can mitigate this privacy risk by using pairwise identifiers
that are unique to each relationship; in effect, each identifier acts as a
pseudonym. A pairwise identifier need only be shared with more than one party
when correlation is explicitly desired. If pairwise identifiers are the default,
then the only need to publish an identifier openly, or to share it with multiple
parties, is when the controllers and/or subjects explicitly
desire public identification and correlation.
6.3 Controller Document Correlation Risks
The anti-correlation protections of pairwise identifiers are easily defeated if
the data in the corresponding controller documents can be correlated. For
example, using identical verification methods in multiple controller
documents can provide as much correlation information as using the same
identifier. Therefore, the controller document for a pairwise identifier
also needs to use pairwise unique information, such as ensuring that
verification methods are unique to the pairwise relationship.
6.4 Subject Classification
It is dangerous to add properties to the controller document that can be
used to indicate, explicitly or through inference, what type or nature
of thing the subject is, particularly if the subject is a person.
Including type information in a controller document can result
in personal privacy harms even for subjects that are non-person entities,
such as IoT devices. The aggregation of such information around a
controller could serve as a form of digital fingerprint and this is best
avoided.
The following section describes accessibility considerations that developers
implementing this specification are urged to consider in order to ensure that
their software is usable by people with different cognitive, motor, and visual
needs. As a general rule, this specification is used by system software and does
not directly expose individuals to information subject to accessibility
considerations. However, there are instances where individuals might be
indirectly exposed to information expressed by this specification and thus the
guidance below is provided for those situations.
7.1 Presenting Time Values
This specification enables the expression of dates and times related to the
validity period of cryptographic proofs. This information might be indirectly
exposed to an individual if a proof is processed and is detected to be outside
an allowable time range. When exposing these dates and times to an individual,
implementers are urged to take into account
cultural normas and locales
when representing dates and times in display software. In addition to these
considerations, presenting time values in a way that eases the cognitive burden
on the individual receiving the information is a suggested best practice.
For example, when conveying the expiration date for a particular set of
digitally signed information, implementers are urged to present the time of
expiration using language that is easier to understand rather than language that
optimizes for accuracy. Presenting the expiration time as "This ticket expired
three days ago." is preferred over a phrase such as "This ticket expired on July
25th 2023 at 3:43 PM." The former provides a relative time that is easier to
comprehend than the latter time, which requires the individual to do the
calculation in their head and presumes that they are capable of doing such a
calculation.
A. Examples
This section is non-normative.
This section contains more detailed examples of the concepts introduced in
the specification.
A.1 Multikey Examples
This section is non-normative.
This section contains various Multikey examples that might be useful for
developers seeking test values.
Example 19: A P-256 public key encoded as a Multikey
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.