This specification defines how to secure Verifiable Credentials with JSON
Web Tokens (JWT) [RFC7519], which build on JSON Web Signatures (JWS)
[RFC7515]. This enables Verifiable Credentials to be easily integrated into ecosystems that already support JSON Web Tokens.
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.
JSON Web Token (JWT) [RFC7519] is a widely-used means of
expressing
claims to be transferred between two parties. Providing a
representation of the Verifiable Credentials Data Model for JWT allows
existing systems and libraries to participate in the ecosystem described
in Section ecosystem overview. A JWT encodes a set of
claims as a JSON object that is contained in a JSON Web Signature
(JWS) [RFC7515] and/or JSON Web Encryption (JWE) [RFC7516]. For this specification, the use
of JWE is out of scope.
1.1 Verifiable Credentials Data Model
This specification describes how to secure media types
expressing Verifiable Credentials and Verifiable Presentations
as described in the [VC-DATA-MODEL], using JWTs [RFC7519].
Note
The application/vc+jwt media type described in this specification defines
an example of a unidirectional mapping to a base media type defined in
the [VC-DATA-MODEL]; see Appendix A.4.1.
2. Securing JSON
This section
provides guidance on how to use JSON [RFC7159] claimsets with JWT registered claims to construct
a JWT that can be mapped to a verifiable credential. This section also describes
how to use content types and token types to distinguish different representations of verifiable credentials.
The vc and vp claims MUST NOT be present when the content type header parameter is set to credential-claims-set+json.
2.3 Verifiable Credential
3. Securing the Core VC Data Model
The use of Verifiable Credentials often involves the representation and exchange of structured
data in the form of JSON-LD as this is the format of the core data model. While JSON-LD provides a flexible and extensible format for
describing data, it is important to note that it also provides a linkage between the data structure
and semantic meaning of data.
This section outlines how JSON-LD encoded claimset can be secured using either JOSE or COSE.
A benefit to this approach is that payloads can be made to conform directly to the [VC-DATA-MODEL]
without any mapping or transformation.
3.1 With JOSE
3.1.1 Securing JSON-LD VCs with JOSE
This section details how to secure data payloads with the type application/vc+ld+json
with JOSE.
COSE [rfc8152] is a common approach to encoding and securing information
using CBOR [rfc8949]. Verifiable credentials MAY be secured using COSE [rfc8152]
and MUST be identified through use of content types as outlined in this section.
3.2.1 Securing JSON-LD VCs with COSE
This section details how to secure data with the type application/vc+ld+json
with COSE.
This prevents following the guidance from the JWT BCP
4. 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, and MUST NOT 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.
5. Privacy Considerations
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 the [VC-DATA-MODEL].
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], 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 VC-JWT.
6. 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 JWTs.
When implementing VC-JWTs, 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.
A. IANA Considerations
This section is non-normative.
A.1 application/vc+jwt
This specification registers the application/vc+jwt Media Type specifically for
identifying a JWT conforming to the Verifiable Credentials JWT format in the typ header.
Type name:
application
Subtype name:
application/vc+jwt
Required parameters:
None
Encoding considerations:
application/vc+jwt values are encoded
as a series of base64url encoded values (some of which may be the
empty string) each separated from the next by a single period
('.') character.
Security considerations:
As defined in this specification. See also the security considerations in [RFC7519].
This specification registers the application/vc+ld+jwt Media Type specifically for
identifying a JWT conforming to the Verifiable Credentials JWT format in the typ header.
Type name:
application
Subtype name:
vc+ld+jwt
Required parameters:
None
Encoding considerations:
application/vc+ld+jwt values are encoded
as a series of base64url encoded values (some of which may be the
empty string) each separated from the next by a single period
('.') character.
Security considerations:
As defined in this specification. See also the security considerations in [RFC7519].
This specification registers the application/credential-claims-set-1.1+json MIME Media Type specifically for
identifying a JWT Claims Set conforming to the Verifiable Credentials 1.1 JWT format in the cty header.
Type name:
application
Subtype name:
application/credential-claims-set-1.1+json
Required parameters:
None
Encoding considerations:
Resources that use the "application/credential-claims-set-1.1+json"
Media Type are required to conform to all of the requirements
for the "application/json" Media Type and are
therefore subject to the same encoding considerations specified
in Section 11 of [RFC7159].
Security considerations:
As defined in this specification. See also the security considerations in [RFC7519].
The following describes a mapping from application/vc+jwt to
application/vc+ld+json. This is one possible unidirectional mapping
between 2.0 VC-JWTs and the VC Data Model; other such mappings are possible.
Extract iss, sub, iat, nbf,
exp, jti, and aud as registered claims.
Set aside all other claims as subject claims.
To construct the VCDM-compliant JSON:
Set the value of @context to
"https://www.w3.org/ns/credentials/v2".
Set the value of type to ["VerifiableCredential"].
Set the value of the issuer property to one of the following:
If the value of iss is a URL, use the value of iss.
If the value of iss is not a URL, use the concatenation of "urn:vc:"
and the value of iss.
If jti is present, set the value of id to the
concatenation of "urn:vc:" and the value of jti.
If nbf is present, set the value of validFrom to the
dateTime obtained by converting the value of nbf from
the NumericDate described in [RFC7519] to a dateTime as
described in [XMLSCHEMA11-2].
If exp is present, set the value of validUntil to the
dateTime obtained by converting the value of exp from
the NumericDate described in [RFC7519] to a dateTime as
described in [XMLSCHEMA11-2].
Set the value of credentialSubject to an object that contains
the following properties:
If sub is present, set the value of the id property to
the concatenation of "urn:vc:" and the value of sub.
Add all of the subject claims.
B. Examples
Example 11: A revocable credential with multiple subjects