Learn

Compact Credentials

Introduction

Compact Credentials are used to represent claims of data that can be cryptographically proven as authentic while being compact enough to fit inside a QR code.

MATTR VII's compact credential format is ideal where high information assurance is required but not high identity assurance about the entity presenting the credential.

Compact Credentials are ‘bearer credentials’ where all the assurance is fully self-contained within the QR code, with no need for complex dynamic presentation capability from the holder. For example, discount vouchers, physical asset tags, and luxury goods verification cards are all examples where having authentic information through the supply chain increases the value of goods and services produced.

The compact nature of the credential is an essential feature of offering credentials that work in offline or paper-based contexts. They reduce the digital divide by enabling a credential to be contained within a QR code that can be placed on a PDF and printed. Compact Credentials can also be stored digitally using Digital Passes, stored in Apple Wallet or Google Pay.

There are some key considerations that should be explored as part of implementing either a Compact or Semantic Compact credential into your ecosystem, MATTR has outlined a guide to these implementation considerations to further assist you in utilising the MATTR VII capability in the best way possible for your use case.

Because Compact Credentials are represented as QR codes, their payload is limited by the size of the QR generated and displayed. Therefore Compact Credentials use a terse payload structure in a Concise Binary Object Representation (CBOR) data format called CBOR Web Token (CWT). This structure is used to represent credentials that become cryptographically verifiable when signed by an issuer.

Holders present compact credentials by showing a verifier a QR code. This can be scanned visually, or digitally transmitted by uploading an image or PDF for verification. This makes them ideal for rapid validation situations or even places where there is only no reliable internet connectivity.

Properties

  • Verifiable data formats 

  • Issuer uses a DID Web identifier to host public key material using NIST approved P-256 key types 

  • Can be enclosed in an easily-read QR Code 

  • Revocable attributes that provide the issuer with continued control over the credential's validity

  • Printable onto PDF using templating functions 

  • Issue credentials to Apple or Google Pay wallets using your own developer accounts 

  • Can be verified online via API or entirely offline scenarios with the MATTR Verifier SDK or Verifier App (road mapped) 

Data Model Choices

Compact credentials can use either a W3C Verifiable Credential data model to provide more descriptive semantic meaning or a more concise, non-semantic model. The choice between the data model to use comes down to how compact you need the credential to be versus how openly you intend to share and exchange the created credentials across different domains and jurisdictions.

The W3C Verifiable Credential (VC) data model offers a standards-compliant way of constructing a verifiable credential that can be understood by many parties so the credential is semantic. However, the data model is expressive in ways that will result in payloads significantly larger than the claims data. The smaller the claims, the larger the ratio of the data model overhead. 

In general, the more compact the credential is, the quicker and easier it is to manage by holders and verifiers.  

Therefore, choosing between the semantic W3C VC compact credential and the standard CWT compact credential is just a balance of standards compliance for an open-data ecosystem or a more compact credential for a closed ecosystem. 

MATTR is exploring other credential formats based on properties of COSE, including detached digital signatures.

CBOR Object Signing & Encryption (COSE) 

CBOR is a binary data format derived from JSON that allows it to utilizes data types like numbers, strings & arrays, however, due to being binary, it offers a much more compact message size. Often when CBOR is being discussed or documented, we can represent the data model using JSON to simplify the way the data can be viewed and modelled. 

In the same way, JSON Object Signing & Encryption (JOSE) is used to create ubiquitous JSON Web Tokens (JWT) in the signed (JWS) and encrypted (JWE) flavours, CBOR Object Signing & Encryption (COSE) can be used to create CBOR Web Tokens (CWT) in the same formats known as CWS and CWE.  

COSE is a general-purpose digital signature encoding format that supports several different cryptographic algorithms. 

Compact credentials issued by the MATTR platform are CWTs that have been cryptographically signed using an issuer DID controlled by the tenant, this DID must be a DID Web using a P-256 key type.  

 At this stage only did:web with a P-256 key is supported for signing Compact Credentials. We have found that DIDs of this type make offline verification much easier by using standard caching mechanisms and better support for the cryptographic primitives. 

The CWTs created by the MATTR Platform will contain many standard claim types, including expiry date (“exp”), not before date (“nbf”) and a unique identifier (“jti”). These claims are represented in JSON as part of the `decoded` object, whereas the entire CWT with associated string pre-fix can be found in the `encoded` object of the response.

Standard claims

  • iss: represents the party who issued the credential. This must be a did:web using a P-256 key type available on the tenant. The claim key for iss of 1 MUST be used.

  • sub: represents the subject of the credential. If this claim is presented its value MUST be a text string. The claim key of 2 must be used.

  • kid: the key identifier header represents a reference to the signing key material. Its value corresponds to a relative reference to the key used to verify the signature of the credential, which MUST be combined with the value in the iss claim in the payload to resolve the public key. The claim key of 4 must be used.

  • alg: the Signature Algorithm header represents what algorithm is used for creating the signature. The claim key of 4  must be used.

  • exp (expiry, claim key 4), nbf (not before, claim key 5) and iat (issued at, claim key 6) are dates expressed as a timestamp encoded as an integer in the NumericDate format that controls the validity period of the credential once it has been issued. 

  • cti: (credential id) is the unique identifier of the credentials. It must be presented as a byte string. The claim key of 7 must be used.

  • status: specifies the status of a credential, such as whether it is revoked. It contains an optional type field with the default value BitIndexRevcationList. This is checked during verification. url is a URL of the revocation list. index is an integer greater than or equal to 0. It identifies the bit position of the revocation status for the credential.  The claim key of -65537 in the private range must be used.

Custom claims

Any custom claims can be included as part of the credential. This section describes two variants of payload structure that can be used for different use cases: compact profile and semantic compact profile.

Compact profile

A compact credential with a compact profile embeds custom claims in the same ways as other standard claims in the top level. The following is an example of a decoded payload:

json
Copy to clipboard.
1{
2  "iss": "did:web:example.nz",
3  "nbf": 1516239022,
4  "exp": 1516239922,
5  "jti": "Z2kmyTU-RBa08U3Kb8ZeZw",
6  "status": {
7    "url": "https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/core/v2/credentials/compact/revocation-lists/8f25e8a5-c878-411e-8141-43fb2d257137",
8    "index": 23434
9  },
10  "custom_claim1": "",
11  "custom_claim2": ""
12}

Currently, the value of any custom claims in the credential MUST be either a boolean, a string or a number. However, this can be extended to support more complex values in the future.

jti claim is transformed from a byte string of the cti to its equivalent string-based representation. The decoded jti value will be encoded with base64URL without padding. 

Semantic compact profile

A compact credential with a semantic compact profile embeds custom claims into a standard vc property. It provides semantic context to the claims and is also compliant with the W3C Verifiable Credentials Data Model 1.0. The following is an example of a decoded payload:

json
Copy to clipboard.
1{
2  "iss": "did:web:example.nz",
3  "nbf": 1516239022,
4  "exp": 1516239922,
5  "jti": "urn:uuid:cc599d04-0d51-4f7e-8ef5-d7b5f8461c5f",
6  "vc": {
7    "@context": [ "https://www.w3.org/2018/credentials/v1" ],
8    "type": [ "VerifiableCredential"],
9    "credentialSubject": {
10      "givenName": "John Andrew",
11      "familyName": "Doe",
12      "dob": "1979-04-14"
13    }
14  }
15  "status": {
16    "url": "https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/core/v2/credentials/compact/revocation-lists/8f25e8a5-c878-411e-8141-43fb2d257137",
17    "index": 23434
18  }
19}

The value of any dynamic claims within vc.credentialSubjectMUST be either a boolean, a string or a number. However, this can be extended to support more complex values in the future.

jti claim must be a valid URI according to the W3C Verifiable Credentials Data Model 1.0. To meet these requirements the decoded form of the cti claim must be a uuid.

More specifics on the types of claims used in the credentials and how they can be applied when signing and validating them can be found in the compact credential sign and verify tutorials. 

Limitations

By their nature, Compact Credentials are not suited for situations where large payloads are required, such as embedding photographs or any set of claims that is likely to exceed 10 attributes. There are no hard limits imposed by the system (other than our general API payload limit of 1MB). However, practically speaking, any large compact credential which is issued and then embedded into a QR code will result in an overly-dense QR code that cannot be shared or read by cameras on devices. 

Compact Credentials are considered to be ‘bearer’ credentials because they do not utilize a subject identifier, and when presented offer no way to cryptographically ensure that the credential was issued to the same person as the presenter. Bearer credentials are best suited for situations where any identity-related values in the presented claims can be identified separately. For example, on a Training Course Entry Pass credential, if the Name field is included along with the event-specific fields, then the person presenting the credential would need to present their staff photo ID at the time of entry to prove their identity as the owner of the issued credential, therefore gaining access to the event. This works equally as well in situations where no identity validation is needed whatsoever, such as when using a ticket or pass to get access to public transportation.