This specification defines how to secure credentials and presentations
conforming to the Verifiable Credential data model [VC-DATA-MODEL-2.0]
with JSON Object Signing and Encryption (JOSE)
and CBOR Object Signing and Encryption (COSE) [RFC9052].
This enables the Verifiable Credential data model
[VC-DATA-MODEL-2.0] to be implemented with standards
for signing and encryption that are widely adopted.
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.
This specification describes how to secure media types
expressing Verifiable Credentials and Verifiable Presentations
as described in [VC-DATA-MODEL-2.0] using approaches
defined by the OAuth, JOSE, and COSE working groups at the IETF.
This includes SD-JWT [SD-JWT] and COSE [RFC9052],
and provides an approach using well-defined content types
[RFC6838] and structured suffixes [MULTIPLE-SUFFIXES]
to distinguish the data types of unsecured documents conforming to [VC-DATA-MODEL-2.0]
from the data types of secured documents conforming to [VC-DATA-MODEL-2.0],
as defined in this specification.
Selective Disclosure for JWTs (SD-JWT) [SD-JWT] provides a standardized
mechanism for digitally signing JSON documents. It provides a means
to ensure the integrity, authenticity, selective disclosure and non-repudiation of
the information contained in a JSON document. These
properties make SD-JWT especially well suited to securing documents
conforming to the JSON-LD [VC-DATA-MODEL-2.0].
CBOR Object Signing and Encryption (COSE) [RFC9052] is a
specification that defines a framework for representing signed and
encrypted data using (Concise Binary Object Representation) [RFC8949]
data structures. COSE provides a standardized way to secure the
integrity, authenticity, and confidentiality of CBOR-encoded
information. It offers a flexible and extensible set of
cryptographic options, allowing for a wide range of algorithms
to be used for signing and encryption.
COSE supports two main operations: signing and encryption. For
signing, COSE allows the creation of digital signatures over
CBOR data using various algorithms such as HMAC, RSA, ECDSA, or
EdDSA. These signatures provide assurance of data integrity and
authenticity. COSE also supports encryption, enabling the
confidentiality of CBOR data by encrypting it with symmetric or
asymmetric encryption algorithms.
2. Terminology
This section defines the terms used in this specification. A link to these terms
is included whenever they appear in this specification.
public key
Cryptographic material that can be used to verify digital proofs created with a
corresponding private key.
private key
Cryptographic material that can be used to generate digital proofs.
authentication
A process by which an entity can prove to a verifier that it has a specific
attribute or controls a specific secret.
decentralized identifier (DID)
A globally unique persistent identifier that does not require a centralized
registration authority and is often generated and/or registered
cryptographically. The generic format of a DID is defined in [DID-CORE]. Many — but
not all — DID methods make use of distributed ledger technology (DLT) or some
other form of decentralized network.
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.
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.
distributed ledger (DLT)
A non-centralized system for recording events. These systems establish
sufficient confidence for participants to rely upon the data recorded by others
to make operational decisions. They typically use distributed databases where
different nodes use a consensus protocol to confirm the ordering of
cryptographically signed transactions. The linking of digitally signed
transactions over time often makes the history of the ledger effectively
immutable.
resource
As defined by [RFC3986]: "...the term 'resource' is used in a general sense
for whatever might be identified by a URI." Similarly, any resource might serve
as a subject identified by a DID.
verifiable credential
A standard data model and representation format for expressing
cryptographically-verifiable digital credentials, as defined by the W3C
Verifiable Credentials specification [VC-DATA-MODEL-2.0].
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."
This section outlines how to secure documents conforming
to [VC-DATA-MODEL-2.0] using JOSE and COSE.
Documents conforming to [VC-DATA-MODEL-2.0],
and their associated media types, rely on
JSON-LD, which is an extensible format for describing
linked data; see JSON-LD Relationship to RDF.
A benefit to this approach is that payloads can be made to conform
directly to [VC-DATA-MODEL-2.0] without any mappings or
transformation, while at the same time supporting registered
header parameters and claims that are understood in the context of JOSE and COSE.
The most specific media type (or subtype) available SHOULD be used, instead of
more generic media types (or supertypes). For example, rather than the general
application/sd-jwt, application/vc+ld+json+sd-jwt
ought to be used, unless there is a more specific media type that would even
better identify the secured envelope format.
If implementations do not know which media type to use, media types defined in this specification MUST be used.
3.1 With JOSE
3.1.1 Securing JSON-LD Verifiable Credentials with JOSE
This section details how to use JOSE to secure verifiable credentials conforming
to [VC-DATA-MODEL-2.0].
[RFC7515] MAY be used to secure this media type.
The typ header parameter SHOULD be vc+ld+json+sd-jwt.
When present, the cty header parameter SHOULD be vc+ld+json.
See Registered Header Parameter Names
for additional details regarding usage of typ and
cty.
Example 1: A simple example of a verifiable credential
3.1.2 Securing JSON-LD Verifiable Presentations with JOSE
This section details how to use JOSE to secure verifiable presentations conforming
to [VC-DATA-MODEL-2.0].
[RFC7515] MAY be used to secure this media type.
The typ header parameter SHOULD be vp+ld+json+sd-jwt.
When present, the cty header parameter SHOULD be vp+ld+json.
See Registered Header Parameter Names
for additional details regarding usage of typ and
cty.
To improve interoperability, implementations SHOULD support the compact serialization (application/sd-jwt),
and MAY support the JSON serialization (application/sd-jwt+json).
If the JSON serialization is used, it is RECOMMENDED that a profile be defined,
to ensure any addition JSON members are understood consistently.
3.2 With COSE
COSE [RFC9052] is a common approach to encoding and securing
information using CBOR [RFC8949]. Verifiable credentials MAY
be secured using COSE [RFC9052] and SHOULD be identified through
use of content types as outlined in this section.
3.2.1 Securing JSON-LD Verifiable Credentials with COSE
This section details how to secure data with the type
application/vc+ld+json
with COSE.
[RFC9052] MAY be used to secure this media type.
The typ header parameter SHOULD be application/vc+ld+json+cose.
See I-D.ietf-cose-typ-header-parameter
for the COSE "typ" (type) header parameter.
When present, the content type (3) header parameter
SHOULD be application/vc+ld+json.
See Common COSE Header Parameters for additional details.
3.2.2 Securing JSON-LD Verifiable Presentations with COSE
This section details how to use COSE to secure verifiable presentations conforming
to [VC-DATA-MODEL-2.0].
[RFC9052] MAY be used to secure this media type.
The typ header parameter SHOULD be application/vp+ld+json+sd-jwt.
When present, the cty header parameter SHOULD be application/vp+ld+json.
See Common COSE Header Parameters for additional details.
When the iat and/or exp JWT claims are present,
they represent the issuance and expiration time of the signature, respectively.
Note that these are different from the validFrom and validUntil properties
defined in Validity Period,
which represent the validity of the data that is being secured.
The claims and security provided by this specification are independent of the data
secured and semantics provided by the [VC-DATA-MODEL-2.0]. This means that while the security
features of this specification ensure data integrity and authenticity, they do
not dictate the interpretation of claim data.
Implementers SHOULD avoid setting JWT claims to values that conflict with
verifiable credential properties, especially with pairs such as
iss and issuer, jti and id, and sub and credentialSubject.id.
The JWT Claim Names vc and vpMUST NOT be present.
Additional members may be present as header parameters and claims.
If they are not understood, they MUST be ignored.
It is RECOMMENDED to use
the IANA CBOR Web Token Claims registry and
the IANA COSE Header Parameters registry
to identify any claims and header parameters that might be confused with
members defined by [VC-DATA-MODEL-2.0]. These include but are not
limited to: iss, kid,
alg, iat,
exp, and cnf.
When the iat and/or exp CWT claims are present,
they represent the issuance and expiration time of the signature, respectively.
Note that these are different from the validFrom and validUntil properties
defined in Validity Period,
which represent the validity of the data that is being secured.
Additional members may be present as header parameters and claims.
If they are not understood, they MUST be ignored.
When iss is absent, and the issuer is identified as a [URL],
the kidMUST be an absolute [URL] to a verification method listed in a controller document.
Example 7: An issuer identified by a controller document identifier
When the holder is identified as a [URL],
and iss is absent,
the kidMUST be an absolute [URL] to a verification method listed in a controller document.
Example 9: A holder identified by a controller document identifier
When iss is present and is a [URL],
the kidMUST match a key discovered via a JWT Issuer Metadata Request,
as described in [SD-JWT-VC].
Issue 160: (AT RISK) Feature depends on demonstration of independent implementations post-CR
This normative statement depends on the IETF OAUTH working group adopted draft [SD-JWT-VC].
This feature is at risk and will be removed from the specification if at least
two independent, interoperable implementations are not demonstrated.
There are several different ways to discover the verification keys of
the issuers
and holders.
5.1 Using Header Parameters and Claims for Key Discovery
These JOSE header parameters and JWT claims can be used by
verifiers to discover verification keys.
5.1.1 kid
If kid is present in the JOSE Header,
a verifier can use this parameter
as a hint indicating which key was used to secure the verifiable credential, when performing a
verification process as defined in RFC7515.
kidMUST be present when the key of the issuer
or subject is expressed as a DID URL.
The value of the issuer property can be either a string or an object.
When issuer value is a string, iss value, if present, MUST match issuer value.
When issuer value is an object with an id value,
iss value, if present, MUST match issuer.id value.
If kid is also present in the
JOSE Header, it is used to
distinguish the specific key used.
5.1.3 cnf
If cnf is present in the JOSE Header
or the JWT Claims ,
a verifierMAY use this parameter
to identify a proof-of-possession key in the manner described in [RFC7800] for use in the
verification process.
When the issuer value is a URL using the HTTPS scheme,
issuer metadata including the issuer's public keys can be retrieved using the mechanism
defined in [SD-JWT-VC].
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 type property MUST be a string that references exactly one verification
method type. To maximize interoperability, the
verification method type SHOULD be JsonWebKey.
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, its value MUST be an [XMLSCHEMA11-2]
combined date and time 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.
5.3.1.1 Verification Material
Verification material MUST be expressed in the publicKeyJwk property
of a JsonWebKey or as a COSE_Key. This key material is retrieved based on hints in the
JOSE or COSE message envelopes, such as kid or iss. At
the time of writing, there is no standard way to retrieve a public key in JWK or
COSE_Key from a DID URL or controller document.
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
another representtion 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 JSON Web Key (JWK) is a specific type of verification method
that uses the JWK specification [RFC7517] to encode key types into a
set of parameters.
When specifying 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 REQUIRED, and its value MUST
be a JSON Web Key that conforms to [RFC7517].
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 be set to
the public key fingerprint [RFC7638]. See the first key in the example below
for an instance of a public key with a compound key identifier.
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 13: 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. Although optional, it is RECOMMENDED that alg
be included, to avoid security issues arising from using the same key with multiple
algorithms. The crv property identifies the particular curve type of the
public key. The kid property is a hint used to help discover the key; if present,
the kid value SHOULD match, or be included in, the id property of the
encapsulating JsonWebKey object, as part of the path, query, or fragment of the
URL. Finally, the x property specifies the point on the Ed25519 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".
JSON Web Key is also capable of encoding secret keys, sometimes
referred to as private keys.
Example 14: 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 secp384r1 curve that is associated with the public key).
{
...
"authentication": [
// this key is referenced and might be used by// more than one verification relationship
"did:example:123456789abcdefghi#keys-1",
],
...
}
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 16: Authentication property
containing three verification methods
{
"@context": [
"https://www.w3.org/ns/did/v1",
"https://www.w3.org/ns/credentials/v2"
],
"id": "did:example:123456789abcdefghi",
...
"authentication": [
// this method can be used to authenticate as did:...fghi
"did:example:123456789abcdefghi#keys-1",
...
}
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 whether 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
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.
{
"@context": [
"https://www.w3.org/ns/did/v1",
"https://www.w3.org/ns/credentials/v2"
],
"id": "did:example:123456789abcdefghi",
...
"assertionMethod": [
// this method can be used to assert statements as did:...fghi
"did:example:123456789abcdefghi#keys-1",
...
}
6. 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.
The normative statements in Securing
Verifiable Credentials apply to securing
application/vc+ld+json and
application/vp+ld+json
as application/vc+ld+json+sd-jwt and
application/vp+ld+json+sd-jwt.
Accordingly, Issuers, Holders, and Verifiers MUST understand the
JSON Web Token header parameter
"alg": "none" when securing [VC-DATA-MODEL-2.0]
with JSON Web Tokens.
When content types from [VC-DATA-MODEL-2.0] are secured using
JSON Web Tokens, the header parameter "alg": "none",
MUST be used to communicate that a JWT Claims Set (a
Verifiable Credential or a Verifiable Presentation) has no
integrity protection.
When a JWT Claims Set (a Verifiable Credential or a
Verifiable Presentation) contains
proof, and the JSON Web Token header contains
"alg": "none", the JWT Claims Set MUST be considered to
have no integrity protection.
Verifiable Credentials and Verifiable Presentations are not
required to be secured or integrity protected or to contain a
proof member.
Issuers, Holders, and Verifiers MUST ignore all JWT Claims Sets that
have no integrity protection.
The JWT Claim Names vc and vpMUST NOT be present in any JWT Claims Set.
7. Wallets
This section is non-normative.
Issuers,
Holders and
Verifiers might rely on clients,
as defined in [RFC4949].
Such clients are often referred to as wallets or digital credential wallets,
when they support storing and presenting digital credentials.
To meet Verifier requirements, some
Issuers might need to assess the quality of a wallet used by a
Holder, prior to issuing and
delivering credentials to a Holder.
This specification registers the
application/vc+ld+json+sd-jwt Media Type specifically for
identifying a Selective Disclosure for JWTs (SD-JWT)
conforming to the Verifiable Credential Data Model.
Type name:
application
Subtype name:
vc+ld+json+sd-jwt
Required parameters:
None
Encoding considerations:
binary; application/sd-jwt values are a series of base64url-encoded values
(some of which may be the empty string) separated by period ('.') or tilde ('~') characters.
This specification registers the
application/vp+ld+json+sd-jwt Media Type specifically for
identifying a Selective Disclosure for JWTs (SD-JWT)
conforming to the Verifiable Presentations.
Type name:
application
Subtype name:
vp+ld+json+sd-jwt
Required parameters:
None
Encoding considerations:
binary; application/sd-jwt values are a series of base64url-encoded values
(some of which may be the empty string) separated by period ('.') or tilde ('~') characters.
Verifiable Credentials often contain sensitive information that
needs to be protected to ensure the privacy and security of
organizations and individuals. This section outlines some
privacy considerations relevant to implementers and users.
Implementers are advised to note and abide by all privacy
considerations called out in [VC-DATA-MODEL-2.0].
Implementers are additionally advised to reference the
Privacy
Consideration
section of the JWT specification for privacy guidance.
In addition to the privacy recommendations in the
[VC-DATA-MODEL-2.0], the following considerations are given:
Minimization of data: It is considered best practice for
Verifiable Credentials to only contain the minimum amount of
data necessary to achieve their intended purpose. This helps
to limit the amount of sensitive information that is shared
or stored unnecessarily.
Informed consent: It is considered best practice that
individuals be fully informed about how their data will be
used and provide the ability to consent to or decline the
use of their data. This helps to ensure that individuals
maintain control over their own personal information.
Data protection: It is considered best practice to protect
Verifiable Credentials using strong encryption and other
security measures to prevent unauthorized access,
modification, or disclosure.
These considerations are not exhaustive, and implementers and
users are advised to consult additional privacy resources and
best practices to ensure the privacy and security of Verifiable
Credentials implemented using this specification.
9.2 Security Considerations
This section outlines security considerations for implementers
and users of this specification. It is important to carefully
consider these factors to ensure the security and integrity of
Verifiable Credentials when implemented using JOSE or COSE.
When implementing this specification, it is essential to address all
security issues relevant to broad cryptographic applications.
This especially includes protecting the user's asymmetric
private and symmetric secret keys, as well as employing
countermeasures against various attacks. Failure to adequately
address these issues could compromise the security and integrity
of Verifiable Credentials, potentially leading to unauthorized
access, modification, or disclosure of sensitive information.
Implementers are advised to follow best practices and
established cryptographic standards to ensure the secure
handling of keys and other sensitive data. Additionally, conduct
regular security assessments and audits to identify and address
any vulnerabilities or threats.
Follow all security considerations outlined in [RFC7515] and
[RFC7519].
When utilizing JSON-LD, take special care around remote
retrieval of contexts and follow the additional security
considerations noted in [json-ld11].
As noted in [RFC7515] when utilizing JSON [RFC7159], strict
validation is a security requirement. If malformed JSON is
received, it may be impossible to reliably interpret the
producer's intent, potentially leading to ambiguous or
exploitable situations. To prevent these risks, it is essential
to use a JSON parser that strictly validates the syntax of all
input data. It is essential that any JSON inputs that do not
conform to the JSON-text syntax defined in [RFC7159] be
rejected in their entirety by JSON parsers. Failure to reject
invalid input could compromise the security and integrity of
Verifiable Credentials.
9.3 Accessibility
This section is non-normative.
When implementing this specification, it is crucial for
technical implementers to consider various accessibility
factors. Ignoring accessibility concerns renders the information
unusable for a significant portion of the population. To ensure
equal access for all individuals, regardless of their abilities,
it is vital to adhere to accessibility guidelines and standards,
such as the Web Content Accessibility Guidelines (WCAG 2.1)
[WCAG21]. This becomes even more critical when establishing
systems that involve cryptography, as they have historically
posed challenges for assistive technologies.
Implementers are advised to note and abide by all accessibility
considerations called out in [VC-DATA-MODEL-2.0].
This specification might be used with many different key discovery protocols.
Therefore, discovery of verification keys is described in 5. Key Discovery,
and is assumed to have succeeded prior to beginning the verification process.
As a general rule, verifiers SHOULD strive to minimize the processing of untrusted data.
This includes minimizing any processing of the protected header, unprotected header, or payload as part of the key discovery procedures.
When verifying a credential or presentation secured with SD-JWT, the algorithm defined in
[[SD-JWT] for
Verification of the SD-JWT
MUST be followed.
When verifying a credential or presentation secured with COSE_Sign1, the algorithm defined in
Signing and Verification Process
MUST be followed.
After verification has succeeded, additional validation checks SHOULD be performed.
12. Validation Algorithm
All claims expected for the typMUST be present.
All claims that are understood MUST be evaluated according the verifier's validation policies.
All claims that are not understood MUST be ignored.
Schema extension mechanisms such as credentialSchemaSHOULD be checked.
If the extension mechanism type is not understood,
this property MUST be ignored.
Status extension mechanisms such as credentialStatusSHOULD be checked.
If the extension mechanism type is not understood,
this property MUST be ignored.
Based on the validation policy of the verifier and the type of credentials and type of securing mechanism,
additional validation checks might be applied. For example, dependencies between multiple credentials,
ordering or timing information associated with multiple credentials, and/or multiple presentations
could cause an otherwise valid credential or presentation to be considered invalid.