# Aries RFC XXXX: W3C Verifiable Credential Attachment format for requesting and issuing credentials

- Authors: Timo Glastra (Animo Solutions)
- Status: [ACCEPTED](/README.md#accepted)
- Since: 2023-12-13
- Status Note: Included as part of the JSON-LD verifiable credentials subtarget of [AIP v2.0](../../concepts/0302-aries-interop-profile/README.md).
- Supersedes: [Aries RFC 0593: JSON-LD Credential Attachment](https://github.com/hyperledger/aries-rfcs/blob/main/features/0593-json-ld-cred-attach/README.md)
- Start Date: 2023-12-13
- Tags: [feature](/tags.md#feature), [protocol](/tags.md#protocol), [credentials](/tags.md#credentials), [test-anomaly](/tags.md#test-anomaly)

## Summary

This RFC registers an attachment format for use in the [issue-credential V2](../0453-issue-credential-v2/README.md) protocol based on W3C Verifiable Credentials from the [VC Data Model](https://www.w3.org/TR/vc-data-model/#linked-data-proofs). It aims to support both JSON-LD and JWT based proof formats.

## Motivation

The Issue Credential protocol needs an attachment format to be able to exchange W3C verifiable credentials. It is desirable to make use of specifications developed in an open standards body, such as the [Credential Manifest](https://identity.foundation/credential-manifest/) for which the attachment format is described in [RFC 0511: Credential-Manifest Attachment format](../0511-dif-cred-manifest-attach/README.md). However, the _Credential Manifest_ is not finished and ready yet, and therefore there is a need to bridge the gap between standards.

## Tutorial

Complete examples of messages are provided in the [reference section](#reference).

## Reference

## Credential Offer Attachment Format

{
    "format": "<format>" // jwt_vc or di_vc
    "crypto_suites_supported": ["Ed25519Signature2018", "AnonCredsProof2023", "EdDSA"],
    // Q: do we need to specify which algs are supported for the didcomm_signed_attachment
    // Q: do we only support did for the binding in a didcomm_signed_attachment, or should that be flexible?
    // Q: should we allow to specify which did methods are supported by the issuer for the didcomm_signed_attachment?
    "binding_methods_supported": ["anoncreds_link_secret", "didcomm_signed_attachment"],
    "credential": {
        // contents of VC
        // May omit credentialSubject.id if this is bound to the request
    },
    "request_nonce": "",
    "options": {
        "credentialStatus": {
            "type": "AnonCredsCredentialStatusList2023"
        }
    }
    // TODO: add anoncreds specific options somewhere?
}

- `format` - String indicating the format of w3c credential that will be issued. See [Proof Formats](#proof-formats) for supported proof formats.
- `crypto_suites_supported` - Array of strings indicating which crypto suites are supported by the issuer offering the credential. The specific values that are allowed in this array are dependant on the format. E.g. for the `ldp_vc` format, entries must be signature suite types, while for `jwt_vc` entries must be JWAs.
- `binding_methods_supported` - Array of strings indicating which binding methods are supported by the issuer offering the credential. A binding method allows a credential to be bound to a holder. See [Binding Methods](#binding-methods) for supported binding methods.
- `credential` - The W3C credential contents without proof. It is allowed for the issuer offering the credential to omit some values from the credential in the offer (such as specific `id`), that will be in the finally issued credential. The `credential` in the offer message is to indicate to the receiver of the credential the intentions about which credential will be issued, and to allow negotiation to occur.
- `options` - TODO
- `request_nonce` - String that should be used in the request for the binding proof.

### Credential Request Attachment Format

Format identifier: `didcomm/w3c-vc-request@v0.1`

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

{
    "format": "<format>",
    "binding_proof": {
        "method": "<binding-proof-method>",
        // binding method specific properties
    }
}

- `format` - String indicating the format being requested. MUST match the format from the offer.
- `binding_proof` - Object containing the proof to bind the credential to a holder. Besides the `method`, other attributes in the `binding_proof` object are defined by the specific binding method used. See [Binding Methods](#binding-methods) for supported binding methods.
- `method` - String indicating the method used for the binding proof. Must match an entry from the `binding_methods_supported` array from the offer.

### Credential Attachment Format

Format identifier: `didcomm/w3c-vc@v0.1`

This format is used to transmit a verifiable credential. The JSON structure might look like this:

{
    "format": "<format>"
    "credential": "<signed-credential>"
}

- `format` - The format of issued credential. MUST match the `format` from the request.
- `credential` - The signed credential. Can be either a string (e.g. in case of JWT VC) or an object (e.g. in case of W3C credential with `proof`)

A complete [`issue-credential` message from the Issue Credential protocol 2.0](../0453-issue-credential-v2/README.md#issue-credential) 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/w3c-vc@v0.1"
    }
  ],
  "credentials~attach": [
    {
      "@id": "5b38af88-d36f-4f77-bb7a-2f04ab806eb8",
      "mime-type": "application/ld+json",
      "data": {
        "base64": "ewogICAgICAgICAgIkBjb250ZXogWwogICAgICAg...(clipped)...RNVmR0SXFXZhWXgySkJBIgAgfQogICAgICAgIH0="
      }
    }
  ]
}

### Proof Formats

This section describes different methods for securing the integrity of a W3C verifiable credential. Each format

#### Data Integrity Proof

Format identifier: `di_vc`

Secure a W3C verifiable credential using a Data Integrity Proof, as defined in [Section 6.3.2 Data Integrity Proofs](https://www.w3.org/TR/vc-data-model/#data-integrity-proofs) from the Verifiable Credential Data Model.

> NOTE:
> The VC Data Model used to point to Linked Data Proofs, but now points to the new Data Integrity VC specification. The data integrity VC spec
> has more strict requirements it seems on how the `proof` object should look (e.g. multibase `proofValue` is required). I'm not sure if we need
> to add `ldp_vc` as a format as well to support older signature suites not conforming to the new data integrity spec. But it feels weird that the
> LDPs have been renamed, and now pointing to a spec that is not compatible (and thus a breaking change it seems?).

When `format` is `di_vc` the following applies:
- The values in the `cryptographic_suites_supported` MUST be valid ?? types as defined in XXX
- The `credential` property in the credential message MUST be an object containing a W3C verifiable credential with `proof` property
- The `credenital` in the credential message MAY contain multiple proofs

#### Json Web Token

Format identifier: `jwt_vc`

Secure a W3C verifiable credential using a JSON Web Token, as defined in [Section 6.3.1 JSON Web Token](https://www.w3.org/TR/vc-data-model/#json-web-token) from the Verifiable Credential Data Model.

When `format` is `jwt_vc` the following applies:
- The values in the `cryptographic_suites_supported` MUST be valid JSON Web Algorithms as defined in XXX
- `anoncreds_link_secret` MUST NOT be used for the `binding_proof`
- The `credential` property in the credential message MUST be a string containing a compact JWT securing the W3C verifiable credential

### 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_methods_supported` array.

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 `method` defines the specific binding method that is chosen.

#### AnonCreds Link Secret

Identifier: `anoncreds_link_secret`

This binding method is intended to be used in combination with a credential containing an AnonCreds proof. The structure of the `binding_proof` in the request MUST match the structure of the [Credential Request](https://hyperledger.github.io/anoncreds-spec/#credential-request) as defined in the AnonCreds specification, with the addition of the `method` key.

{
    "method": "anoncreds_link_secret",
    "entropy": "<random-entropy>",
    "blinded_ms": {},
    "blinded_ms_corectness_proof": {},
    "nonce": "<random-nonce>"
}

#### DIDComm Signed Attachment

Identifier: `didcomm_signed_attachment`

This binding method leverages [DIDComm signed attachments](https://github.com/hyperledger/aries-rfcs/blob/main/concepts/0017-attachments/README.md#signing-attachments) to bind a credential to a specific key and/or identifier.

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 `base64` field. The structure of the signed attachment is described below.

{
    "method": "didcomm_signed_attachment",
    "attachment_id": "<@id of the attachment>"
}

- `attachment_id` - The id of the appended attachment included in the offer message that contains the signed attachment.

##### Signed Attachment Content

**JWS Payload**

{
    "nonce": "<request_nonce>",
    "aud": "did:web:example.com"
}

- `nonce` - The `request_nonce` from the credential offer
- `aud` - Intended audience of the signed attachment. MUST be the same as the issuer identifier in the `credential` from the offer

**Signed JWS Header**

- `alg`: REQUIRED. A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry. MUST NOT be none or an identifier for a symmetric algorithm (MAC).
- `kid`: OPTIONAL. JOSE Header containing the key ID. If the Credential shall be bound to a DID, the kid refers to a DID URL which identifies a particular key in the DID Document that the Credential shall be bound to.

## Drawbacks

While it has a similar setup and structure compared to OpenID for Verifaible Credential Issuance, this attachment format only focuses on issuance of W3C Verifiable Credentials. Therefore another (but probably quite similar) attachment format needs to be defined to support issuance of non-W3C VCs

## Rationale and alternatives

[RFC 0593: JSON-LD Credential Attachment](https://github.com/hyperledger/aries-rfcs/blob/main/features/0593-json-ld-cred-attach/README.md), [W3C VC API](https://w3c-ccg.github.io/vc-api/) allows issuance of credentials using only linked data signatures, while [RFC 0592: Indy Attachment](https://github.com/hyperledger/aries-rfcs/blob/main/features/0592-indy-attachments/README.md) supports issuance of AnonCreds credentials. This attachment format aims to support issuance of both previous attachment formats (while for AnonCreds it now being in the W3C model), as well as supporting additional features such as issuance W3C JWT VCs, credentials with multiple proofs, and cryptographic binding of the credential to the holder.

## Prior art

The attachment format in this RFC is heavily inspired by [RFC 0593: JSON-LD Credential Attachment](https://github.com/hyperledger/aries-rfcs/blob/main/features/0593-json-ld-cred-attach/README.md), [W3C VC API](https://w3c-ccg.github.io/vc-api/) and [OpenID for Verifiable Credential Issuance](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html).

## Unresolved questions

- Should we support multi-credential offers?
- It may be desirable to have multi-format (so jwt or ldp_vc), or should that also be handled by multiple attachment formats?
- Should we support `jwk` as well, in addition to `kid` in the header? Would allow a credential to be bound to a JWK rather than a did
- With VCDM 2.0 being mostly ready for usage, it might be worth to support both v1.x and v2.x versions of the VCDM in this attachment format. Version support could be indicated in the proposal/offer/request messages using a `data_model_version` property. An implementer is not required to support all versions, but we would define both `v1.1` and `v2.0` as currently recognized data model versions.
- Do we need to support multiple binding methods for a single credential?
- Relevant in case of W3C VC with AnonCreds + Ed22519
- Wondering whether AnonCreds should be a separate format? Ideally not, but in that case we need to define some properties that can be included for specific proof.type values.
- Is it required for the receiver to know upfront which proof type(s) the issuer will use to secure the integrity of the VC?