{"id":28229555,"url":"https://github.com/porech/pkcs11-web-proxy","last_synced_at":"2025-06-14T04:30:48.393Z","repository":{"id":239173590,"uuid":"798760196","full_name":"porech/pkcs11-web-proxy","owner":"porech","description":"A very simple reverse proxy that listens for plain HTTP requests and sends them to an upstream server with TLS client authentication from a PCKS#11 device (like a smart card).","archived":false,"fork":false,"pushed_at":"2024-05-29T09:49:39.000Z","size":23,"stargazers_count":4,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-18T16:11:19.020Z","etag":null,"topics":["authentication","pkcs11","smart-card"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/porech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-10T12:14:21.000Z","updated_at":"2024-12-07T03:49:42.000Z","dependencies_parsed_at":"2024-05-29T11:09:53.347Z","dependency_job_id":"bdfc4f9b-e9ad-4d2e-bf5e-ae938a6add1f","html_url":"https://github.com/porech/pkcs11-web-proxy","commit_stats":null,"previous_names":["porech/pkcs11-web-proxy"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/porech/pkcs11-web-proxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/porech%2Fpkcs11-web-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/porech%2Fpkcs11-web-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/porech%2Fpkcs11-web-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/porech%2Fpkcs11-web-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/porech","download_url":"https://codeload.github.com/porech/pkcs11-web-proxy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/porech%2Fpkcs11-web-proxy/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259759711,"owners_count":22907020,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","pkcs11","smart-card"],"created_at":"2025-05-18T16:10:34.831Z","updated_at":"2025-06-14T04:30:48.386Z","avatar_url":"https://github.com/porech.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pkcs11-web-proxy\n\nA very simple reverse proxy that listens for plain HTTP requests and sends them to an upstream server with TLS client authentication from a PCKS#11 device (like a smart card).\n\n# WARNING\n\nPlease think at least twice before using it. Try to understand what it means: you are exposing a port (on your host only, by default)\nwhich can be reached over HTTP and will perform requests to your target server, via HTTPS, authenticated with the certificate on YOUR PKCS#11 device.\n\nThe certificate on a smart card may be something that can legally prove your identity, and allow someone to do (bad?) things on your behalf.\n\nNeedless to say, this poses lots of security risks.\n\nThose are some cases in which it MAY be a good idea to use it:\n\n- You are developing a client that integrates with an API that requires client authentication, and your preferred tool to play with it doesn't support PKCS#11 devices (looking bad at you, [Postman](https://github.com/postmanlabs/postman-app-support/issues/3789))\n- You're in your super-secure network with only your devices attached to it, you want to access a service from multiple PCs, but you have only one smart card\n\nIn all the other cases, it's probably a bad idea to use it.\n\n# Usage\n\nFirst of all, you should probably install OpenSC. It's not a dependency, but it brings the `pkcs11-tool` utility to get the token serial, and also a good PKCS#11 module if you don't have one from your device vendor.\n\nInstall golang and clone this repo. Build with `go build .` and run with `./pkcs11-web-proxy -help` to see the options:\n\n```\n  -listen-addr string\n    \tAddress to listen on (default \"127.0.0.1\")\n\n  -listen-port int\n    \tPort to listen on (default 8080)\n\n  -destination-url string\n    \tURL to forward requests to.\n\n  -no-preserve-host\n    \tDo not preserve the host header in the request.\n\n  -log-requests\n    \tLog each request to stdout.\n\n  -pkcs11-path string\n    \tPath to the PKCS11 module. Use the card vendor-specific one, or run 'pkcs11-tool --help' and look for '--module' default value for a good one to use.\n\n  -token-serial string\n    \tSerial number of the token. Run 'pkcs11-tool --list-token-slots' to find it.\n\n  -pin string\n    \tPIN to access the card. Cannot be used with --pin-file.\n\n  -pin-file string\n    \tFile containing the PIN to access the card (will be deleted after read!). Cannot be used with --pin.\n\n  -certificate-index int\n    \tIndex of the certificate to use. Run './pkcs11-web-proxy -token-serial ... [-pin/-pin-file] ... list-certificates' to find the index. By default, the first found certificate (index 0) will be used.\n\n  -listen-tls\n        Listen on TLS instead of plain HTTP (useful if your upstream sets 'secure' cookies)\n\n  -listen-tls-cert\n        Path to the certificate or chain file for the TLS listener (required if --listen-tls is set)\n\n  -listen-tls-key\n        Path to the private key file for the TLS listener (required if --listen-tls is set)\n```\n\nIf you have multiple certificates on the same card, you can choose the one to use with its index. To list all of the available certificates you can run:\n\n```\n./pkcs11-web-proxy -token-serial ... [-pin/-pin-file] ... list-certificates\n```\n\n# Example\n\n```\n./pkcs11-web-proxy -destination-url https://clientecho.alerinaldi.it -pin 12345 -pkcs11-path /lib/bit4id/libbit4xpki.so -token-serial 1234567898765432\n```\n\n# You should not use -pin\n\nAs you may guess, the PIN is sensitive information. If you pass it as a command line argument, it will be visible to anyone that can run `ps aux` on your machine, and in the shell history.\nYou should use the `-pin-file` option instead, which will read the PIN from a file and delete it after reading.\n\nYou might want to use a script like this:\n\n```sh\n#!/bin/bash\necho -n \"Enter PIN: \"\nread -r -s pin_val\necho \"\"\necho -n $pin_val \u003e /tmp/pin-val.txt\n./pkcs11-web-proxy -destination-url https://clientecho.alerinaldi.it -pin-file /tmp/pin-val.txt -pkcs11-path /lib/bit4id/libbit4xpki.so -token-serial 1234567898765432\n# If something went really wrong starting the proxy, delete the file anyway\nif [ -f /tmp/pin-val.txt ]; then\nrm /tmp/pin-val.txt\nfi\n```\n\n# TLS listener\n\nIt seems counterintuitive to run such a tool to listen over TLS, but sometimes an upstream server may set cookies with the \"secure\" flag, which will be ignored by the browser if the connection is not over HTTPS.\nThis may lead to issues with authentication on such services.\n\nBy using the TLS listener, you may avoid this issue: the connection to the reverse proxy will be over HTTPS, but it won't require a client certificate, that will be injected by the proxy itself when connecting to the upstream server.\n\nYou can generate a self-signed certificate and key with openssl:\n\n```\nopenssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 3650 -nodes\n```\n\nAnd then run the proxy with:\n\n```\n./pkcs11-web-proxy -destination-url https://clientecho.alerinaldi.it -pin 12345 -pkcs11-path /lib/bit4id/libbit4xpki.so -token-serial 1234567898765432 -listen-tls -listen-tls-cert cert.pem -listen-tls-key key.pem\n```\n\nYou'll need to trust your certificate on your browser or application to avoid security warnings.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fporech%2Fpkcs11-web-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fporech%2Fpkcs11-web-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fporech%2Fpkcs11-web-proxy/lists"}