Securing Verifiable Credentials using JSON Web Tokens

W3C Working Draft

More details about this document
This version:
https://www.w3.org/TR/2023/WD-vc-jwt-20230515/
Latest published version:
https://www.w3.org/TR/vc-jwt/
Latest editor's draft:
https://w3c.github.io/vc-jwt/
History:
https://www.w3.org/standards/history/vc-jwt
Commit history
Editors:
Orie Steele (Transmute)
Michael Jones (independent)
Michael Prorock (Mesur.io)
Feedback:
GitHub w3c/vc-jwt (pull requests, new issue, open issues)

Copyright © 2023 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.

Abstract

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/.

This document was published by the Verifiable Credentials Working Group as a Working Draft using the Recommendation track.

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 document is governed by the 2 November 2021 W3C Process Document.

1. Introduction

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.

Note

This representation relies on claims registered in the IANA JSON Web Token Claims Registry whenever possible.

Note

Production of this representation does not use vc+ld+json as an input.

2.1 Credential Header

typ MUST use the media type vc+jwt.

2.2 Credential

Note

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 JSON-LD

The use of Verifiable Credentials often involves the representation and exchange of structured data in the form of JSON-LD. 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.

[rfc7515] MAY be used to secure this media type.

When using this approach, the typ MUST be vc+ld+jwt

When using this approach, the cty MUST be vc+ld+json

See Common JOSE Header Parameters for additional details regarding usage of typ and cty.

Examples
Credential Header
Credential
Verifiable Credential

3.1.2 Securing JSON-LD VPs with JOSE

This section details how to secure verifiable presentations with the type application/vp+ld+json with JOSE.

[rfc7515] MAY be used to secure this media type.

When using this approach, the typ MUST be vp+ld+jwt

When using this approach, the cty MUST be vp+ld+json

See Common JOSE Header Parameters for additional details regarding usage of typ and cty.

Examples
Presentation Header
Presentation
Verifiable Presentation

3.2 With COSE

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.

[rfc8152] MAY be used to secure this media type.

When using this approach, the type (TBD) MUST be vc+ld+cwt

When using this approach, the content type (3) MUST be application/vc+ld+json

See Common COSE Header Parameters for additional details.

See Concise Binary Object Representation (CBOR) Tags for additional details.

Issue 67: typ for COSE

There is no registered tag for typ in COSE.

This prevents following the guidance from the JWT BCP

4. Securing Version 1.1

4.1 JSON Web Token Extensions

The [VC-DATA-MODEL] version 1.1 introduced two new registered claim names, which contain those parts of the standard verifiable credentials and verifiable presentations where no explicit encoding rules for JWT exist. These objects are enclosed in the JWT Claims Set as follows:

4.2 JWT and JWS Considerations

4.2.1 JWT Encoding

To encode a verifiable credential as a JWT, specific properties MUST be either:

  • Encoded as standard JOSE header parameters, or
  • Encoded as registered JWT claim names, or
  • Contained in the JWS signature part.

If no explicit rule is specified, properties are encoded in the same way as with a standard credential, and the encoded properties are then added to the vc claim of the JWT. As with all JWTs, the JWS-based signature of a verifiable credential represented in the JWT syntax is calculated against the literal JWT string value as presented across the wire, before any decoding or transformation rules are applied. The following paragraphs describe these encoding rules.

If a JWS is present, the digital signature refers either to the issuer of the verifiable credential, or in the case of a verifiable presentation, to the holder of the verifiable credential. The JWS proves that the iss of the JWT signed the contained JWT Claims Set and therefore, the proof property can be omitted.

If no JWS is present, a proof property MUST be provided. The proof property can be used to represent a more complex proof, as may be necessary if the creator is different from the issuer, or a proof not based on digital signatures, such as Proof of Work. The issuer MAY include both a JWS and a proof property. For backward compatibility reasons, the issuer MUST use JWS to represent proofs based on a digital signature.

The following rules apply to JOSE headers in the context of this specification:

  • alg MUST be set for digital signatures. If only the proof property is needed for the chosen signature method (that is, if there is no choice of algorithm within that method), the alg header MUST be set to none.
  • kid MAY be used if there are multiple keys associated with the issuer of the JWT. The key discovery is out of the scope of this specification. For example, the kid can refer to a key in a DID document, or can be the identifier of a key inside a JWKS.

For backward compatibility with JWT processors, the following registered JWT claim names MUST be used, instead of or in addition to, their respective standard verifiable credential counterparts:

Other JOSE header parameters and JWT claim names not specified herein can be used if their use is not explicitly discouraged. Additional verifiable credential claims MUST be added to the credentialSubject property of the JWT.

Note

For more information about using JOSE header parameters and/or JWT claim names not specified herein, see the Verifiable Credentials Implementation Guidelines [VC-IMP-GUIDE] document.

This version of the specification defines no JWT-specific encoding rules for the concepts outlined in Section Advanced Concepts (for example, refreshService, termsOfUse, and evidence). These concepts can be encoded as they are without any transformation, and can be added to the vc JWT claim.

Note

At the time of this writing, JWTs do not have a representation for multiple subjects and are thus not capable of encoding a verifiable credential with more than one subjects. The Working Group may decide to create a new JWT claim for this purpose, and, if so, may register it in the JSON Web Token Claims Registry.

4.2.2 JWT Decoding

To decode a JWT to a standard credential or presentation, the following transformation MUST be performed:

  1. Create a JSON object.
  2. Add the content from the vc or vp claim to the new JSON object.
  3. Transform the remaining JWT specific headers and claims and add the results to the new credential or presentation JSON object.

To transform the JWT specific headers and claims, the following MUST be done:

  • If exp is present, the UNIX timestamp MUST be converted to an [XMLSCHEMA11-2] date-time, and MUST be used to set the value of the expirationDate property of credentialSubject of the new JSON object.
  • If iss is present, the value MUST be used to set the issuer property of the new credential JSON object or the holder property of the new presentation JSON object.
  • If nbf is present, the UNIX timestamp MUST be converted to an [XMLSCHEMA11-2] date-time, and MUST be used to set the value of the issuanceDate property of the new JSON object.
  • If sub is present, the value MUST be used to set the value of the id property of credentialSubject of the new credential JSON object.
  • If jti is present, the value MUST be used to set the value of the id property of the new JSON object.
Example 10: JWT header of a JWT-based verifiable credential using JWS as a proof (non-normative) 
{
  "alg": "RS256",
  "kid": "did:example:abfe13f712120431c276e12ecab#keys-1"
}

In the example above, the verifiable credential uses a proof based on JWS digital signatures, and the corresponding verificatio key can be obtained using the kid header parameter.

Example 11: JWT Claims Set of a JWT-based verifiable credential using JWS as a proof (non-normative) 
{
  "sub": "did:example:ebfeb1f712ebc6f1c276e12ec21",
  "jti": "http://example.edu/credentials/3732",
  "iss": "https://example.com/keys/foo.jwk",
  "nbf": 1541493724,
  "iat": 1541493724,
  "exp": 1573029723,
  "nonce": "660!6345FSer",
  "vc": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://www.w3.org/2018/credentials/examples/v1"
    ],
    "type": ["VerifiableCredential", "UniversityDegreeCredential"],
    "credentialSubject": {
      "degree": {
        "type": "BachelorDegree",
        "name": "Bachelor of Science and Arts"
      }
    }
  }
}

In the example above, vc does not contain the id property because the JWT encoding uses the jti attribute to represent a unique identifier. The sub attribute encodes the information represented by the id property of credentialSubject. The nonce has been added to stop a replay attack.

Example 12: Verifiable credential using JWT compact serialization (non-normative) 
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImRpZDpleGFtcGxlOmFiZmUxM2Y3MTIxMjA0
MzFjMjc2ZTEyZWNhYiNrZXlzLTEifQ.eyJzdWIiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxY
zI3NmUxMmVjMjEiLCJqdGkiOiJodHRwOi8vZXhhbXBsZS5lZHUvY3JlZGVudGlhbHMvMzczMiIsImlzc
yI6Imh0dHBzOi8vZXhhbXBsZS5jb20va2V5cy9mb28uandrIiwibmJmIjoxNTQxNDkzNzI0LCJpYXQiO
jE1NDE0OTM3MjQsImV4cCI6MTU3MzAyOTcyMywibm9uY2UiOiI2NjAhNjM0NUZTZXIiLCJ2YyI6eyJAY
29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSIsImh0dHBzOi8vd
3d3LnczLm9yZy8yMDE4L2NyZWRlbnRpYWxzL2V4YW1wbGVzL3YxIl0sInR5cGUiOlsiVmVyaWZpYWJsZ
UNyZWRlbnRpYWwiLCJVbml2ZXJzaXR5RGVncmVlQ3JlZGVudGlhbCJdLCJjcmVkZW50aWFsU3ViamVjd
CI6eyJkZWdyZWUiOnsidHlwZSI6IkJhY2hlbG9yRGVncmVlIiwibmFtZSI6IjxzcGFuIGxhbmc9J2ZyL
UNBJz5CYWNjYWxhdXLDqWF0IGVuIG11c2lxdWVzIG51bcOpcmlxdWVzPC9zcGFuPiJ9fX19.KLJo5GAy
BND3LDTn9H7FQokEsUEi8jKwXhGvoN3JtRa51xrNDgXDb0cq1UTYB-rK4Ft9YVmR1NI_ZOF8oGc_7wAp
8PHbF2HaWodQIoOBxxT-4WNqAxft7ET6lkH-4S6Ux3rSGAmczMohEEf8eCeN-jC8WekdPl6zKZQj0YPB
1rx6X0-xlFBs7cl6Wt8rfBP_tZ9YgVWrQmUWypSioc0MUyiphmyEbLZagTyPlUyflGlEdqrZAv6eSe6R
txJy6M1-lD7a5HTzanYTWBPAUHDZGyGKXdJw-W_x0IWChBzI8t3kpG253fg6V3tPgHeKXE94fz_QpYfg
--7kLsyBAfQGbg
Example 13: JWT header of a JWT based verifiable presentation (non-normative) 
{
  "alg": "RS256",
  "kid": "did:example:ebfeb1f712ebc6f1c276e12ec21#keys-1"
}

In the example above, the verifiable presentation uses a proof based on JWS digital signatures, and the corresponding verification key can be obtained using the kid header parameter.

Example 14: JWT Claims Set of a JWT based verifiable presentation (non-normative) 
{
  "iss": "did:example:ebfeb1f712ebc6f1c276e12ec21",
  "jti": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
  "aud": "did:example:4a57546973436f6f6c4a4a57573",
  "nbf": 1541493724,
  "iat": 1541493724,
  "exp": 1573029723,
  "nonce": "343s$FSFDa-",
  "vp": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://www.w3.org/2018/credentials/examples/v1"
    ],
    "type": ["VerifiablePresentation"],
    // base64url-encoded JWT as string
    "verifiableCredential": ["..."]
  }
}

In the example above, vp does not contain the id property because the JWT encoding uses the jti attribute to represent a unique identifier. verifiableCredential contains a string array of verifiable credentials using JWT compact serialization. The nonce has been added to stop a replay attack.

Example 15: Verifiable presentation using JWT compact serialization (non-normative) 
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImRpZDpleGFtcGxlOjB4YWJjI2tleTEifQ.e
yJpc3MiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUxMmVjMjEiLCJqdGkiOiJ1cm46d
XVpZDozOTc4MzQ0Zi04NTk2LTRjM2EtYTk3OC04ZmNhYmEzOTAzYzUiLCJhdWQiOiJkaWQ6ZXhhbXBsZ
To0YTU3NTQ2OTczNDM2ZjZmNmM0YTRhNTc1NzMiLCJuYmYiOjE1NDE0OTM3MjQsImlhdCI6MTU0MTQ5M
zcyNCwiZXhwIjoxNTczMDI5NzIzLCJub25jZSI6IjM0M3MkRlNGRGEtIiwidnAiOnsiQGNvbnRleHQiO
lsiaHR0cHM6Ly93d3cudzMub3JnLzIwMTgvY3JlZGVudGlhbHMvdjEiLCJodHRwczovL3d3dy53My5vc
mcvMjAxOC9jcmVkZW50aWFscy9leGFtcGxlcy92MSJdLCJ0eXBlIjpbIlZlcmlmaWFibGVQcmVzZW50Y
XRpb24iLCJDcmVkZW50aWFsTWFuYWdlclByZXNlbnRhdGlvbiJdLCJ2ZXJpZmlhYmxlQ3JlZGVudGlhb
CI6WyJleUpoYkdjaU9pSlNVekkxTmlJc0luUjVjQ0k2SWtwWFZDSXNJbXRwWkNJNkltUnBaRHBsZUdGd
GNHeGxPbUZpWm1VeE0yWTNNVEl4TWpBME16RmpNamMyWlRFeVpXTmhZaU5yWlhsekxURWlmUS5leUp6Z
FdJaU9pSmthV1E2WlhoaGJYQnNaVHBsWW1abFlqRm1OekV5WldKak5tWXhZekkzTm1VeE1tVmpNakVpT
ENKcWRHa2lPaUpvZEhSd09pOHZaWGhoYlhCc1pTNWxaSFV2WTNKbFpHVnVkR2xoYkhNdk16Y3pNaUlzS
W1semN5STZJbWgwZEhCek9pOHZaWGhoYlhCc1pTNWpiMjB2YTJWNWN5OW1iMjh1YW5kcklpd2libUptS
WpveE5UUXhORGt6TnpJMExDSnBZWFFpT2pFMU5ERTBPVE0zTWpRc0ltVjRjQ0k2TVRVM016QXlPVGN5T
Xl3aWJtOXVZMlVpT2lJMk5qQWhOak0wTlVaVFpYSWlMQ0oyWXlJNmV5SkFZMjl1ZEdWNGRDSTZXeUpvZ
EhSd2N6b3ZMM2QzZHk1M015NXZjbWN2TWpBeE9DOWpjbVZrWlc1MGFXRnNjeTkyTVNJc0ltaDBkSEJ6T
2k4dmQzZDNMbmN6TG05eVp5OHlNREU0TDJOeVpXUmxiblJwWVd4ekwyVjRZVzF3YkdWekwzWXhJbDBzS
W5SNWNHVWlPbHNpVm1WeWFXWnBZV0pzWlVOeVpXUmxiblJwWVd3aUxDSlZibWwyWlhKemFYUjVSR1ZuY
21WbFEzSmxaR1Z1ZEdsaGJDSmRMQ0pqY21Wa1pXNTBhV0ZzVTNWaWFtVmpkQ0k2ZXlKa1pXZHlaV1VpT
25zaWRIbHdaU0k2SWtKaFkyaGxiRzl5UkdWbmNtVmxJaXdpYm1GdFpTSTZJanh6Y0dGdUlHeGhibWM5S
jJaeUxVTkJKejVDWVdOallXeGhkWExEcVdGMElHVnVJRzExYzJseGRXVnpJRzUxYmNPcGNtbHhkV1Z6U
EM5emNHRnVQaUo5ZlgxOS5LTEpvNUdBeUJORDNMRFRuOUg3RlFva0VzVUVpOGpLd1hoR3ZvTjNKdFJhN
TF4ck5EZ1hEYjBjcTFVVFlCLXJLNEZ0OVlWbVIxTklfWk9GOG9HY183d0FwOFBIYkYySGFXb2RRSW9PQ
nh4VC00V05xQXhmdDdFVDZsa0gtNFM2VXgzclNHQW1jek1vaEVFZjhlQ2VOLWpDOFdla2RQbDZ6S1pRa
jBZUEIxcng2WDAteGxGQnM3Y2w2V3Q4cmZCUF90WjlZZ1ZXclFtVVd5cFNpb2MwTVV5aXBobXlFYkxaY
WdUeVBsVXlmbEdsRWRxclpBdjZlU2U2UnR4Snk2TTEtbEQ3YTVIVHphbllUV0JQQVVIRFpHeUdLWGRKd
y1XX3gwSVdDaEJ6STh0M2twRzI1M2ZnNlYzdFBnSGVLWEU5NGZ6X1FwWWZnLS03a0xzeUJBZlFHYmciX
X19.ft_Eq4IniBrr7gtzRfrYj8Vy1aPXuFZU-6_ai0wvaKcsrzI4JkQEKTvbJwdvIeuGuTqy7ipO-EYi
7V4TvonPuTRdpB7ZHOlYlbZ4wA9WJ6mSVSqDACvYRiFvrOFmie8rgm6GacWatgO4m4NqiFKFko3r58Lu
eFfGw47NK9RcfOkVQeHCq4btaDqksDKeoTrNysF4YS89INa-prWomrLRAhnwLOo1Etp3E4ESAxg73CR2
kA5AoMbf5KtFueWnMcSbQkMRdWcGC1VssC0tB0JffVjq7ZV6OTyV4kl1-UVgiPLXUTpupFfLRhf9QpqM
BjYgP62KvhIvW8BbkGUelYMetA

4.3 Verifiable Credential as a Registered Claim

This section describes how to produce a VC-JWT encoded VerifiableCredential from an object of media type application/vc+ld+json.

There are currently 2 competing solutions to this problem described below. It is a goal of the v2 work to resolve them and reduce production rules to a single, simple, set of instructions that any implementer can easily meet if they possess a software library supporting [RFC7515] or [RFC7519].

4.3.1 In addition to...

There are several members (claims) of the application/vc+ld+json which will need to be translated to their JOSE form, and included next to the vc or vp member in the JWT Claims Set. We refer to the JWT Claims Set as payload in this section.

If a member is not present in the application/vc+ld+json, it MUST NOT be present in the VerifiableCredential as either a claim in the payload or a claim in the vc attribute of the payload.

We start with payload objects and an empty header, and we add members to the header and the payload based on the content in the application/vc+ld+json.

issuer -> iss

This member MUST be present in the payload.vc.issuer attribute as either a string or an object with and id.

This member MUST be present payload.iss.

In the case that payload.vc.issuer is an object, payload.iss MUST be payload.vc.issuer.id.

In the case that payload.vc.issuer is a string, payload.iss must be payload.vc.issuer

issuanceDate -> nbf

This member MUST be present in the payload.vc.issuanceDate attribute as an XMLDateTime String.

This member MUST be present payload.nbf as a unix timestamp.

In the case that the issuanceDate includes leap seconds, it is not possible to detect them when the date time is represented in nbf

Issue

This section needs to be defined.

issuance

The header and payload converted into a JWT, in accorance with the RFC: RFC7519 Section 7.1

4.3.2 Instead of...

The following steps are one way to obtain this representation:

  1. Complete the mapping for In Addition To....
  2. Remove any properties from the application/vc+ld+json that were mapped in the previous steps.
  3. Set the resulting object to be the vc member of the claim set.
Note

The object value for the vc property, when Instead of... production rules have been applied, is not of media type application/vc+ld+json.

4.4 Verifiable Presentation as Registered Claim

This section describes how to produce a VP-JWT encoded VerifiablePresentation from an object of media type application/presentation+ld+json.

There are several members (claims) of the application/presentation+ld+json which will need to be translated to their JOSE form, and included next to the vp member in the JWT Claims Set. We refer to the JWT Claims Set as payload in this section.

If a member is not present in the application/presentation+ld+json it MUST NOT be present in the VerifiablePresentation as either a claim in the payload or a claim in the vp attribute of the payload.

We start with an empty header, and payload objects, and we add members to the header and the payload based on the content in the application/presentation+ld+json.

4.4.1 holder -> iss

This member MAY be present in the payload.vp.holder attribute as either a string or an object with an id.

This member MAY be present payload.iss.

If payload.vp.holder is an object, payload.iss MUST be payload.vp.holder.id.

If payload.vp.holder is a string, payload.iss must be payload.vp.holder

4.4.2 id -> jti

If payload.vp.id is a string, payload.jti must be payload.vp.id

4.4.3 nonce

payload.nonce MUST be present.

4.4.4 verifiableCredential

payload.vp.verifiableCredential contains a string array of verifiable credentials using JWT compact serialization.

4.4.5 issuance

The header and payload converted into a JWT, in accorance with the RFC: RFC7519 Section 7.1

5. 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.

6. 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:

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.

7. 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].
Contact: W3C Verifiable Credentials Working Group public-vc-wg@w3.org

A.2 application/vc+ld+jwt

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].
Contact: W3C Verifiable Credentials Working Group public-vc-wg@w3.org

A.3 application/credential-claims-set-1.1+json

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].
Contact: W3C Verifiable Credentials Working Group public-vc-wg@w3.org
Issue 42: Bikeshedding the name for the `vc-jwt` 1.1 `cty` value.

See the original PR here: #40

The original proposal was :

application/credential-1.1+json

The name was modified to:

application/credential-claims-set-1.1+json

The editors noted that "claim-set" is redundant.

A.4 Appendix

A.4.1 Example Mapping

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. References

B.1 Normative references

[DID-CORE]
Decentralized Identifiers (DIDs) v1.0. Manu Sporny; Amy Guy; Markus Sabadello; Drummond Reed. W3C. 19 July 2022. W3C Recommendation. URL: https://www.w3.org/TR/did-core/
[json-ld11]
JSON-LD 1.1. Gregg Kellogg; Pierre-Antoine Champin; Dave Longley. W3C. 16 July 2020. W3C Recommendation. URL: https://www.w3.org/TR/json-ld11/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC7159]
The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. March 2014. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7159
[RFC7515]
JSON Web Signature (JWS). M. Jones; J. Bradley; N. Sakimura. IETF. May 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7515
[RFC7519]
JSON Web Token (JWT). M. Jones; J. Bradley; N. Sakimura. IETF. May 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7519
[rfc8152]
CBOR Object Signing and Encryption (COSE). J. Schaad. IETF. July 2017. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc8152
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[rfc8949]
Concise Binary Object Representation (CBOR). C. Bormann; P. Hoffman. IETF. December 2020. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc8949
[rfc9052]
CBOR Object Signing and Encryption (COSE): Structures and Process. J. Schaad. IETF. August 2022. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc9052
[VC-DATA-MODEL]
Verifiable Credentials Data Model v1.1. Manu Sporny; Grant Noble; Dave Longley; Daniel Burnett; Brent Zundel; Kyle Den Hartog. W3C. 3 March 2022. W3C Recommendation. URL: https://www.w3.org/TR/vc-data-model/
[XMLSCHEMA11-2]
W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes. David Peterson; Sandy Gao; Ashok Malhotra; Michael Sperberg-McQueen; Henry Thompson; Paul V. Biron et al. W3C. 5 April 2012. W3C Recommendation. URL: https://www.w3.org/TR/xmlschema11-2/

B.2 Informative references

[RFC7516]
JSON Web Encryption (JWE). M. Jones; J. Hildebrand. IETF. May 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7516
[VC-IMP-GUIDE]
Verifiable Credentials Implementation Guidelines 1.0. Andrei Sambra. W3C. 24 September 2019. W3C Working Group Note. URL: https://www.w3.org/TR/vc-imp-guide/