VCB Verify

Verify Verifiable Credential Barcodes on DL/ID PDF417 barcodes.

Background

Verifiable Credential Barcodes embed digitally signed credentials inside PDF417 barcodes on government-issued drivers licenses and identification cards. This library verifies those credentials: it parses the barcode, checks the cryptographic proof, and optionally checks revocation status.

The library is jurisdiction-agnostic. Any issuer that follows the W3C VCB specification can be supported by adding an IssuerProfile. Built-in profiles are included for California DMV and the W3C Utopia test vectors. Each profile bundles DID documents for offline use, but online resolution is recommended for production to pick up key rotations. Host allowlists on each profile restrict which remote resources can be fetched during verification.

The API is synchronous. Python 3.12+.

Install

pip install vcb-verify

Development:

git clone https://github.com/subfile-llc/vcb-verify.git
cd vcb-verify
pip install -e ".[dev]"

Usage

Basic verification

from vcb_verify import verify
from vcb_verify.issuers import ca_dmv_prod_profile

scanned_data = ...  # PDF417 bytes or string from barcode scanner
result = verify(data=scanned_data, profile=ca_dmv_prod_profile())

if result.valid:
    print("Valid credential")
else:
    print(f"Invalid: {result.error}")

By default, barcodes without VCB data are returned as not-valid rather than raising an error. Pass require_vcb=True to treat missing VCB data as a verification failure, or use profile.vcb_required_after to require it based on the credential's issued date.

Check revocation status

result = verify(
    data=scanned_data,
    profile=ca_dmv_prod_profile(),
    verify_status=True,
)

This uses profile.get_fetching_loader() by default. To supply a custom fetch implementation, pass http_fetch=... to verify() or use profile.get_fetching_loader(http_fetch=...) as document_loader.

Document loaders

Verification resolves JSON-LD contexts and DID documents through a DocumentLoader callback. IssuerProfile.get_loader() provides offline (bundled) and online (HTTP) defaults. For custom fetch behaviour, use build_loader(..., http_fetch=...) or profile.get_fetching_loader(http_fetch=...).

Online mode

online=True (and verify_status=True) enables HTTP for allowlisted remote resources such as revocation status lists. Live did:web fetch happens only when no bundled document is available.

Debug output

result = verify(
    data=scanned_data,
    profile=ca_dmv_prod_profile(),
    debug=True,
)
if result.debug:
    print(result.debug["credential"])
    print(result.debug["aamva_hash"].hex())

Issuer Profiles

An IssuerProfile configures verification for a specific jurisdiction.

Built-in profiles

from vcb_verify.issuers import ca_dmv_prod_profile, ca_dmv_uat_profile, utopia_test_profile

Custom profiles

from vcb_verify import IssuerProfile

profile = IssuerProfile(
    name="my-state",
    issuer_identification_number="123456",
    vcb_subfile="ZC",
    vcb_field="ZCE",
    type_table={ ... },           # CBOR-LD compression table for this issuer
    allowed_hosts={"did.example.com"},
    static_documents={ ... },     # Bundled DID documents for offline mode
)

See the CA DMV profile for a complete example.

API

verify(data, *, profile, ...)

Returns: VerifyResult

IssuerProfile.get_loader(*, online=False)

Returns a document loader for this profile.

Contribute

pip install -e ".[dev]"
pytest
ruff check src tests

See CHANGELOG.md for release notes.

License

BSD-3-Clause © Subfile, LLC