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),
Selective Disclosure for JWTs [SD-JWT],
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/.
The Working Group is actively seeking implementation feedback for this
specification. In order to exit the Candidate Recommendation phase, the
Working Group has set the requirement of at least two independent
implementations for each mandatory feature in the specification. For details
on the conformance testing process, see the test suite listed in the
implementation report.
Publication as a Candidate Recommendation does not
imply endorsement by W3C and its Members. A Candidate Recommendation Draft integrates
changes from the previous Candidate Recommendation that the Working Group
intends to include in a subsequent Candidate Recommendation Snapshot.
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 defines how to secure media types
expressing Verifiable Credentials and Verifiable Presentations
as described in [VC-DATA-MODEL-2.0] using approaches
defined by the JOSE, OAuth, and COSE working groups at the IETF.
This includes JSON Web Signature (JWS) [RFC7515],
Selective Disclosure for JWTs [SD-JWT],
and CBOR Object Signing and Encryption (COSE) [RFC9052].
It uses content types [RFC6838]
to distinguish between the data types of unsecured documents
conforming to [VC-DATA-MODEL-2.0]
and the data types of secured documents conforming to [VC-DATA-MODEL-2.0].
JSON Web Signature (JWS) [RFC7515] defines a standard means of
digitally signing documents, including JSON documents,
using JSON-based data structures.
It provides a means to ensure the integrity, authenticity,
and non-repudiation of the information contained in the document.
Selective Disclosure for JWTs (SD-JWT) [SD-JWT] builds on JWS by also
providing a mechanism enabling selective disclosure of document elements.
These properties make JWS and SD-JWT especially well suited to
securing documents conforming to [VC-DATA-MODEL-2.0].
CBOR Object Signing and Encryption (COSE) [RFC9052] defines
a standard means of representing digitally signed data structures
using Concise Binary Object Representation (CBOR) [RFC8949].
Like JWS, COSE provides a standardized way to secure the
integrity, authenticity, and confidentiality of 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 RSA, ECDSA, and
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.
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, NOT RECOMMENDED, RECOMMENDED, 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.
1.1.1 Conformance Classes
A conforming JWS document is one that conforms to all of the
"MUST" statements in Section 3.1 With JOSE.
The normative statements in Securing
Mechanisms apply to securing
application/vc-ld+jwt and
application/vp-ld+jwt,
application/vc-ld+sd-jwt and
application/vp-ld+sd-jwt,
as well as
application/vc-ld+cose and
application/vp-ld+cose.
Issuers, Holders, and Verifiers MUST understand the
JSON Web Token header parameter setting
"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 setting "alg": "none",
MUST be used to communicate that a JWT Claims Set that comprises a
Verifiable Credential or a Verifiable Presentation has no
integrity protection.
When a JWT Claims Set that comprises 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 nor integrity protected, nor to contain a
proof member.
Issuers, Holders, and Verifiers of Verifiable Credentials and/or
Verifiable Presentations MUST ignore all, and MUST NOT produce any,
JWT Claims Sets that have no integrity protection.
The JWT Claim Names vc and vpMUST NOT be present in any JWT Claims Set that comprises a
Verifiable Credential or a Verifiable Presentation.
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.
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].
controller document
A document that contains public cryptographic material as defined in the
Controller Documents 1.0 specification.
3. Securing the VC Data Model
This section outlines how to secure documents conforming
to [VC-DATA-MODEL-2.0] using JOSE, SD-JWT, 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, SD-JWT, 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+sd-jwtSHOULD 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].
The typ header parameter SHOULD be vc-ld+jwt.
When present, the cty header parameter SHOULD be vc.
See Registered Header Parameter Names
for additional details regarding usage of typ and
cty.
To encrypt a secured verifiable credential
when transmitting over an insecure channel,
implementers MAY use JSON Web Encryption (JWE) [RFC7516]
by nesting the secured verifiable credential
as the plaintext payload of a JWE,
per the description of Nested JWTs in [RFC7519].
Example 1: A simple example of a verifiable credential secured with JOSE
The typ header parameter SHOULD be vp-ld+jwt.
When present, the cty header parameter SHOULD be vp.
See Registered Header Parameter Names
for additional details regarding usage of typ and
cty.
Credentials in verifiable presentations MUST be secured.
These credentials are secured using JWS in this case.
To encrypt a secured verifiable presentation
when transmitting over an insecure channel,
implementers MAY use JSON Web Encryption (JWE) [RFC7516]
by nesting the secured verifiable presentation
as the plaintext payload of a JWE,
per the description of Nested JWTs in [RFC7519].
Example 2: A simple example of a verifiable presentation secured with JOSE with the EnvelopedVerifiableCredential type
When the iat (Issued At) and/or
exp (Expiration Time) 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.
Use of the nbf (Not Before) claim is NOT RECOMMENDED,
as it makes little sense to attempt to assign a future date to
a signature.
The claims and security provided by this specification are independent of the
data secured and semantics provided by the Verifiable Credentials Data Model v2.0 [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 the
values of verifiable credential properties when a claim and property pair refer
to the same conceptual entity, especially with pairs such as iss and issuer,
jti and id, and sub and credentialSubject.id. For example, JWK claim
iss should not be set to a value which conflicts with the value of verifiable
credential property issuer.
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.
3.2 With SD-JWT
3.2.1 Securing JSON-LD Verifiable Credentials with SD-JWT
This section details how to use JOSE to secure verifiable credentials conforming
to [VC-DATA-MODEL-2.0].
The typ header parameter SHOULD be vc-ld+sd-jwt.
When present, the cty header parameter SHOULD be vc.
See Registered Header Parameter Names
for additional details regarding usage of typ and
cty.
When securing verifiable credentials with [SD-JWT] implementers MUST ensure that
properties necessary for the validation and verification of a credential are NOT selectively
disclosable (i.e., such properties MUST be disclosed). These properties include but are not
limited to credentialStatus
and credentialSchema.
To encrypt a secured verifiable credential
when transmitting over an insecure channel,
implementers MAY use JSON Web Encryption (JWE) [RFC7516]
by nesting the secured verifiable credential
as the plaintext payload of a JWE,
per the instructions in Section 11.2 of [SD-JWT].
Example 4: A simple example of a verifiable credential secured with SD-JWT
The typ header parameter SHOULD be vp-ld+sd-jwt.
When present, the cty header parameter SHOULD be vp.
See Registered Header Parameter Names
for additional details regarding usage of typ and
cty.
Credentials in verifiable presentations MUST be secured.
These credentials are secured using SD-JWT in this case.
When securing verifiable presentations with [SD-JWT] implementers MUST ensure that
properties necessary for the validation and verification of a credential are NOT selectively
disclosable (i.e., such properties MUST be disclosed). These properties include but are not
limited to credentialStatus
and credentialSchema.
To encrypt a secured verifiable presentation
when transmitting over an insecure channel,
implementers MAY use JSON Web Encryption (JWE) [RFC7516]
by nesting the secured verifiable presentation
as the plaintext payload of a JWE,
per the instructions in Section 11.2 of [SD-JWT].
Example 5: A simple example of a verifiable presentation secured with SD-JWT using the EnvelopedVerifiableCredential type
Implementations MUST 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 additional JSON members are understood consistently.
3.3 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.3.1 Securing JSON-LD Verifiable Credentials with COSE
This section details how to use COSE to secure verifiable credentials conforming
to [VC-DATA-MODEL-2.0].
A conforming COSE issuer implementationMUST use COSE_Sign1 as specified in [RFC9052] to secure
this media type.
The unsecured verifiable credential is the unencoded COSE_Sign1 payload.
To encrypt a secured verifiable credential
when transmitting over an insecure channel,
implementers MAY use COSE encryption,
as defined in Section 5 of [RFC9052],
by nesting the secured verifiable credential
as the plaintext payload of an encrypted COSE object.
Example 7: A simple example of a verifiable credential secured with COSE
3.3.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].
A conforming COSE issuer implementationMUST use COSE_Sign1 as specified in [RFC9052] to secure
this media type.
The unsecured verifiable presentation is the unencoded COSE_Sign1 payload.
The typ header parameter SHOULD be application/vp-ld+cose.
When present, the cty header parameter SHOULD be application/vp.
See Common COSE Header Parameters for additional details.
Credentials in verifiable presentations MUST be secured.
These credentials are secured using COSE in this case.
To encrypt a secured verifiable presentation
when transmitting over an insecure channel,
implementers MAY use COSE encryption,
as defined in Section 5 of [RFC9052],
by nesting the secured verifiable presentation
as the plaintext payload of an encrypted COSE object.
Example 8: A simple example of a verifiable presentation secured with COSE using the EnvelopedVerifiableCredential type
When the iat (Issued At) and/or
exp (Expiration Time) 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.
Use of the nbf (Not Before) claim is NOT RECOMMENDED,
as it makes little sense to attempt to assign a future date to
a signature.
Additional members may be present as header parameters and claims. If they are
not understood, they MUST be ignored.
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.
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].
Issue 1: (AT RISK) Feature depends on demonstration of independent implementations
This normative statement depends on the IETF OAuth working group 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.
Example 10: A kid as a URL with a JWK Thumbprint URI
When using controller documents with this specification,
the following requirements apply.
The value of the type property of the verification method MUST be JsonWebKey.
Verification material MUST be expressed in the publicKeyJwk property
of a JsonWebKey. 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 format
from a DID URL or controller document.
When using [URL] identifiers, the kid is RECOMMENDED to be
an absolute [URL] that includes a JWK Thumbprint URI
as defined in [RFC7638]. For example:
https://vendor.example/issuers/42/keys/urn:ietf:params:oauth:jwk-thumbprint:sha-256:NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs
Example 11: 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 13: A holder identified by a controller document identifier
This specification might be used with many different key discovery protocols.
Therefore, discovery of verification keys is described in 4. 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.
After verification has succeeded, additional validation checks SHOULD be
performed as described in Section 5.4 Validation
The outputs for the following algorithms are:
status: a boolean indicating the result of verification,
true for success and false for failure.
If processing aborts for any reason or the JWT is rejected:
Set status to false
Set document to null
Set mediaType to null
Return
5.2 Verifying a Credential or Presentation Secured with SD-JWT
The inputs for this algorithm are:
inputMediaType: vc-ld+sd-jwt
inputDocument: the verifiable credential secured with [SD-JWT]
Upon receipt of the verifiable credential or presentation secured with
[SD-JWT], the holder or verifier follows this algorithm:
Follow the algorithms defined in SD-JWT for
verification of the SD-JWT.
If processing completes successfully:
Set status to true
Set mediaType to vc
Convert the SD-JWT payload back into the JSON claim set by reversing the process
in Selective Disclosure for JWTs (SD-JWT) [SD-JWT]. Set document to the JSON claim set.
(For examples of the transition from JSON claim set to SD-JWT payload, please
see SD-JWT examples).
Return
If processing aborts for any reason or the SD-JWT is rejected:
Set status to false
Set document to null
Set mediaType to null
Return
5.3 Verifying a Credential or Presentation Secured with COSE
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.
The verified document returned from verification MUST be a
well-formed compact JSON-LD document, as described in
Verifiable Credentials Data Model v2.0.
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, the type of credentials, and
the type of securing mechanism, additional validation checks MAY 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.
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.
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/vc-ld+cose Media Type specifically for
identifying a COSE object [RFC9052]
with a payload
conforming to the
Verifiable Credential Data Model.
Type name:
application
Subtype name:
vc-ld+cose
Required parameters:
None
Encoding considerations:
binary (CBOR)
Security considerations:
As defined in this specification. See also the security
considerations in [RFC9052].
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
and NIST Special Publication 800-122 [[SP-800-122]
"Guide to Protecting the Confidentiality of Personally Identifiable Information (PII)"
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.
7.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.
7.3 Accessibility
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].
The payload can be either a credential or presentation as described in
Securing Mechanisms.
A. Acknowledgements
This section is non-normative.
The Working Group thanks Orie Steele for his substantive intellectual and content
contributions to this specification. It wouldn't be the same without them.