Create a ZKP-enabled JSON-LD Credential

Introduction

This guide will demonstrate how to create a ZKP-enabled credential.

ZKP-enabled credentials use the BBS+ signature suite, MATTR is heavily involved in developing these standards within the community. If you are planning on using this feature for production workloads please get in touch for more information on how we can help you as these standards continue to evolve.

Check out the video:

Prerequisites

You need access to the MATTR VII APIs. If you’re experiencing any difficulties, contact us.

In order to create a credential, you will need the following information:

  • Subject DID

  • Credential type

  • JSON-LD claim names as defined by schema.org

  • Claim values

Create a DID

In order to create a ZKP-enabled credential, you first need to create an Issuer DID with a bls12381g2 key type, which supports BBS+ signatures for issuing ZKP-enabled credentials.

Request

Set the keyType in the options to bls12381g2 in order to create a DID with a BLS key type.

json
Copy to clipboard.
1{
2  "method": "key",
3  "options": {
4    "keyType": "bls12381g2"
5  }
6}

Response

  • The resulting DID resides in the did attribute.

  • If you want to confirm the DID will work for issuing ZKP-enabled credentials, check the DID URL for the assertionMethod matches a publicKey.id that contains "type": "Bls12381G2Key2020".

json
Copy to clipboard.
1{
2  "did": "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v",
3  "registrationStatus": "COMPLETED",
4  "localMetadata": {
5    "keys": [
6      {
7        "didDocumentKeyId": "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v#zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v",
8        "kmsKeyId": "25voPUCTSWXcDLCZNfZeTWuNaDcM3KgQZqwkvuY1s2GNGJ3tJ3UubY8uFR4X8Ykhdb2xTnXkGffugi9rHsM4A3J5FRPCyoAh4ZrdcCWUSEj29pGahY1cUA7uR1ns52JeZBQc"
9      }
10    ],
11    "registered": 1600918030673,
12    "initialDidDocument": {
13      "@context": "https://w3.org/ns/did/v1",
14      "id": "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v",
15      "publicKey": [
16        {
17          "id": "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v#zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v",
18          "type": "Bls12381G2Key2020",
19          "controller": "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v",
20          "publicKeyBase58": "25voPUCTSWXcDLCZNfZeTWuNaDcM3KgQZqwkvuY1s2GNGJ3tJ3UubY8uFR4X8Ykhdb2xTnXkGffugi9rHsM4A3J5FRPCyoAh4ZrdcCWUSEj29pGahY1cUA7uR1ns52JeZBQc"
21        }
22      ],
23      "authentication": [
24        "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v#zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v"
25      ],
26      "assertionMethod": [
27        "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v#zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v"
28      ],
29      "capabilityDelegation": [
30        "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v#zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v"
31      ],
32      "capabilityInvocation": [
33        "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v#zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v"
34      ]
35    }
36  }
37}

Create a credential

Create a credential by making an API request as follows:

Request

http
Copy to clipboard.
1POST https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/core/v1/credentials
json
Copy to clipboard.
1{
2    "issuer": {
3        "id": "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v",
4        "name": "tenant"
5    },
6    "@context": [
7        "https://www.w3.org/2018/credentials/v1",
8        "https://schema.org"
9    ],
10    "subjectId": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi",
11    "type": [
12        "VerifiableCredential",
13        "CourseCredential"
14    ],
15    "claims": {
16        "givenName": "Chris",
17        "familyName": "Shin",
18        "educationalCredentialAwarded": "Certificate Name"
19    },
20    "persist": false,
21    "revocable": true
22}

The issuer.id contains the DID of the issuer, as created in the previous step.

When the issuer DID has the “keyType”:“bls12381g2”, the platform will automatically detect this capability and issue a ZKP-enabled BBS+ credential.

The @context must include the reference to the W3C credential definition "https://www.w3.org/2018/credentials/v1" and this example will use a common data vocab https://schema.org which is referenced in the claims field.

type is an array of credential types that must start with VerifiableCredential. It indicates what sort of information a credential holds.

The subjectId defines the DID of the subject. The issued credential attests claims about the subject.

Response

json
Copy to clipboard.
1{
2  "id": "ab42adbc-1139-47f0-9256-3bf5a01fcc7e",
3  "credential": {
4    "type": [
5      "VerifiableCredential",
6      "CourseCredential"
7    ],
8    "issuer": {
9      "id": "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v",
10      "name": "tenant"
11    },
12    "issuanceDate": "2020-09-24T19:16:33.222Z",
13    "credentialSubject": {
14      "id": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi",
15      "givenName": "Chris",
16      "familyName": "Shin",
17      "educationalCredentialAwarded": "Certificate Name"
18    },
19    "@context": [
20      "https://www.w3.org/2018/credentials/v1",
21      "https://w3c-ccg.github.io/ldp-bbs2020/context/v1",
22      "https://schema.org",
23      "https://w3id.org/vc-revocation-list-2020/v1"
24    ],
25    "credentialStatus": {
26      "id": "https://tenant.vii.mattr.global/core/v1/revocation-lists/dd7ceeaa-a5e0-4ab3-a70c-b7237500c605#0",
27      "type": "RevocationList2020Status",
28      "revocationListIndex": "0",
29      "revocationListCredential": "https://tenant.vii.mattr.global/core/v1/revocation-lists/dd7ceeaa-a5e0-4ab3-a70c-b7237500c605"
30    },
31    "proof": {
32      "type": "BbsBlsSignature2020",
33      "created": "2020-11-24T19:16:33Z",
34      "proofPurpose": "assertionMethod",
35      "proofValue": "pVJlfG/Ra9h8WbwqthNsT4lY9Xx5eVxZR6j0GY3yoDNzJq1CuF+nWKgcie3LpAn3UQpzkiODY46kt/WWaqGzyKyX4k5KRsBuSU9pSAL5Y99QFhnrm8t2MeKuZ1NL++ZO1+IelYtNjl6OmajHdphDUA==",
36      "verificationMethod": "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v#zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v"
37    }
38  },
39  "credentialStatus": {
40    "id": "https://product-team.vii.staging.mattrlabs.io/v1/revocation-lists/dd7ceeaa-a5e0-4ab3-a70c-b7237500c605#0",
41    "type": "RevocationList2020Status",
42    "revocationListIndex": "0",
43    "revocationListCredential": "https://product-team.vii.staging.mattrlabs.io/v1/revocation-lists/dd7ceeaa-a5e0-4ab3-a70c-b7237500c605"
44  },
45  "issuanceDate": "2020-09-24T19:16:33.222Z"
46}

The returned credential object is the credential, with id and issuanceDate shown as meta-data, along with other fields depending on the options chosen.

Because this is a ZKP-enabled credential it contains a BBS+ signature, which enables selective disclosure as defined by the proof type of BbsBlsSignature2020. For more information on this signature suite, check out the specification at the W3C CCG.

Obtain a ZKP-Enabled Credential on the Mobile Wallet

ZKP-enabled credentials provide valuable benefits to the subjects and holders of credentials. In order for them to receive those benefits, issuers must specifically issue them with ZKP-enabled credentials using signature schemes such as BBS+. The MATTR mobile wallet is interoperable with ZKP-enabled credentials containing BBS+ signatures. It responds appropriately to privacy-preserving Presentation Requests using JSON-LD Framing.

To set up an Issuer for ZKP-enabled credentials, first, create an Issuer DID with a bls12381g2 key type.

Then either;

Once the ZKP-enabled credential is stored in the mobile wallet, you can then move to the Verify tutorials and Create a Presentation Request Template for privacy-preserving requests.

The MATTR mobile wallet will indicate if a credential it is holding is ZKP-enabled.

https://www.datocms-assets.com/38428/1620705775-selective-disclosure.svg