Documentation Index Fetch the complete documentation index at: https://docs.futurex.com/llms.txt
Use this file to discover all available pages before exploring further.
Perform the following tasks to initialize the vault and then test the PKI operations:
Initialize Vault.
Generate managed keys on the CryptoHub for the Root and Intermediate CA.
Enable the PKI secrets engine for the Root and Intermediate CA.
Create a Root CA certificate from the managed key generated on the CryptoHub.
Create a CSR for the Intermediate CA from the managed key generated on the CryptoHub.
Use the managed Root CA to issue the Intermediate CA certificate from a CSR.
Issue a leaf certificate from the managed Intermediate CA.
Initialize Vault Before performing PKI operations, you must initialize, unseal (if required), and log in to Vault.
In a different terminal window from where Vault is running, set the VAULT_ADDR and PIN environment variables. $ export VAULT_ADDR='http://127.0.0.1:8200' $ export PIN='identity_password'
Set the PIN value to the CryptoHub identity password configured inside the <CRYPTO-OPR-PASS> tag in the fxpkcs11.cfg file.
Check the Vault status. The output should look similar to the following example: Key Value --- ----- Recovery Seal Type pkcs11 Initialized false Sealed true Total Recovery Shares 0 Threshold 0 Unseal Progress 0/0 Unseal Nonce n/a Version n/a HA Enabled false
Initialize Vault. We do not recommend using 1 for both the key shares and the key threshold in production.
$ vault operator init -key-shares=1 -key-threshold=1
The output should look similar to the following example: Unseal Key 1: qK4pHBY46Zxg2nt/cMgeLGh01Kh9SQ1ChOIDHPe/kmg= Initial Root Token: hvs.iYjhzPiwz00bpqX6rmzSe7yj Success! Vault is initialized Recovery key initialized with 1 key shares and a key threshold of 1. Please securely distribute the key shares printed above.
If you did not configure HSM auto-unseal, you must unseal Vault manually: $ vault operator unseal < Unseal Key 1 provided from abov e >
Log in to Vault. $ vault login < Initial Root Token provided from abov e >
Generate managed keys Perform the following steps to generate managed keys on the CryptoHub for the Root and Intermediate CA:
Generate a managed key on the CryptoHub for the Root CA. $ vault write /sys/managed-keys/pkcs11/hsm-key-root library=hsm1 token_label=Futurex pin= $PIN key_label="hsm-key-root" allow_generate_key= true allow_store_key= true mechanism= 0x0001 key_bits= 2048 any_mount= false
You must always set the value specified in the token_label field to Futurex.
The value specified in the library field must match the value set in the name field of the kms_library stanza in the following Vault configuration file.
# Provide your Futurex HSM connection information kms_library "pkcs11" { name="hsm1" library = "/usr/local/bin/fxpkcs11/libfxpkcs11-Debug.so" }
Generate a managed key on the CryptoHub for the Intermediate CA. $ vault write /sys/managed-keys/pkcs11/hsm-key-int library=hsm1 token_label=Futurex pin= $PIN key_label="hsm-key-int" allow_generate_key= true allow_store_key= true mechanism= 0x0001 key_bits= 2048 any_mount= false
Verify that the key configuration has been written to Vault. $ vault list /sys/managed-keys/pkcs11
Verify that the key configurations are valid by test-signing some data. $ vault write -f /sys/managed-keys/pkcs11/hsm-key-root/test/sign $ vault write -f /sys/managed-keys/pkcs11/hsm-key-int/test/sign
Enable the PKI secrets engine Perform the following steps to enable the PKI secrets engine for the Root and Intermediate CA:
Enable the PKI secrets engine for the Root CA. $ vault secrets enable -path=pki -allowed-managed-keys=hsm-key-root pki
Enable the PKI secrets engine for the Intermediate CA. $ vault secrets enable -path=pki_int -allowed-managed-keys=hsm-key-int pki
Create a Root certificate Perform the following steps to create a Root CA certificate from the managed key generated on the CryptoHub:
Create a Root CA certificate with its corresponding managed key and output it to a file. $ vault write -field=certificate pki/root/generate/kms managed_key_name=hsm-key-root common_name=example.com ttl=8760h > /tmp/CA_cert.crt
Verify the certificate looks correct. Create a CSR Perform the following steps to create a Certificate Signing Request (CSR) for the Intermediate CA from the managed key generated on the CryptoHub:
Create a CSR for the Intermediate CA with its corresponding managed key and output it to a file. The following command requires installing the jq package, which processes JSON output, on your system.
$ vault write -format=json pki_int/intermediate/generate/kms managed_key_name=hsm-key-int common_name="example.com" | jq -r '.data.csr' > /tmp/pki_intermediate.csr
Verify the CSR looks correct. $ cat /tmp/pki_intermediate.csr
Use the Root CA to issue the certificate Perform the following steps to use the managed Root CA to issue the Intermediate CA certificate from a CSR:
Issue the Intermediate CA certificate from the CSR by using the managed Root CA and output it to a file. The following command requires installing the jq package, which processes JSON output, on your system.
$ vault write -format=json pki/root/sign-intermediate csr=@/tmp/pki_intermediate.csr format=pem_bundle ttl="43800h" | jq -r '.data.certificate' > /tmp/intermediate.cert.pem
Write the signed Intermediate CA certificate to Vault. $ vault write pki_int/intermediate/set-signed certificate=@/tmp/intermediate.cert.pem
Issue a leaf certificate Perform the following steps to issue a leaf certificate from the managed Intermediate CA:
Create a new role. $ vault write pki_int/roles/example-dot-com allowed_domains="example.com" allow_subdomains= true max_ttl="720h"
Issue a leaf certificate. $ vault write -format=json pki_int/issue/example-dot-com common_name="test.example.com" ttl="24h"
