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.
1{
2 "method": "web",
3 "options": {
4 "url": "organization.com",
5 "keyType": "Bls12381G2"
6 }
7}
Response
The resulting DID resides in the
didattribute.If you want to confirm the DID will work for issuing ZKP-enabled credentials, check the DID URL for the
assertionMethodmatches apublicKey.idthat contains"type": "Bls12381G2Key2020".
1{
2 "did": "did:web:organization.com",
3 "registrationStatus": "COMPLETED",
4 "localMetadata": {
5 "keys": [
6 {
7 "didDocumentKeyId": "did:web:organization.com#oKhQ6nfNxg",
8 "kmsKeyId": "a4c76bad-897c-4202-8fbd-3257e165d215"
9 },
10 {
11 "didDocumentKeyId": "did:web:organization.com#2EHAKPYcG6",
12 "kmsKeyId": "6bb9bb7a-70b4-45ee-9d02-30bcecc34aa4"
13 }
14 ],
15 "registered": 1632282683786,
16 "initialDidDocument": {
17 "@context": "https://w3.org/ns/did/v1",
18 "id": "did:web:organization.com",
19 "publicKey": [
20 {
21 "id": "did:web:organization.com#oKhQ6nfNxg",
22 "controller": "did:web:organization.com",
23 "type": "Bls12381G2Key2020",
24 "publicKeyBase58": "oKhQ6nfNxgjkmMDXJpyQnpPrHZBMWjaEfBfRzxKYwL51zHA7W3QhjKkpoksD7kMkyMphMCfHFc5f7T2avs3THwiXPr6g6AiLs3i62BTgJeaK3zmkjb8Pcbper7grDgNjUCQ"
25 }
26 ],
27 "authentication": [
28 "did:web:organization.com#oKhQ6nfNxg"
29 ],
30 "assertionMethod": [
31 "did:web:organization.com#oKhQ6nfNxg"
32 ],
33 "capabilityDelegation": [
34 "did:web:organization.com#oKhQ6nfNxg"
35 ],
36 "capabilityInvocation": [
37 "did:web:organization.com#oKhQ6nfNxg"
38 ],
39 "keyAgreement": [
40 {
41 "id": "did:web:organization.com#2EHAKPYcG6",
42 "controller": "did:web:organization.com",
43 "type": "X25519KeyAgreementKey2019",
44 "publicKeyBase58": "2EHAKPYcG6wPdpMHjRtwDhg4WnSyi695V7EkfRRNxmYW"
45 }
46 ]
47 }
48 }
49}
Create a credential
Create a credential by making an API request as follows:
Request
1POST https://YOUR_TENANT_URL/v2/credentials/web-semantic/sign1{
2 "payload": {
3 "@context": [
4 "https://schema.org"
5 ],
6 "name": "Course credential",
7 "description": "Course credential description",
8 "type": [
9 "CourseCredential"
10 ],
11 "credentialSubject": {
12 "id": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi",
13 "givenName": "Chris",
14 "familyName": "Shin",
15 "educationalCredentialAwarded": "Certificate Name"
16
17 },
18 "issuer": {
19 "id": " did:web:organization.com ",
20 "name": "tenant"
21 },
22 "expirationDate": "2024-02-07T06:44:28.952Z"
23 },
24 "persist": false,
25 "revocable": true,
26}
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 common data vocab https://schema.org
type is an array of credential types. It indicates what sort of information a credential holds. This is a unique identifier that the system uses to differentiate between different types of Web Credentials. There MUST be a value of type other than VerifiableCredential in the payload.
The credentialSubject.Id specifies an identifier bound to the credential. This is usually a decentralised identifier (DID) that's owned by the credential holder.
Response
1
2"id": "ab42adbc-1139-47f0-9256-3bf5a01fcc7e",
3"credential": {
4 "type": [
5 "VerifiableCredential",
6 "CourseCredential"
7 ],
8 "issuer": {
9 "id": "did:web:organization.com",
10 "name": "tenant"
11 },
12 "name": "Course credential",
13 "description": "Course credential description",
14 "issuanceDate": "2020-09-24T19:16:33.222Z",
15 "expirationDate": "2024-02-07T06:44:28.952Z",
16 "credentialSubject": {
17 "id": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi",
18 "givenName": "Chris",
19 "familyName": "Shin",
20 "educationalCredentialAwarded": "Certificate Name"
21 },
22 "@context": [
23 "https://www.w3.org/2018/credentials/v1",
24 "https://w3id.org/security/bbs/v1",
25 "https://w3id.org/vc-revocation-list-2020/v1",
26 "https://mattr.global/contexts/vc-extensions/v2",
27 "https://schema.org"
28 ],
29 "credentialStatus": {
30 "id": "https://tenant.vii.mattr.global/core/v1/revocation-lists/dd7ceeaa-a5e0-4ab3-a70c-b7237500c605#0",
31 "type": "RevocationList2020Status",
32 "revocationListIndex": "0",
33 "revocationListCredential": "https://YOUR_TENANT_URL/core/v1/revocation-lists/dd7ceeaa-a5e0-4ab3-a70c-b7237500c605"
34 },
35 "proof": {
36 "type": "BbsBlsSignature2020",
37 "created": "2020-11-24T19:16:33Z",
38 "proofPurpose": "assertionMethod",
39 "proofValue": "pVJlfG/Ra9h8WbwqthNsT4lY9Xx5eVxZR6j0GY3yoDNzJq1CuF+nWKgcie3LpAn3UQpzkiODY46kt/WWaqGzyKyX4k5KRsBuSU9pSAL5Y99QFhnrm8t2MeKuZ1NL++ZO1+IelYtNjl6OmajHdphDUA==",
40 "verificationMethod": "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v#zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v"
41 }
42 },
43 "credentialStatus": {
44 "id": "https://YOUR_TENANT_URL/v1/revocation-lists/dd7ceeaa-a5e0-4ab3-a70c-b7237500c605#0",
45 "type": "RevocationList2020Status",
46 "revocationListIndex": "0",
47 "revocationListCredential": "https://product-team.vii.staging.mattrlabs.io/v1/revocation-lists/dd7ceeaa-a5e0-4ab3-a70c-b7237500c605"
48 },
49 "issuanceDate": "2020-09-24T19:16:33.222Z"
50}
51
The returned credential object is the credential, with id and issuanceDate shown as meta-data, along with other fields depending on the options chosen.
https://www.w3.org/2018/credentials/v1 and https://mattr.global/contexts/vc-extensions/v2 which is the reference to the W3C credential definition is auto-injected as the first element in the context array.
VerifiableCredential is also auto-injected as the first element in the type array. Every W3C verifiable credential must include VerifiableCredential in the type property.
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 Bls12381BG2 key type.
Then either;
Create the credential as above and follow the tutorial to offer a credential directly or,
Follow all the steps in offer a credential using OpenID provisioning and make sure you have created DID with a
bls12381g2key that can be selected as theissuerDidwhen you issue a credential.
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.
