proxy-pkcs11

README

pkcs11-proxy

A TLS forward proxy that enables applications to use PKCS#11 hardware tokens (e.g. smart cards, HSMs) for client certificate authentication.

📦 Prerequisites

PCSC

• Ensure pcscd>=2.3 is installed and running as a systemd service:

  pcscd -v
  

• Override the pcscd systemd service to disable Polkit and auto-exit

  sudo systemctl edit pcscd.service
  

  Add:

  [Service]
  ExecStart=
  ExecStart=/usr/sbin/pcscd --foreground --disable-polkit
  

• Reload systemd and restart pcscd

  sudo systemctl daemon-reload
  sudo systemctl restart pcscd.service
  

Go

If running on the host:

• Go>=1.25

Check version:

  go version

⚙️ Configuration

• Create a configuration file (see config.template.toml)
• Create an env file (see .env.app.template)

⚡ Build & Run

Build

go build -o proxy-pkcs11 ./cmd

Help

./proxy-pkcs11 --help

Run the app

Note: default log format is structured JSON, use --log-text to log in human readable format.

./proxy-pkcs11 --config config.toml --env .env.app

Test

Test the proxy by sending a HTTP request:

curl http://<host>:<port> -H "Host: <remote_host>"

🐳 Docker

Build

docker build -t <image_name> .

Run

docker run \
  --rm \
  --name <container_name> \
  -p <host_port>:<container_port> \
  -v /path/to/.env.app:/app/.env.app:ro \
  -v /path/to/app.conf:/app/config.toml:ro \
  -v /path/to/token/lib.so:/usr/local/lib/token/lib.so:ro \
  -v /run/pcscd/pcscd.comm:/run/pcscd/pcscd.comm \
  <image_name> \
  --config /app/config.toml \
  --env /app/.env.app

License

Distributed under MIT