Testing PKI operations

7min

This section demonstrates through several PKI operations how to create Root and intermediate CAs, which can then issue leaf certificates under them. 
Initialize Vault
Before performing the test PKI operations, perform the following steps to initialize, unseal (if required), and log in to Vault:
1
In a different terminal window from where Vault is running, run the following commands to set the VAULT_ADDR and PIN environment variables.
Shell
export VAULT_ADDR='http://127.0.0.1:8200'
export PIN='safest'
export VAULT_ADDR='http://127.0.0.1:8200'
export PIN='safest'
﻿
2
Run the following command to check the Vault status.
Shell
vault status
vault status
﻿
If the operation succeeds, the output should be similar to the following example:
Shell
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
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
﻿
3
Run the following command to initialize Vault:
Shell
vault operator init -key-shares=1 -key-threshold=1
vault operator init -key-shares=1 -key-threshold=1
﻿
We do not recommend using 1 for both the key shares and the key threshold in production.
If the operation succeeds, the output should be similar to the following example:
Shell
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.
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.
﻿
4
Optionally, if HSM auto unseal is not configured, run the following command to unseal Vault manually:
Shell
vault operator unseal <Unseal Key 1 provided from above>
vault operator unseal <Unseal Key 1 provided from above>
﻿
5
Run the following command to log in to Vault:
Shell
vault login <Initial Root Token provided from above>
vault login <Initial Root Token provided from above>
﻿
Generate managed keys on the HSM for the Root and intermediate CA
1
Run the following command to generate a managed key on the HSM for the Root CA:
The value specified in the library field in the preceding command must match the value set in the name field of the kms_library stanza in the Vault configuration file (shown in the following example): 
Shell
# Provide your Futurex HSM connection information
kms_library "pkcs11" {
  name="hsm1"
  library = "/usr/local/bin/fxpkcs11/libfxpkcs11-Debug.so"
}
# Provide your Futurex HSM connection information
kms_library "pkcs11" {
  name="hsm1"
  library = "/usr/local/bin/fxpkcs11/libfxpkcs11-Debug.so"
}
﻿
The value specified in the token_label field in the preceding command must be Futurex.
Shell
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
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
﻿
2
Run the following command to generate a managed key on the HSM for the intermediate CA:
Shell
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
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
﻿
3
Run the following command to verify that the key configurations were written to Vault:
Shell
vault list /sys/managed-keys/pkcs11
vault list /sys/managed-keys/pkcs11
﻿
4
Run the following commands to verify that the key configurations are valid by test signing some data:
Shell
vault write -f /sys/managed-keys/pkcs11/hsm-key-root/test/sign
vault write -f /sys/managed-keys/pkcs11/hsm-key-int/test/sign
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 for the Root and intermediate CA
1
Run the following command to enable the PKI secrets engine for the Root CA:
Shell
vault secrets enable -path=pki -allowed-managed-keys=hsm-key-root pki
vault secrets enable -path=pki -allowed-managed-keys=hsm-key-root pki
﻿
2
Run the following command to enable the PKI secrets engine for the Intermediate CA:
Shell
vault secrets enable -path=pki_int -allowed-managed-keys=hsm-key-int pki 
vault secrets enable -path=pki_int -allowed-managed-keys=hsm-key-int pki 
﻿
Create a Root CA certificate with the corresponding managed key that you generated and stored on the HSM
1
Run the following command to create a Root CA certificate with its corresponding managed key and output it to a file:
Shell
vault write -field=certificate pki/root/generate/kms managed_key_name=hsm-key-root common_name=example.com ttl=8760h > /tmp/CA_cert.crt
vault write -field=certificate pki/root/generate/kms managed_key_name=hsm-key-root common_name=example.com ttl=8760h > /tmp/CA_cert.crt
﻿
2
Run the following command to verify that the certificate looks correct:
Text
cat /tmp/CA_cert.crt
cat /tmp/CA_cert.crt
﻿
Create a CSR for the intermediate CA with the managed key that you generated and stored on the HSM
1
Run the following command to create an Intermediate CA certificate with its corresponding managed key and output it to a file:
The following command requires you to install the jq package on your system. This package processes JSON output.
Shell
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
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
﻿
2
Run the following command to verify that the certificate looks correct:
Shell
cat /tmp/pki_intermediate.csr
cat /tmp/pki_intermediate.csr
﻿
Sign the intermediate CA certificate with the managed Root CA
1
Run the following command to sign the intermediate CA certificate with the managed Root CA and output it to a file:
The following command requires you to install the jq package on your system. This package processes JSON output.
Shell
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
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
﻿
2
Run the following command to write the signed Intermediate CA certificate to Vault:
Shell
vault write pki_int/intermediate/set-signed certificate=@/tmp/intermediate.cert.pem
vault write pki_int/intermediate/set-signed certificate=@/tmp/intermediate.cert.pem
﻿
Issue a leaf certificate from the intermediate CA
1
Run the following command to create a new role:
Shell
vault write pki_int/roles/example-dot-com allowed_domains="example.com" allow_subdomains=true max_ttl="720h"
vault write pki_int/roles/example-dot-com allowed_domains="example.com" allow_subdomains=true max_ttl="720h"
﻿
2
Run the following command to issue a leaf certificate:
Shell
vault write -format=json pki_int/issue/example-dot-com common_name="test.example.com" ttl="24h"
vault write -format=json pki_int/issue/example-dot-com common_name="test.example.com" ttl="24h"
﻿
﻿

Updated 15 Sep 2024

Did this page help you?

Configure the Futurex PKCS #11 Library with HashiCorp Vault

Appendix: Configuring Vault to use a key manually generated on the HSM