Skip to main content

VC Barcodes

Learn how to verify VC barcodes.

Procivis One supports the verification of physical barcodes using the Verifiable Credential Barcodes v0.7 specification.

Verifiable Credentials Barcodes​

The specification enhances the barcodes found on certain physical credentials, essentially adding a verifiable credential to the printed credential. It provides mechanisms for two credentials to be enhanced with verifiable credentials:

  • Employer Authorization with a machine-readable zone (MRZ) (implemented)
  • Driver's License with a PDF417 barcode (in development)

How it works​

  • A VC is created to express some basic information about a barcode (for example, context, issuer metadata, proof).
  • This VC is compressed using CBOR-LD.
  • This compressed VC is small enough to be printed as a barcode.

For PDF417s, the VC is incorporated into a new version of the barcode; the VC is effectively appended onto the barcode. For MRZs, the VC is printed as a QR code and verifiers scan both the QR code and the MRZ.

Typically when a proof is created for a VC, only the credential is signed. But VC barcodes incorporate material from the barcode into the signature. By doing so, the VC is bound to the printed barcode. This secures tamper-resistance; if the printed barcode has been tampered with, the signature will not be verified.

Verifying VC barcodes with Procivis One​

Some elements must be configured before VC barcodes can be verified.

Configuration​

The credential format provider must be configured with type PHYSICAL_CARD:

format:
  PHYSICAL_CARD:
    type: 'PHYSICAL_CARD'

The exchange protocol provider must be configured with type SCAN_TO_VERIFY:

exchange:
  SCAN_TO_VERIFY:
    type: 'SCAN_TO_VERIFY'

Credential schema​

Due to the unique structure of the credentials in the specification, the required credential and proof schemas must be built precisely. Additionally, any given organization can only have one Employer Authorization (MRZ) credential schema and one Driver's License (PDF417) credential schema, and the corresponding proof schemas can contain no other credentials.

Employer Authorization Document​

The credential schema for the Employer Authorization Document with MRZ must follow the pattern below. Fields which can differ are noted.

{
  "claims": [
    // All fields in `claims` must match precisely, including keys and datatype
    {
      "array": false,
      "claims": [],
      "datatype": "STRING",
      "key": "Issuing Country",
      "required": true
    },
    {
      "array": true,
      "claims": [],
      "datatype": "STRING",
      "key": "Surname(s)",
      "required": true
    },
    {
      "array": true,
      "claims": [],
      "datatype": "STRING",
      "key": "Given Name(s)",
      "required": true
    },
    {
      "array": false,
      "claims": [],
      "datatype": "STRING",
      "key": "Document number",
      "required": true
    },
    {
      "array": false,
      "claims": [],
      "datatype": "STRING",
      "key": "Nationality",
      "required": true
    },
    {
      "array": false,
      "claims": [],
      "datatype": "DATE",
      "key": "Date of Birth",
      "required": true
    },
    {
      "array": false,
      "claims": [],
      "datatype": "STRING",
      "key": "Gender",
      "required": true
    },
    {
      "array": false,
      "claims": [],
      "datatype": "DATE",
      "key": "Date of Expiry",
      "required": true
    }
  ],
  "format": "PHYSICAL_CARD", // Required
  "layoutType": "CARD", // Required
  "name": "Employer Authorization Document", // Anything accepted here
  "revocationMethod": "NONE", // Verification will check revocation status regardless of the value here
  "schemaId": "UtopiaEmploymentDocument", // Required
  "walletStorageType": "SOFTWARE" // Can be any value or null as there is no digital wallet involved
}

Proof schema​

The proof schema must include only the single credential schema with all attributes required.

Proof request​

The proof request flow for verifying physical credentials differs from other proof request flows.

scanToVerify​

In addition to passing the usual information expected when creating proof requests (for example, proofSchemaId, verifierDID, verifierKey), the scanToVerify object must be passed as well. This object contains all the information from the scanned physical credential. This means the physical credential is scanned before the POST Proof Request endpoint (or Create Proof Request in the SDK) is called.

"scanToVerify": {
    "barcode": "string", // barcode as string
    "barcodeType": "MRZ", // MRZ or PDF417
    "credential": "string" // credential as string
}

For MRZ, the credential is contained in a QR code on the front of the card while the barcode is contained in the MRZ on the back of the card. For PDF417, the barcode returns all data together. In both cases, the credential data must be extracted, then decompressed with CBOR-LD and the result must then be converted to JSON and passed for credential as string.

See the MRZ example and the PDF417 example from the specification for details on decoding and decompressing.

Verification​

When verifying a physical credential via the scanToVerify object, there is no need to create a share endpoint URL for requesting a proof; the proof ID can be used to directly check the results of verification.