Merge pull request #20 from mode51software/develop

Release v0.3.3

Author: mode51software

CHANGELOG.md

@@ -0,0 +1,23 @@
+## v0.3.3
+### 18/03/2021
+
+* Bugfix for key label in relation to persistent storage
+* pathSignVerbatim
+
+## v0.3.2.beta.1
+### 17/Mar/2021
+
+* Improved connection checks
+* RSA keys for Generate Root and Generate Intermediate (initially hard coded to EC)  
+* Remove hardcoded key types except for CSR gen as part of Generate Intermediate
+* Detect if in metamode on startup
+
+## v0.3.1.beta.1
+### 14/Mar/2021
+
+* Added Generate Root, Generate Intermediate and Sign Intermediate paths
+
+## v0.3.0
+### 01/Mar/2021
+
+* Initial release with support for HSM signing using an externally generated CA cert imported using Vault's Set Signed Intermediate command

Makefile

@@ -46,4 +46,25 @@ pathsetcrlconfig:
 pathfetchcrl:
 	go test -v -run TestPathFetchCRL ./pkg/hsmpki
 
+pathrevokecrl:
+	go test -v -run TestPathRevokeCRL ./pkg/hsmpki
+
+pathrotatecrl:
+	go test -v -run TestPathRotateCRL ./pkg/hsmpki
+
+pathtidycrl:
+	go test -v -run TestPathTidyCRL ./pkg/hsmpki
+
+pathgenerateroot:
+	go test -v -run TestPathGenerateRoot ./pkg/hsmpki
+
+pathgenerateintermediate:
+	go test -v -run TestPathGenerateIntermediate ./pkg/hsmpki
+
+pathissue:
+	go test -v -run TestPathIssue ./pkg/hsmpki
+
+pathdeleteroot:
+	go test -v -run TestPathDeleteRoot ./pkg/hsmpki
+
 .PHONY: build clean fmt start enable

README.md

@@ -47,53 +47,181 @@ Now open a new terminal window and login to Vault. This is an example for a dev
 
 ### Setup
 
-Enable the HSM PKI plugin:
+#### Setup Without CA Generation
 
-`vault secrets enable -path=hsmpki -options="config=conf/config-softhsm.hcl" vaultplugin-hsmpki`
+These instructions apply if the Intermediate CA has been created and signed by a Root CA externally to Vault.
 
-### Run
+##### Enable the HSM PKI plugin:
+
+`vault secrets enable -path=hsmpki_inter -options="config=conf/config-softhsm.hcl" vaultplugin-hsmpki`
+
+#### Setup With CA Generation
+
+These instructions apply if the Root and Intermediate CAs need to be created and signed by Vault.
+
+##### Enable the HSM PKI plugin paths:
+
+* Different configuration files can be passed to each instance of the plugin. 
+* These may contain alternative HSM slot and PIN settings.
+* If no key label is specified then one will be automatically generated and stored within Vault.
+* The automatically generated key label is provided in the response to the Generate Root and Generate Intermediate commands.
+
+Root CA path:
+`vault secrets enable -path=hsmpki_root -options="config=conf/config-safenet.hcl" vaultplugin-hsmpki`
+
+Intermediate CA path:
+`vault secrets enable -path=hsmpki_inter -options="config=conf/config-safenet.hcl" vaultplugin-hsmpki`
+
+### Run Create CA certs and Issue
+
+In this sequence of steps Vault:
+
+* generates a Root CA cert using the hsmpki_root path
+* generate an Intermediate CA and CSR using the hsmpki_inter path
+* signs the Intermediate CA's CSR producing the cert using the hsmpki_root path
+* sets the signed Intermediate CA using the hsmpki_inter path
+* creates a role  
+* issues a new private key and a new cert signed by the Intermediate CA using the hsmpki_path    
+
+#### Generate Root CA
+
+Notice that key_label is returned alongside serial_number. Also note that the certificate is the same as the issuing certificate.
+
+A key label for the HSM will be generated automatically if a key_label isn't specified in the conf file.
+
+The format of the automatically generated key_label is eg. ROOTCA20210314232939
+
+`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"`
+
+Save the signed Intermediate CA to a file eg. data/root.cert.pem
+
+This CA cert can be imported into a browser for testing.
+
+#### Generate Intermediate CA and CSR
+
+The format of the automatically generated key_label is eg. INCA20210314233609
+
+`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"`
+
+Save the CSR to a file, eg. data/intermediate.csr.pem
+
+Use openssl to check the CSR:
+
+`openssl req -in ./data/intermediate.csr.pem -text`
+
+#### Sign the Intermediate CA
+
+`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"`
+
+Save the signed Intermediate CA to a file eg. data/intermediate.cert.pem
+
+This CA cert can be imported into a browser for testing.
+
+#### Set the Signed Intermediate CA
+
+If 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:
+
+`vault write hsmpki_inter/intermediate/set-signed certificate=@data/intermediate.cert.pem hash_algo="SHA-512"`
 
 #### Create a Role
 
 Create a role for the allowed domain, which configures the certificate signing template, in this case localhost:
 
-`vault write hsmpki/roles/localhost allowed_domains=localhost allow_subdomains=true ttl=24h max_ttl=72h key_type="ec" key_bits="384"`
+`vault write hsmpki_inter/roles/localhost allowed_domains=localhost allow_subdomains=true ttl=24h max_ttl=72h key_type="ec" key_bits="384"`
+
+#### Issue a New Signed Cert
+
+Ask 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:
+
+`vault write hsmpki_inter/issue/localhost common_name=localhost`
+
+
+### Run Signing Using an Externally Generated and Signed CA
 
 #### Set the Signed Intermediate CA
 
-Set the signed Intermediate certificate and use the HSM PKI extensions supporting the configuration of the HSM key alias and the preferred SHA algorithm :
+Set the signed Intermediate certificate and use the HSM PKI extensions supporting the configuration of the HSM key alias and the preferred SHA algorithm.
+
+The key label can also be configured in the conf file passed in to the secrets enable command:
+
+`vault write hsmpki_inter/intermediate/set-signed certificate=@data/safenet-inter-0016.ca.cert.pem key_label="ECTestCAInterKey0016" hash_algo="SHA-512"`
+
+#### Create a Role
+
+Create a role for the allowed domain, which configures the certificate signing template, in this case localhost:
 
-`vault write hsmpki/intermediate/set-signed certificate=@data/safenet-inter-0016.ca.cert.pem key_alias="ECTestCAInterKey0016" hash_algo="SHA-512"`
+`vault write hsmpki_inter/roles/localhost allowed_domains=localhost allow_subdomains=true ttl=24h max_ttl=72h key_type="ec" key_bits="384"`
 
 #### Sign a CSR
+
 Now that Vault is ready for signing, sign a standalone CSR file using the HSM returning the CA and the signed certificate:
 
-`vault write hsmpki/sign/localhost csr=@data/localhost512.csr.pem`
+`vault write hsmpki_inter/sign/localhost csr=@data/localhost512.csr.pem`
 
-#### Generate a Key, CSR and Sign
+#### Issue a New Cert
 
 Ask 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:
 
-`vault write hsmpki/issue/localhost common_name=localhost`
+`vault write hsmpki_inter/issue/localhost common_name=localhost`
 
 #### Revoke a Certificate
 
-`vault write hsmpki/revoke serial_number="<your serial number>"`
+`vault write hsmpki_inter/revoke serial_number="<your serial number>"`
 
 #### View Revocation Time of Certificate
 
-`vault read hsmpki/cert/<your serial number>`
+`vault read hsmpki_inter/cert/<your serial number>`
 
 #### View CRL
 
-`curl --header "X-Vault-Token: root"  http://127.0.0.1:8200/v1/hsmpki/crl/pem > data/crl.txt`
+`curl --header "X-Vault-Token: root"  http://127.0.0.1:8200/v1/hsmpki_inter/crl/pem > data/crl.txt`
 
 `openssl crl -in ./data/crl.txt -text`
 
+### Verify Certs
+
+Install nginx and setup the TLS certificate and private key for the test site, 
+referred to below as localhost.crt and localhost.key.
+
+These are the private key and the certificate generated by Vault's issue command.
+
+Separately import the Root CA and Intermediate CA into a web browser.
+
+Visit https://localhost:444/ and confirm that the TLS certificate is accepted.
+
+```
+server {
+
+listen              444 ssl http2 default_server;
+
+server_name         localhost;
+
+ssl_certificate     /etc/nginx/certs/localhost.crt;
+
+ssl_certificate_key /etc/nginx/certs/localhost.key;
+
+ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;
+
+ssl_ciphers         HIGH:!aNULL:!MD5;
+
+    location / {
+      root   /usr/share/nginx/html;
+      index  index.html index.htm;
+    }
+```
+
 ### Testing
 
 View the [TESTING](TESTING.md) README
 
+### Troubleshooting
+
+#### SafeNet DPoD [Troubleshooting](https://thalesdocs.com/dpod/services/hsmod_services/hsmod_troubleshooting/index.html)
+
+##### HSM error code 0x80001604
+
+This may indicate that the SafeNet DPoD partition is full
+
 ## License
 
 HSM 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.

TESTING.md

@@ -8,7 +8,7 @@ If you want to run tests in an IDE then source DPoD in a shell and start the IDE
 
 ## Makefile Command Line Tests
 
-Test the HSM connection where the conf is loaded in from conf/config-hsm.hcl
+Test the HSM connection where the conf is loaded in from conf/config-safenet.hcl
 
 `make test hsmconnection`
 
@@ -19,3 +19,9 @@ Test the HSM connection where the conf is loaded in from conf/config-hsm.hcl
 `make test pathfetchcrl`
 
 `make test pathsetsignedintermediate`
+
+`make test pathgenerateroot`
+
+`make test pathgenerateintermediate`
+
+`make test pathdeleteroot`

conf/config-safenet.hcl

@@ -0,0 +1,8 @@
+
+lib = "/opt/apps/safenet/dpod/current/libs/64/libCryptoki2.so"
+slot_id = 3
+pin = "1234"
+# be aware that the key_label can be overridden by dynamically providing it during Set Signed Intermediate
+#key_label = "ECTestCAInterKey0016"
+connect_timeout_s = 10
+read_timeout_s = 5

go.mod

@@ -3,16 +3,31 @@ module github.com/mode51software/vaultplugin-hsmpki
 go 1.13
 
 require (
+	github.com/armon/go-metrics v0.3.4 // indirect
 	github.com/asaskevich/govalidator v0.0.0-20180720115003-f9ffefc3facf
+	github.com/fatih/color v1.9.0 // indirect
 	github.com/fatih/structs v1.1.0
+	github.com/go-test/deep v1.0.7 // indirect
+	github.com/google/go-cmp v0.5.2 // indirect
 	github.com/hashicorp/errwrap v1.0.0
 	github.com/hashicorp/go-hclog v0.14.1
+	github.com/hashicorp/go-retryablehttp v0.6.7 // indirect
+	github.com/hashicorp/go-version v1.2.1 // indirect
 	github.com/hashicorp/hcl v1.0.1-vault
-	github.com/hashicorp/vault v1.6.2
 	github.com/hashicorp/vault/api v1.0.5-0.20201001211907-38d91b749c77
 	github.com/hashicorp/vault/sdk v0.1.14-0.20210127182440-8477cfe632c0
+	github.com/hashicorp/yamux v0.0.0-20181012175058-2f1d1f20f75d // indirect
+	github.com/kr/pretty v0.2.1 // indirect
+	github.com/miekg/pkcs11 v1.0.3
+	github.com/mitchellh/mapstructure v1.3.3 // indirect
+	github.com/mitchellh/reflectwalk v1.0.1 // indirect
+	github.com/mode51software/pkcs11helper v0.3.3
+	github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e // indirect
 	github.com/ryanuber/go-glob v1.0.0
+	github.com/stretchr/objx v0.2.0 // indirect
 	golang.org/x/crypto v0.0.0-20201002170205-7f63de1d35b0
 	golang.org/x/net v0.0.0-20200625001655-4c5254603344
-	github.com/mode51software/pkcs11helper v0.3.0
+	golang.org/x/sys v0.0.0-20200831180312-196b9ba8737a // indirect
+	golang.org/x/text v0.3.3 // indirect
+	gopkg.in/check.v1 v1.0.0-20200227125254-8fa46927fb4f // indirect
 )