piv-smartcard

A cross-platform Python library to read X.509 certificates from PIV smart cards over PC/SC (Windows, macOS and Linux).

It is a Python port of GoogleChromeLabs/web-smartcard-demo. The original is a ChromeOS-only Isolated Web App that uses the experimental Web Smart Card API to read the X.509 Card Authentication certificate from a PIV smart card. That API does not exist on Windows or macOS, so this project keeps the same architecture but talks to the native PC/SC stack through pyscard, which works on Windows, macOS and Linux.

Architecture

Reader (PC/SC)
   │  pyscard  (WinSCard on Windows, PCSC framework on macOS)
   ▼
CardSession ── transmit(CommandAPDU) ──► ResponseAPDU
   │
   ▼
piv.select() ─► piv.read_certificate() ─► BER-TLV decode ─► X.509 parse
   │
   ▼
Tkinter GUI  /  CLI

Prerequisites

• Python 3.10+
• A smart-card reader and a PIV card (e.g. a YubiKey with the PIV interface).
• Windows: the Smart Card service is built in — nothing to install.
• macOS: the PCSC framework is built in — nothing to install.
• Linux: install pcscd and libpcsclite (sudo apt install pcscd libpcsclite-dev).

Install

From PyPI (once published):

pip install piv-smartcard

From source (development):

python -m venv .venv
.venv\Scripts\Activate.ps1      # Windows
# source .venv/bin/activate     # macOS / Linux
pip install -e ".[dev]"

Use as a library

from smartcard_demo import CardSession, list_readers, select, read_certificate

reader = list_readers()[0]
with CardSession(reader) as session:
    select(session)                              # SELECT the PIV application
    info = read_certificate(session, "card_authentication")
    print(info.as_lines())
    print(info.pem)

The pure-Python parts (CommandAPDU, BER-TLV parse/find, parse_certificate, identify_card, SLOTS, ...) are importable without pyscard; the CardSession / list_readers reader symbols are loaded lazily and only require pyscard when actually used.

Run the apps

GUI:

piv-smartcard-gui        # after install
python main.py           # from a source checkout

CLI:

piv-smartcard list
piv-smartcard read
piv-smartcard read --slot authentication --pem

# or, from a source checkout without installing:
python -m smartcard_demo.cli list

PIV certificate slots

Tests

pip install pytest cryptography
pytest

The tests use canned APDU responses and a synthetic certificate, so they run without a reader or card.

Publishing

Build and check the distribution locally:

python -m pip install build twine
python -m build
python -m twine check dist/*

Releasing to PyPI is automated: create a Git tag vX.Y.Z (or publish a GitHub Release) and the Publish to PyPI workflow builds and uploads via PyPI Trusted Publishing (OIDC, no token stored). Configure the trusted publisher once on PyPI, pointing at amandeepsdet/piv-smartcard and the publish.yml workflow.

git tag v0.1.0
git push origin v0.1.0

Troubleshooting

• pyscard fails to build on install (e.g. "Microsoft Visual C++ 14.0 or greater is required"): pyscard ships prebuilt wheels only for released Python versions. On very new interpreters (e.g. Python 3.14) pip falls back to compiling from source. Either use Python 3.10–3.13 (recommended), or install the Microsoft C++ Build Tools. The apdu, ber, util and piv modules do not import pyscard, so the test suite runs even when pyscard is not installed.