{"id":37180717,"url":"https://github.com/mode51software/vaultplugin-hsmpki","last_synced_at":"2026-01-14T21:00:19.371Z","repository":{"id":40559798,"uuid":"343254738","full_name":"mode51software/vaultplugin-hsmpki","owner":"mode51software","description":"The Vault HSM PKI plugin overlays the modifications to the builtin PKI plugin that enable support for certificate signing using a Hardware Security Module via PKCS#11.","archived":false,"fork":false,"pushed_at":"2022-05-02T16:47:42.000Z","size":223,"stargazers_count":19,"open_issues_count":3,"forks_count":6,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-06-19T02:11:10.172Z","etag":null,"topics":["hardware-security-module","hsm","pki","vault-plugin","vault-plugins"],"latest_commit_sha":null,"homepage":"https://www.vaultproject.io/docs/plugin-portal","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mode51software.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-03-01T01:17:44.000Z","updated_at":"2024-03-26T19:22:39.000Z","dependencies_parsed_at":"2022-08-09T23:10:26.711Z","dependency_job_id":null,"html_url":"https://github.com/mode51software/vaultplugin-hsmpki","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/mode51software/vaultplugin-hsmpki","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mode51software%2Fvaultplugin-hsmpki","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mode51software%2Fvaultplugin-hsmpki/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mode51software%2Fvaultplugin-hsmpki/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mode51software%2Fvaultplugin-hsmpki/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mode51software","download_url":"https://codeload.github.com/mode51software/vaultplugin-hsmpki/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mode51software%2Fvaultplugin-hsmpki/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28434516,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T18:57:19.464Z","status":"ssl_error","status_checked_at":"2026-01-14T18:52:48.501Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["hardware-security-module","hsm","pki","vault-plugin","vault-plugins"],"created_at":"2026-01-14T21:00:18.369Z","updated_at":"2026-01-14T21:00:19.310Z","avatar_url":"https://github.com/mode51software.png","language":"Go","readme":"# Vault HSM PKI Plugin\n\nThe Vault HSM PKI plugin overlays the modifications to the builtin PKI plugin that enable support for certificate signing using a Hardware Security Module via [PKCS#11](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html).\n\n## Software Design\n\n### Reuse of builtin PKI\n\nThe [builtin PKI](https://github.com/hashicorp/vault/tree/v1.6.3/builtin/logical/pki) has a [specified API](https://www.vaultproject.io/api-docs/secret/pki) in terms of usage which new plugins can conform to, but the code is not expressed as a reusable module. \n\nAs this HSM plugin seeks to retain the majority of existing functionality without modification, eg. roles, the builtin PKI code is included in the [pkg/pki](./pkg/pki) directory with the addition of the pki_api.go file that makes select functions externally accessible. The rest of the included PKI code is included verbatim in the pkg/pki directory.\n\nThe HSM PKI plugin can therefore selectively override some of the PKI paths whilst using some unchanged paths.\n\n## Usage\n\n### Dependencies\n\n[Go](https://golang.org/doc/install)\n\n[Vault](https://www.vaultproject.io/downloads)\n\n### Setup HSMs\n\nThe [pkcs11helper module](https://github.com/mode51software/pkcs11helper) provides [detailed setup instructions](https://github.com/mode51software/pkcs11helper/blob/master/SETUP.md) for SoftHSM, Thales's SafeNet and Entrust's nShield.\n\n### Configure\n\nPlease prepare the [HSM configuration file in the conf/ directory](https://github.com/mode51software/vaultplugin-hsmpki/blob/master/conf/config-safenet.hcl).\n\nThe path to the PKCS#11 client library is specified in this configuration file along with the Slot ID and PIN.\n\nOmit the key_label parameter to randomly generate a new key label.\n\nIf you have installed and configured SafeNet DPoD set the environment first for the shell:\n\n```\ncd /opt/safenet/dpod/current\n. ./setenv\ncd \u003cthis git repo download directory\u003e\n\n```\n\n### Build\n\nNote that the following env var may be needed:\n\nexport GOSUMDB=off\n\nThe following command will build the plugin binary and start the Vault server as an in memory dev instance:\n\n```\nmake\n```\n\nVisit [INSTALL.md](INSTALL.md) for the persistent plugin installation instructions and registration details.\n\n### Login \n\nNow open a new terminal window and login to Vault. This is an example for a dev instance:\n\n`export VAULT_ADDR='http://127.0.0.1:8200'`\n\n`vault login root`\n\n### Setup\n\n#### Setup Without CA Generation\n\nThese instructions apply if the Intermediate CA has been created and signed by a Root CA externally to Vault.\n\n##### Enable the HSM PKI plugin:\n\n`vault secrets enable -path=hsmpki_inter -options=\"config=conf/config-softhsm.hcl\" vaultplugin-hsmpki`\n\n#### Setup With CA Generation\n\nThese instructions apply if the Root and Intermediate CAs need to be created and signed by Vault.\n\n##### Enable the HSM PKI plugin paths:\n\n* Different configuration files can be passed to each instance of the plugin. \n* These may contain alternative HSM slot and PIN settings.\n* If no key label is specified then one will be automatically generated and stored within Vault.\n* The automatically generated key label is provided in the response to the Generate Root and Generate Intermediate commands.\n\nRoot CA path:\n`vault secrets enable -path=hsmpki_root -options=\"config=conf/config-safenet.hcl\" vaultplugin-hsmpki`\n\nIntermediate CA path:\n`vault secrets enable -path=hsmpki_inter -options=\"config=conf/config-safenet.hcl\" vaultplugin-hsmpki`\n\n### Run Create CA certs and Issue\n\nIn this sequence of steps Vault:\n\n* generates a Root CA cert using the hsmpki_root path\n* generate an Intermediate CA and CSR using the hsmpki_inter path\n* signs the Intermediate CA's CSR producing the cert using the hsmpki_root path\n* sets the signed Intermediate CA using the hsmpki_inter path\n* creates a role  \n* issues a new private key and a new cert signed by the Intermediate CA using the hsmpki_path    \n\n#### Generate Root CA\n\nNotice that key_label is returned alongside serial_number. Also note that the certificate is the same as the issuing certificate.\n\nA key label for the HSM will be generated automatically if a key_label isn't specified in the conf file.\n\nThe format of the automatically generated key_label is eg. ROOTCA20210314232939\n\n`vault write hsmpki_root/root/generate/internal common_name=safenet.ec.ca.mode51.software key_type=ec key_bits=521 permitted_dns_domains=localhost organization=\"mode51 Software Ltd\" ou=\"Software\" country=\"GB\" locality=\"Cambridge\" province=\"Cambridgeshire\" street_address=\"1 A Street\" postal_code=\"CB1\"`\n\nSave the signed Intermediate CA to a file eg. data/root.cert.pem\n\nThis CA cert can be imported into a browser for testing.\n\n#### Generate Intermediate CA and CSR\n\nThe format of the automatically generated key_label is eg. INCA20210314233609\n\n`vault write hsmpki_inter/intermediate/generate/internal common_name=safenet.ec.interca.mode51.software key_type=ec key_bits=384 permitted_dns_domains=localhost organization=\"mode51 Software Ltd\" ou=\"Software\" country=\"GB\" locality=\"Cambridge\" province=\"Cambridgeshire\" street_address=\"1 A Street\" postal_code=\"CB1\"`\n\nSave the CSR to a file, eg. data/intermediate.csr.pem\n\nUse openssl to check the CSR:\n\n`openssl req -in ./data/intermediate.csr.pem -text`\n\n#### Sign the Intermediate CA\n\n`vault write hsmpki_root/root/sign-intermediate csr=@data/intermediate.csr.pem common_name=safenet.ec.interca.mode51.software key_type=ec key_bits=384 permitted_dns_domains=localhost organization=\"mode51 Software Ltd\" ou=\"Software\" country=\"GB\" locality=\"Cambridge\" province=\"Cambridgeshire\" street_address=\"1 A Street\" postal_code=\"CB1\"`\n\nSave the signed Intermediate CA to a file eg. data/intermediate.cert.pem\n\nThis CA cert can be imported into a browser for testing.\n\n#### Set the Signed Intermediate CA\n\nIf the key label has been automatically generated as part of the Generate Intermediate command then it doesn't need to be specified here or in the conf file:\n\n`vault write hsmpki_inter/intermediate/set-signed certificate=@data/intermediate.cert.pem hash_algo=\"SHA-512\"`\n\n#### Create a Role\n\nCreate a role for the allowed domain, which configures the certificate signing template, in this case localhost:\n\n`vault write hsmpki_inter/roles/localhost allowed_domains=localhost allow_subdomains=true ttl=24h max_ttl=72h key_type=\"ec\" key_bits=\"384\"`\n\n#### Issue a New Signed Cert\n\nAsk Vault to create a new key pair, generate a CSR and sign it using the HSM, returning both the private key, the CA and the signed certificate:\n\n`vault write hsmpki_inter/issue/localhost common_name=localhost`\n\n\n### Run Signing Using an Externally Generated and Signed CA\n\n#### Set the Signed Intermediate CA\n\nSet the signed Intermediate certificate and use the HSM PKI extensions supporting the configuration of the HSM key alias and the preferred SHA algorithm.\n\nThe key label can also be configured in the conf file passed in to the secrets enable command:\n\n`vault write hsmpki_inter/intermediate/set-signed certificate=@data/safenet-inter-0016.ca.cert.pem key_label=\"ECTestCAInterKey0016\" hash_algo=\"SHA-512\"`\n\n#### Create a Role\n\nCreate a role for the allowed domain, which configures the certificate signing template, in this case localhost:\n\n`vault write hsmpki_inter/roles/localhost allowed_domains=localhost allow_subdomains=true ttl=24h max_ttl=72h key_type=\"ec\" key_bits=\"384\"`\n\n#### Sign a CSR\n\nNow that Vault is ready for signing, sign a standalone CSR file using the HSM returning the CA and the signed certificate:\n\n`vault write hsmpki_inter/sign/localhost csr=@data/localhost512.csr.pem`\n\n#### Issue a New Cert\n\nAsk Vault to create a new key pair, generate a CSR and sign it using the HSM, returning both the private key, the CA and the signed certificate:\n\n`vault write hsmpki_inter/issue/localhost common_name=localhost`\n\n#### Revoke a Certificate\n\n`vault write hsmpki_inter/revoke serial_number=\"\u003cyour serial number\u003e\"`\n\n#### View Revocation Time of Certificate\n\n`vault read hsmpki_inter/cert/\u003cyour serial number\u003e`\n\n#### View CRL\n\n`curl --header \"X-Vault-Token: root\"  http://127.0.0.1:8200/v1/hsmpki_inter/crl/pem \u003e data/crl.txt`\n\n`openssl crl -in ./data/crl.txt -text`\n\n### Verify Certs\n\nInstall nginx and setup the TLS certificate and private key for the test site, \nreferred to below as localhost.crt and localhost.key.\n\nThese are the private key and the certificate generated by Vault's issue command.\n\nSeparately import the Root CA and Intermediate CA into a web browser.\n\nVisit https://localhost:444/ and confirm that the TLS certificate is accepted.\n\n```\nserver {\n\nlisten              444 ssl http2 default_server;\n\nserver_name         localhost;\n\nssl_certificate     /etc/nginx/certs/localhost.crt;\n\nssl_certificate_key /etc/nginx/certs/localhost.key;\n\nssl_protocols       TLSv1 TLSv1.1 TLSv1.2;\n\nssl_ciphers         HIGH:!aNULL:!MD5;\n\n    location / {\n      root   /usr/share/nginx/html;\n      index  index.html index.htm;\n    }\n```\n\n### Testing\n\nView the [TESTING](TESTING.md) README\n\n### Troubleshooting\n\n#### Vault\n\n* api_addr must be configured in [Vault's server configuration file](https://www.vaultproject.io/docs/configuration#api_addr) otherwise plugins don't work properly.\n\n\n#### SafeNet DPoD [Troubleshooting](https://thalesdocs.com/dpod/services/hsmod_services/hsmod_troubleshooting/index.html)\n\n##### Environment\n\nThe setenv script sets the following environment var. Please use the path to the root of your dpod files:\n\n```\ndeclare -x ChrystokiConfigurationPath=\"/opt/safenet/dpod/current\"\n```\n\nThis can be set in the service section of the systemd configuration file:\n\n```\nEnvironment=\"ChrystokiConfigurationPath=/opt/safenet/dpod/current\"\n```\n\n##### HSM error code 0x80001604\n\n* This may indicate that the SafeNet DPoD partition is full\n\n## License\n\nHSM PKI for Vault was sponsored by [BT UK](https://www.globalservices.bt.com/en/aboutus/our-services/security), developed by [mode51 Software](https://mode51.software), and contributed to the [HashiCorp community](https://www.vaultproject.io/docs/plugin-portal) under the Mozilla Public License v2.\n\nBy [Chris Newman](https://mode51.software)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmode51software%2Fvaultplugin-hsmpki","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmode51software%2Fvaultplugin-hsmpki","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmode51software%2Fvaultplugin-hsmpki/lists"}