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 First Public 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.
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 5. 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 6. 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 these terms
is included whenever they appear 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 specification defining the usage of specific cryptographic primitives in
order to achieve a particular security goal. These documents are often used
to 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 usage, 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."
Add examples of common Controller documents, such as
controller documents published on a ledger-based registry, or on a mutable medium in
combination with an integrity protection mechanism such as Hashlinks.
2.1 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 usage, 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 id property for a verification
methodMUST be a string that conforms to the
conforms to the [URL] syntax.
type
The value of the type property MUST be a string that references exactly one verification
method type.
controller
The value of the controller property MUST be a string that conforms to the [URL] syntax.
revoked
The revoked property is OPTIONAL.
If present, it MUST be an [XMLSCHEMA11-2]
dateTimeStamp string specifying when the verification 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 3. Multibase.
When specifing 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 3. Multibase.
secretKeyMultibase
The secretKeyMultibase property is OPTIONAL. If present, its value MUST be a
Multibase encoded value as described in Section 3. Multibase.
An example of a Multikey is provided below:
Example 3: Multikey encoding of a Ed25519 public key
In the example above, the publicKeyMultibase value starts with the letter z,
which is the Multibase header that conveys that the
binary data is base-58-btc-encoded using the Bitcoin base-encoding alphabet. The
decoded binary data header is 0xed01, which specifies that the
remaining data is a 32-byte raw Ed25519 public key.
The Multikey data model is also capable of encoding secret keys, whose subtypes
include symmetric keys and private keys.
Example 4: Multikey encoding of a Ed25519 secret key
In the example above, the secretKeyMultibase value starts with the letter z,
which is the Multibase header that conveys that the
binary data is base-58-btc-encoded using the Bitcoin base-encoding alphabet. The
decoded binary data header is 0x8026, which specifies that the
remaining data is a 32-byte raw Ed25519 private key.
2.1.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 public key fingerprint [RFC7638]. See the first key in
Example 2 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 5: 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 "OKP", which means
"Octet string key pairs". The alg property identifies the algorithm intended
for use with the public key, which in this case is ES384. The crv property identifies
the particular curve type of the public key, P-384. The x property specifies
the point on the P-384 curve that is associated with the public key.
The publicKeyJwk property MUST NOT contain any property marked as
"Private" or "Secret" in any registry contained in the JOSE Registries [JOSE-REGISTRIES], including "d".
The JSON Web Key data model is also capable of encoding secret keys, sometimes
referred to as private keys.
Example 6: 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 property, which still specifies the point on
the Ed25519 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 7: Embedding and referencing verification methods
{
...
"authentication": [
// this key is referenced and might be used by// more than one verification relationship
"did:example:123456789abcdefghi#keys-1",
// this key is embedded and may *only* be used for authentication
{
"id": "did:example:123456789abcdefghi#keys-2",
"type": "Multikey", // external (property value)
"controller": "did: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 8: Authentication property
containing three verification methods
{
"@context": [
"https://www.w3.org/ns/did/v1",
"https://www.w3.org/ns/credentials/v2",
"https://w3id.org/security/multikey/v1"
],
"id": "did:example:123456789abcdefghi",
...
"authentication": [
// this method can be used to authenticate as did:...fghi
"did:example:123456789abcdefghi#keys-1",
// this method is *only* approved for authentication, it may not// be used for any other proof purpose, so its full description is// embedded here rather than using only a reference
{
"id": "did:example:123456789abcdefghi#keys-2",
"type": "Multikey",
"controller": "did: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 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 9: Assertion method property
containing two verification methods
{
"@context": [
"https://www.w3.org/ns/did/v1",
"https://www.w3.org/ns/credentials/v2",
"https://w3id.org/security/multikey/v1"
],
"id": "did:example:123456789abcdefghi",
...
"assertionMethod": [
// this method can be used to assert statements as did:...fghi
"did: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": "did:example:123456789abcdefghi#keys-2",
"type": "Multikey", // external (property value)
"controller": "did:example:123456789abcdefghi",
"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
}
],
...
}
2.2.3 Key Agreement
The keyAgreementverification relationship is used to
specify how an entity can generate encryption material in order to transmit
confidential information intended for the controller, such as for
the purposes of establishing a secure communication channel with the recipient.
keyAgreement
The keyAgreement property is OPTIONAL. If present, the associated
value MUST be a set of one or more
verification methods. Each verification 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 10: Key agreement property
containing two verification methods
{
"@context": "https://www.w3.org/ns/did/v1",
"id": "did:example:123456789abcdefghi",
...
"keyAgreement": [
// this method can be used to perform key agreement as did:...fghi
"did:example:123456789abcdefghi#keys-1",
// this method is *only* approved for key agreement usage, it will not// be used for any other verification relationship, so its full description is// embedded here rather than using only a reference
{
"id": "did:example:123#zC9ByQ8aJs8vrNXyDhPHHNNMSHPcaSgNpjjsBYpMMjsTdS",
"type": "X25519KeyAgreementKey2019", // external (property value)
"controller": "did:example:123",
"publicKeyMultibase": "z6LSn6p3HRxx1ZZk1dT9VwcfTBCYgtNWdzdDMKPZjShLNWG7"
}
],
...
}
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 11: Capability invocation property
containing two verification methods
{
"@context": [
"https://www.w3.org/ns/did/v1",
"https://w3id.org/security/multikey/v1"
],
"id": "did:example:123456789abcdefghi",
...
"capabilityInvocation": [
// this method can be used to invoke capabilities as did:...fghi
"did:example:123456789abcdefghi#keys-1",
// this method is *only* approved for capability invocation usage, it will not// be used for any other verification relationship, so its full description is// embedded here rather than using only a reference
{
"id": "did:example:123456789abcdefghi#keys-2",
"type": "Multikey", // external (property value)
"controller": "did:example:123456789abcdefghi",
"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
}
],
...
}
2.2.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.2.4 Capability Invocation.
Example 12: Capability Delegation property
containing two verification methods
{
"@context": [
"https://www.w3.org/ns/did/v1",
"https://w3id.org/security/multikey/v1"
],
"id": "did:example:123456789abcdefghi",
...
"capabilityDelegation": [
// this method can be used to perform capability delegation as did:...fghi
"did: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": "did:example:123456789abcdefghi#keys-2",
"type": "Multikey", // external (property value)
"controller": "did:example:123456789abcdefghi",
"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
}
],
...
}
3. Multibase
Issue 2: Multibase may be standardized at IETF
The [MULTIBASE] specification has been dispatched at IETF and may be
standardized there. There is active discussion on this initiative in
the
Multiformats mailing list at IETF. If the Multibase draft is stabilized
before this specification goes to the Proposed Recommendation phase, the table
below will be replaced with normative references to the Multibase
specification at IETF. It is the intention of the Working Group to ensure
alignment between the Multibase values used in this specification and the
Multibase values defined by the current Multibase community and any potential
future IETF Multiformats Working Group.
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 6.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 6.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.
4. Multihash
Issue 3: Multihash may be standardized at IETF
The [MULTIHASH] specification has been dispatched at IETF and may be
standardized. There is active discussion on this initiative in
the
Multiformats mailing list at IETF. If the IETF draft is stabilized
before this specification goes to the Proposed Recommendation phase, the table
below will be replaced with normative references to the Multihash
specification. It is the intention of the Working Group to ensure
alignment between the Multihash values used in this specification and the
Multihash values defined by the current Multihash community and any potential
future IETF Multiformats Working Group.
A Multihash value starts with a binary header, which identifies the specific
cryptographic hash algorithm and parameters used to generate the digest,
followed by the cryptographic digest value. 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 prepend the associated
Multihash header value to the cryptographic hash value.
To decode a Multihash value, an implementation MUST remove the prepended
Multihash header value, which identifies the type of cryptographic hashing
algorithm as well as its output length, leaving the raw cryptographic hash
value which MUST match the output length associated with the Multihash header.
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 -<DIGEST_ALGORITHM> -binary | openssl base64 -nopad -a.
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 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 value, such
as DataIntegrityProof, are used.
If an @context property is not provided in a document that is being secured or
verified, or the Data Integrity terms used in the document are not mapped by
existing values in the @context property, implementations MUST inject or add
an @context property with a value of
https://w3id.org/security/data-integrity/v2.
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.
5.2 Datatypes
This section defines datatypes that are used by this specification.
5.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.
6. 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.
6.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 13: 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;
}
6.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 14: 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;
}
6.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 proof purpose (proofPurpose), and
a set of dereferencing options (options). A
verification method is produced as output.
Let vmIdentifier be set to verificationMethod.
Let vmPurpose be set to proofPurpose.
If vmIdentifier is not a valid URL, an error MUST be raised and SHOULD
convey an error type of
INVALID_VERIFICATION_METHOD_URL.
Let controllerDocumentUrl be the result of parsing
vmIdentifier according to the rules of the URL scheme and extracting
the primary resource identifier (without the fragment identifier).
Let vmFragment be the result of parsing vmIdentifier
according to the rules of the URL scheme and extracting the secondary
resource identifier (the fragment identifier).
Let controllerDocument be the result of dereferencing
controllerDocumentUrl, according to the rules
of the URL scheme and using the supplied options.
If controllerDocument.id does not match the
controllerDocumentUrl, an error MUST be raised and SHOULD
convey an error type of
INVALID_CONTROLLER_DOCUMENT_ID.
Let verificationMethod be the result of dereferencing the
vmFragment from the controllerDocument according to the
rules of the media type of the controllerDocument.
If verificationMethod is not associated with the array of
vmPurposes in the controllerDocument, either by reference
(URL) or by value (object), an error MUST be raised and SHOULD convey an error
type of
INVALID_PROOF_PURPOSE_FOR_VERIFICATION_METHOD.
Return verificationMethod as the
verification method.
The following example provides a minimum conformant
controller document containing a minimum conformant
verification method as required by the algorithm in this section:
Example 15: 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"]
}
6.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.
The following section describes security considerations that developers
implementing this specification should be aware of in order to create secure
software.
Issue 5
Write Security Considerations section
8. Privacy Considerations
The following section describes privacy considerations that developers
implementing this specification should be aware of in order to create
privacy enhancing software.
Issue 6
Write Privacy Considerations section
9. Accessibility Considerations
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.
Issue 7
Write Accessibility Considerations section
9.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.
10. Revision History
This section is non-normative.
This section contains the substantive changes that have been made to this
specification over time.
Populated Terminology section.
Apply wording updates from VC-JOSE-COSE spec.
11. Acknowledgements
This section is non-normative.
The specification authors would like to thank the contributors to the
W3C Decentralized Identifiers (DIDs) v1.0,
W3C Verifiable Credential Data Integrity 1.0, and
W3C Securing Verifiable Credentials using JOSE and COSE specifications
upon which this work is based.