Skip to content

Latest commit

 

History

History
219 lines (174 loc) · 10 KB

README.md

File metadata and controls

219 lines (174 loc) · 10 KB
Raw

Aries RFC 0593: JSON-LD Credential Attachment format for requesting and issuing credentials

  • Authors: Timo Glastra (Animo Solutions), George Aristy (SecureKey Technologies)
  • Status: ADOPTED
  • Since: 2021-04-15
  • Status Note: Included as part of the JSON-LD verifiable credentials subtarget of AIP v2.0.
  • Supersedes:
  • Start Date: 2021-02-17
  • Tags: feature, protocol, credentials, test-anomaly

Summary

This RFC registers an attachment format for use in the issue-credential V2 protocol based on JSON-LD credentials with Linked Data Proofs from the VC Data Model.

It defines a minimal set of parameters needed to create a common understanding of the verifiable credential to issue. It is based on version 1.0 of the Verifiable Credentials Data Model which is a W3C recommendation since 19 November 2019.

Motivation

The Issue Credential protocol needs an attachment format to be able to exchange JSON-LD credentials with Linked Data Proofs. It is desirable to make use of specifications developed in an open standards body, such as the Credential Manifest for which the attachment format is described in RFC 0511: Credential-Manifest Attachment format. 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

ld-proof-vc-detail attachment format

Format identifier: aries/[email protected]

This format is used to formally propose, offer, or request a credential. The credential property should contain the credential as it is going to be issued, without the proof and credentialStatus properties. Options for these properties are specified in the options object.

The JSON structure might look like this:

{
  "credential": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://www.w3.org/2018/credentials/examples/v1"
    ],
    "id": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
    "type": ["VerifiableCredential", "UniversityDegreeCredential"],
    "issuer": "did:key:z6MkodKV3mnjQQMB9jhMZtKD9Sm75ajiYq51JDLuRSPZTXrr",
    "issuanceDate": "2020-01-01T19:23:24Z",
    "expirationDate": "2021-01-01T19:23:24Z",
    "credentialSubject": {
      "id": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH",
      "degree": {
        "type": "BachelorDegree",
        "name": "Bachelor of Science and Arts"
      }
    }
  },
  "options": {
    "proofPurpose": "assertionMethod",
    "created": "2020-04-02T18:48:36Z",
    "domain": "example.com",
    "challenge": "9450a9c1-4db5-4ab9-bc0c-b7a9b2edac38",
    "credentialStatus": {
      "type": "CredentialStatusList2017"
    },
    "proofType": "Ed25519Signature2018"
  }
}

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

{
  "@id": "7293daf0-ed47-4295-8cc4-5beb513e500f",
  "@type": "https://didcomm.org/issue-credential/%VER/request-credential",
  "comment": "<some comment>",
  "formats": [
    {
      "attach_id": "13a3f100-38ce-4e96-96b4-ea8f30250df9",
      "format": "aries/[email protected]"
    }
  ],
  "requests~attach": [
    {
      "@id": "13a3f100-38ce-4e96-96b4-ea8f30250df9",
      "mime-type": "application/json",
      "data": {
        "base64": "ewogICJjcmVkZW50aWFsIjogewogICAgIkBjb250...(clipped)...IkVkMjU1MTlTaWduYXR1cmUyMDE4IgogIH0KfQ=="
      }
    }
  ]
}

  • credential - Required. Detail of the JSON-LD Credential that will be issued. Properties MUST align with the Verifiable Credentials Data Model. This also means all properties required by the data model MUST be present. The properties listed below are formally supported, but additional properties MAY be included if it conforms with the data model.

    • @context
    • id
    • type
    • issuer
    • issuanceDate
    • expirationDate
    • credentialSubject

  • options - Required. Options for specifying how the linked data proof is created.

    • proofType - Required string. The proof type used for the proof. Should match suites registered in the Linked Data Cryptographic Suite Registry.
    • proofPurpose - Optional string, default assertionMethod. The proof purpose used for the proof. Should match proof purposes registered in the Linked Data Proofs Specification.
    • created - Optional string, default current system time. The date and time of the proof (with a maximum accuracy in seconds).
    • challenge - Optional string. A challenge to include in the proof. SHOULD be provided by the requesting party of the credential (=holder).
    • domain - Optional string. The intended domain of validity for the proof.
    • credentialStatus - Optional object. The credential status mechanism to use for the credential. Omitting the property indicates the issued credential will not include a credential status.

The format is closely related to the Verifiable Credentials HTTP API, but diverts on some places. The main differences are:

  • The types in the VC HTTP API are more restrictive (.e.g. @context must be array of strings). This format allows all fields to use the full syntax as described by the verifiable credentials data model.
  • Instead of specifying the exact verificationMethod, the proofType that will be used for the credential can be specified.

ld-proof-vc attachment format

Format identifier: aries/[email protected]

This format is used to transmit a verifiable credential with linked data proof. The contents of the attachment is a standard JSON-LD Verifiable Credential object with linked data proof as defined by the Verifiable Credentials Data Model and the Linked Data Proofs specification.

The JSON structure might look like this:

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.gov/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": {
    "id": "did:web:vc.transmute.world"
  },
  "issuanceDate": "2020-03-10T04:24:12.164Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science and Arts"
    }
  },
  "proof": {
    "type": "JsonWebSignature2020",
    "created": "2020-03-21T17:51:48Z",
    "verificationMethod": "did:web:vc.transmute.world#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
    "proofPurpose": "assertionMethod",
    "jws": "eyJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCJdLCJhbGciOiJFZERTQSJ9..OPxskX37SK0FhmYygDk-S4csY_gNhCUgSOAaXFXDTZx86CmI5nU9xkqtLWg-f4cqkigKDdMVdtIqWAvaYx2JBA"
  }
}

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/%VER/issue-credential",
  "comment": "<some comment>",
  "formats": [
    {
      "attach_id": "5b38af88-d36f-4f77-bb7a-2f04ab806eb8",
      "format": "aries/[email protected]"
    }
  ],
  "credentials~attach": [
    {
      "@id": "5b38af88-d36f-4f77-bb7a-2f04ab806eb8",
      "mime-type": "application/ld+json",
      "data": {
        "base64": "ewogICAgICAgICAgIkBjb250ZXogWwogICAgICAg...(clipped)...RNVmR0SXFXZhWXgySkJBIgAgfQogICAgICAgIH0="
      }
    }
  ]
}

Supported Proof Types

Following are the Linked Data proof types on Verifiable Credentials that MUST be supported for compliance with this RFC. All suites listed in the following table MUST be registered in the Linked Data Cryptographic Suite Registry:

Suite Spec Enables Selective disclosure? Enables Zero-knowledge proofs? Optional
Ed25519Signature2018 Link No No No
BbsBlsSignature2020** Link Yes No No
JsonWebSignature2020*** Link No No Yes

** Note: see RFC0646 for details on how BBS+ signatures are to be produced and consumed by Aries agents.

*** Note: P-256 and P-384 curves are supported.

Drawbacks

N/A

Rationale and alternatives

  • The hlindy-zkp-v1.0 format is an alternative restricted to the Hyperledger Indy network. The dif/[email protected] allows to issue JSON-LD credentials but is not ready yet for usage.

Prior art

N/A

Unresolved questions

N/A

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