Skip to content

Aries RFC 0881: W3C SD-JWT Verifiable Credential (vc+sd-jwt) Attachment format for requesting and issuing credentials

Summary

This RFC registers an attachment format for use in the issue-credential V2 protocol based on W3C Verifiable Credentials with SD-JWT securing mechanism from the VC Data Model 2.0.

Motivation

The Issue Credential protocol needs an attachment format to be able to exchange W3C credentials secured with SD-JWT. SD-JWT enables selective disclosure of claims, allowing holders to present only the claims they choose to share with a verifier. The vc+sd-jwt media type is defined in the W3C VC-JOSE-COSE specification targeting VC Data Model 2.0.

Tutorial

Complete examples of messages are provided in the reference section.

Reference

Credential Offer Attachment Format

Format identifier: didcomm/[email protected]

This format is used to offer a credential to a potential holder. The JSON structure might look like this:

{
  "binding_required": true,
  "binding_method": {
    "didcomm_signed_attachment": {
      "algs_supported": ["ES256", "EdDSA"],
      "did_methods_supported": ["key", "jwk"],
      "nonce": "b19439b0-4dc9-4c28-b796-99d17034fb5c"
    }
  },
  "selectively_disclosable_claims": [
    "$.credentialSubject.degree.name",
    "$.credentialSubject.degree.type"
  ],
  "credential": {
    "@context": [
      "https://www.w3.org/ns/credentials/v2",
      "https://www.w3.org/ns/credentials/examples/v2"
    ],
    "type": ["VerifiableCredential", "UniversityDegreeCredential"],
    "issuer": "did:key:z6MkodKV3mnjQQMB9jhMZtKD9Sm75ajiYq51JDLuRSPZTXrr",
    "validFrom": "2020-01-01T19:23:24Z",
    "validUntil": "2021-01-01T19:23:24Z",
    "credentialSubject": {
      "degree": {
        "type": "BachelorDegree",
        "name": "Bachelor of Science and Arts"
      }
    }
  }
}

A complete offer-credential message from the Issue Credential protocol 2.0 might look like this:

{
  "@id": "284d3996-ba85-45d9-964b-9fd5805517b6",
  "@type": "https://didcomm.org/issue-credential/2.0/offer-credential",
  "comment": "<some comment>",
  "formats": [
    {
      "attach_id": "5b38af88-d36f-4f77-bb7a-2f04ab806eb8",
      "format": "didcomm/[email protected]"
    }
  ],
  "offers~attach": [
    {
      "@id": "5b38af88-d36f-4f77-bb7a-2f04ab806eb8",
      "mime-type": "application/json",
      "data": {
        "base64": "ewogICJiaW5kaW5nX3JlcXVpcmVkIjogdHJ1ZSwK...(clipped)...fQp9"
      }
    }
  ]
}
  • binding_required - Optional. Boolean indicating whether the credential MUST be bound to the holder. If omitted, the credential is not required to be bound to the holder. If set to true, the credential MUST be bound to the holder using at least one of the binding methods defined in binding_method.
  • binding_method - Required if binding_required is true. Object containing key-value pairs of binding methods supported by the issuer to bind the credential to a holder. See Binding Methods for a registry of default binding methods supported as part of this RFC.
  • selectively_disclosable_claims - Optional. Array of strings indicating which claims in the issued credential will be selectively disclosable. Each string is a JSONPath expression that points to a single, unambiguous location within the credential object (e.g. $.credentialSubject.degree.name). Only dot-notation member accessors and array indices (e.g. $.credentialSubject.addresses[0].street) are permitted — wildcards, filters, array slices, and recursive descent MUST NOT be used. If omitted, the issuer does not communicate which claims will be selectively disclosable ahead of issuance.
  • credential - Required. The credential to be issued. The credential MUST conform to VC Data Model 2.0. The credential MUST NOT contain any proofs. Some properties MAY be omitted if they will only be available at time of issuance, such as validFrom, issuer, credentialSubject.id, credentialStatus.

Credential Offer Exceptions

To allow for validation of the credential in the offer, the credential MUST be conformant to the VC Data Model 2.0, except for the following exceptions:

  • validFrom can be omitted, or set to a placeholder value.
  • issuer (or issuer.id if issuer is an object) can be omitted.
  • credentialSubject.id can be omitted.
  • credentialStatus can be omitted entirely, or credentialStatus.type can be present with other dynamic fields omitted.

Credential Request Attachment Format

Format identifier: didcomm/[email protected]

This format is used to request issuance of a credential. The JSON structure might look like this:

{
  "binding_proof": {
    "didcomm_signed_attachment": {
      "attachment_id": "attachment-0"
    }
  }
}

A complete request-credential message from the Issue Credential protocol 2.0 might look like this:

{
  "@id": "7293daf0-ed47-4295-8cc4-5beb513e500f",
  "@type": "https://didcomm.org/issue-credential/2.0/request-credential",
  "comment": "<some comment>",
  "formats": [
    {
      "attach_id": "13a3f100-38ce-4e96-96b4-ea8f30250df9",
      "format": "didcomm/[email protected]"
    }
  ],
  "requests~attach": [
    {
      "@id": "13a3f100-38ce-4e96-96b4-ea8f30250df9",
      "mime-type": "application/json",
      "data": {
        "base64": "ewogICJiaW5kaW5nX3Byb29mIjogewogICAgImRpZGNvbW1fc2lnbmVkX2F0dGFjaG1lbnQiOiB7CiAgICAgICJhdHRhY2htZW50X2lkIjogImF0dGFjaG1lbnQtMCIKICAgIH0KICB9Cn0="
      }
    }
  ],
  "~attach": [
    {
      "@id": "attachment-0",
      "mime-type": "application/json",
      "data": {
        "base64": "<base64-encoded-json-attachment-content>",
        "jws": {
          "protected": "eyJhbGciOiJFZERTQSIsImtpZCI6ImRpZDprZXk6... (bytes omitted)",
          "signature": "3dZWsuru7QAVFUCtTd0s7uc1peYEijx4eyt5... (bytes omitted)"
        }
      }
    }
  ]
}
  • binding_proof - Required if binding_required is true in the offer. Object containing key-value pairs of proofs for the binding to the holder. The keys MUST match keys of the binding_method object from the offer. See Binding Methods for a registry of default binding methods supported as part of this RFC.

Credential Attachment Format

Format identifier: didcomm/[email protected]

This format is used to transmit a verifiable credential with SD-JWT securing mechanism. The JSON structure might look like this:

{
  "credential": "eyJhbGciOiJFUzI1NiJ9.eyJfc2QiOi...(clipped)...~"
}

A complete issue-credential message from the Issue Credential protocol 2.0 might look like this:

{
  "@id": "284d3996-ba85-45d9-964b-9fd5805517b6",
  "@type": "https://didcomm.org/issue-credential/2.0/issue-credential",
  "comment": "<some comment>",
  "formats": [
    {
      "attach_id": "5b38af88-d36f-4f77-bb7a-2f04ab806eb8",
      "format": "didcomm/[email protected]"
    }
  ],
  "credentials~attach": [
    {
      "@id": "5b38af88-d36f-4f77-bb7a-2f04ab806eb8",
      "mime-type": "application/json",
      "data": {
        "json": {
          "credential": "eyJhbGciOiJFUzI1NiJ9.eyJfc2QiOi...(clipped)...~"
        }
      }
    }
  ]
}
  • credential - Required. The SD-JWT in compact serialization format. The credential MUST conform to the VC Data Model 2.0 and use the application/w3c-vc-sd-jwt media type as defined in W3C VC-JOSE-COSE.

It is up to the issuer to decide which claims are selectively disclosable. If selectively_disclosable_claims was provided in the offer, the issued SD-JWT MUST make at least those claims selectively disclosable. If binding_required was true in the offer, the issued SD-JWT MUST include a cnf (confirmation) claim bound to the holder's key as provided through the binding proof.

Binding Methods

The attachment format supports different methods to bind the credential to the receiver of the credential. In the offer message the issuer can indicate which binding methods are supported in the binding_method object. Each key represents the id of the supported binding method.

This section defines a set of binding methods supported by this attachment format, but other binding methods may be used. Based on the binding method, the request needs to include a binding_proof object where the key matches the key of the binding method from the offer.

DIDComm Signed Attachment

Identifier: didcomm_signed_attachment

This binding method leverages DIDComm signed attachments to bind a credential to a specific key and/or identifier.

Binding Method in Offer
{
  "didcomm_signed_attachment": {
    "algs_supported": ["ES256", "EdDSA"],
    "did_methods_supported": ["key", "jwk"],
    "nonce": "b19439b0-4dc9-4c28-b796-99d17034fb5c"
  }
}
  • algs_supported - Required. List of strings indicating the JSON Web Algorithms supported by the issuer for verifying the signed attachment. The list MUST contain at least one value. The values MUST be a valid algorithm identifier as defined in the JSON Web Signature and Encryption Algorithms registry.
  • did_methods_supported - Required. List of strings indicating which DID methods are supported by the issuer for binding the credential to the holder. The list MUST contain at least one value. Values should ONLY include the method identifier of the DID method (e.g. key, jwk, web).
  • nonce - Required. Nonce to be used in the request to prevent replay attacks of the signed attachment.
Binding Proof in Request

The binding proof in the request points to an appended attachment containing the signed attachment.

{
  "didcomm_signed_attachment": {
    "attachment_id": "<@id of the attachment>"
  }
}
  • attachment_id - Required. The id of the appended attachment included in the request message that contains the signed attachment.
Signed Attachment Content

The attachment MUST be signed by including a signature in the jws field of the attachment. The data MUST be a JSON document encoded in the base64 field of the attachment.

JWS Payload:

{
  "nonce": "<nonce from the offer binding_method>"
}
  • nonce - Required. The nonce from the didcomm_signed_attachment object within binding_method from the credential offer.

Protected Header:

{
  "alg": "ES256",
  "kid": "did:key:zDnaerDaTF5BXEavCrfRZEk316dpbLsfPDZ3WJ5hRTPFU2169#zDnaerDaTF5BXEavCrfRZEk316dpbLsfPDZ3WJ5hRTPFU2169"
}
  • alg - Required. A digital signature algorithm identifier as per IANA "JSON Web Signature and Encryption Algorithms" registry. MUST NOT be none or an identifier for a symmetric algorithm (MAC). MUST match one of the algs_supported entries from the offer binding_method object.
  • kid - Required. JOSE Header containing the DID URL pointing to a specific key in a DID document. The DID method of the DID URL MUST match one of the did_methods_supported from the offer binding_method object.
Binding in Credential

The issued SD-JWT MUST include a cnf (confirmation) claim containing the holder's public key material, enabling SD-JWT Key Binding as defined in SD-JWT-based Verifiable Credentials.

Drawbacks

  • There is currently no attachment format defined for a credential proposal. This makes it impossible for a holder to initiate the issuance of a credential using this attachment format.
  • This RFC only covers issuance. A separate attachment format is needed for presenting SD-JWT credentials via Present Proof v2 (RFC 0454).

Rationale and alternatives

Prior art

This attachment format is structurally based on RFC 0809: W3C Data Integrity Credential Attachment, adapted for the SD-JWT securing mechanism.

Unresolved questions

  • Should the holder be able to propose specific claims as selectively disclosable?
  • Should the cnf binding format used (i.e. jwk vs kid key binding of the holder DID's VM) be negotiable? (currently at the issuer's discretion)

Implementations

The following lists the implementations (if any) of this RFC. Please do a pull request to add your implementation. If the implementation is open source, include a link to the repo or to the implementation within the repo. Please be consistent in the "Name" field so that a mechanical processing of the RFCs can generate a list of all RFCs supported by an Aries implementation.

Name / Link Implementation Notes