Configure the Futurex PKCS #11 library with Vault

the vault hardware security module (hsm) auto unseal and seal wrap features require vault enterprise with the governance & policy module to configure the {{futurex}} pkcs #11 library with vault, perform the following tasks download and install vault configure vault use vault enable the seal wrap feature test the seal wrap feature enable and test the entropy augmentation feature the following sections describe how to perform these tasks download vault download precompiled vault binaries at https //releases hashicorp com/vault/ https //releases hashicorp com/vault/ to download vault enterprise binaries, follow the instructions hashicorp provides vault customers this integration requires the enterprise hsm binary, which is available for testing https //releases hashicorp com/vault/1 7 2+ent hsm/ https //releases hashicorp com/vault/1 7 2+ent hsm/ install vault perform the following steps to install vault run the following command to unzip the downloaded package and then move the vault binary to /usr/local/bin unzip vault ${vault version}+ent hsm linux amd64 zip run the following command to set the owner of the vault binary sudo chown root\ root vault run the following command to verify the vault version vault version the vault command features opt in autocompletion for flags, subcommands, and arguments (where supported) install autocompletion using the following command vault autocomplete install run the following command to enable autocompletion complete c /usr/local/bin/vault vault run the following command to configure vault to use the mlock syscall without running the process as root this operation prevents the system from swapping memory to disk sudo setcap cap ipc lock=+ep /usr/local/bin/vault run the following command to create a unique, non privileged system user to run vault sudo useradd system home /etc/vault d shell /bin/bash vault configure vault to configure vault, perform the following tasks configure systemd configure vault settings configure hsm auto unseal and entropy augmentation configure systemd systemd uses documented sane defaults ( www freedesktop org/software/systemd/man/systemd directives html http //www freedesktop org/software/systemd/man/systemd directives html ), so you need to set only non default values in the configuration file run the following command to create a vault service file at /etc/systemd/system/vault service sudo touch /etc/systemd/system/vault service add the following configuration to vault service \[unit] description="hashicorp vault a tool for managing secrets" documentation=https //www vaultproject io/docs/ requires=network online target after=network online target conditionfilenotempty=/etc/vault d/vault hcl startlimitintervalsec=60 startlimitburst=3 \[service] user=vault group=vault protectsystem=full protecthome=read only privatetmp=yes privatedevices=yes securebits=keep caps ambientcapabilities=cap ipc lock capabilities=cap ipc lock+ep capabilityboundingset=cap syslog cap ipc lock nonewprivileges=yes execstart=/usr/local/bin/vault server config=/etc/vault d/vault hcl execreload=/bin/kill signal hup $mainpid killmode=process killsignal=sigint restart=on failure restartsec=5 timeoutstopsec=30 startlimitinterval=60 startlimitintervalsec=60 startlimitburst=3 limitnofile=65536 limitmemlock=infinity \[install] wantedby=multi user target configure vault settings vault uses documented sane defaults, so you need to set only non default values in the configuration file run the following command to create /etc/vault d directory sudo mkdir parents /etc/vault d run the following command to create a vault configuration file, vault hcl sudo touch /etc/vault d/vault hcl run the following command to set the ownership of the /etc/vault d directory sudo chown recursive vault\ vault /etc/vault d run the following command to set the file permissions sudo chmod 640 /etc/vault d/vault hcl configure hsm auto unseal and entropy augmentation when you start a vault server, it normally starts in a sealed state where you must have a quorum of existing unseal keys to unseal it by integrating vault with the {{k3}} , a trusted hsm key provider can automatically unseal the vault server to integrate the vault enterprise server with a {{k3}} , the configuration file must define the pkcs11 seal stanza https //www vaultproject io/docs/configuration/seal/pkcs11 html and provide the necessary connection information, as shown in the following example example vault hcl \# provide your futurex hsm connection information seal "pkcs11" { lib = "/usr/local/bin/fxpkcs11/x64/openssl 1 1 x/libfxpkcs11 so" slot = "0" key label = "hsm demo" hmac key label = "hsm hmac demo" generate key = "true" } \# add the entropy stanza entropy "seal" { mode = "augmentation" } \# configure the storage backend for vault storage "file" { path = "/tmp/vault" } \# addresses and ports on which vault will respond to requests listener "tcp" { address = "0 0 0 0 8200" tls disable = "true" } ui = true disable mlock = true this guide sets the storage backend to the local file system ( /tmp/vault ) to make the verification step easy the example configuration defines the following in its seal stanza parameter description lib the path to the pkcs #11 library on the machine where vault enterprise is installed slot the slot number to use set this value to 0 because the fxpkcs11 config file sets the slot to 01 by default key label the label of the key to use hmac key label the label of the key to use for hmacing generate key if no existing key with the label specified by key label exists at vault initialization, vault generates a key for this integration, set the generate key parameter to true so that vault automatically creates the encryption keys that it uses for the seal wrap functionality on the {{k}} the values set for the key label and hmac key label parameters correspond with the special key label defines that youneed to set in the \<config> section of the fxpkcs11 cfg file) use vault to get started using vault, perform the following tasks start the vault server initialize vault access the vault ui start the vault server perform the following steps to start the vault server log in with the vault user run the following command to set the pkcs #11 pin to log in use the password of the user you created on the {{k}} and defined in the fxpkcs11 cfg file export vault hsm pin='safest' you can also set the pkcs #11 pin in the vault configuration file ( vault hcl ) with the pin parameter, but we do not recommend that method in a production setting as a best practice, specify the pin with the vault hsm pin environment variable, as shown here, to prevent password exposure if the config file is compromised or stored in an insecure location if you set it through the environment variable, vault obfuscates the environment variable after reading it one caveat you must reset the vault hsm pin environment variable when vault restarts run the following command to start the vault server vault server config=/etc/vault d/vault hcl if the command succeeds, expect output similar to the following example ==> vault server configuration hsm pkcs#11 version 2 20 hsm library fxpkcs11 hsm library version 4 23 hsm manufacturer id futurex hsm type pkcs11 cgo enabled go version go1 14 4 listener 1 tcp (addr "0 0 0 0 8200", cluster address "0 0 0 0 8201", max request duration "1m30s", max request size "33554432", tls "disabled") log level info mlock supported true, enabled false recovery mode false storage file version vault v1 5 0+ent hsm \==> vault server started! log data will stream in below open a new terminal window for later steps and leave this terminal running where you started the vault server initialize vault perform the following steps to initialize vault in the new terminal, run the following command to set the vault addr environment variable export vault addr='http //0 0 0 0 8200' run the following command to check the vault status vault status the output should be 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 run the following command to initialize vault vault operator init recovery shares=1 recovery threshold=1 the output should be similar to the following example recovery key 1 e22hrxufayqy0pvuy+renvpxolz0bsrjwastz64re24= initial root token s mvx8cihrfqmweim9yfnlw9e1 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 run the following command to set the vault token environment variable value to the generated initial root token value displayed in the terminal output export vault token="s mvx8cihrfqmweim9yfnlw9e1" to interact with vault, you must provide a valid token access the vault ui perform the following steps to access the vault ui go to http //localhost 8200 in a web browser copy and paste the initial root token output from the vault initialization command into the token field, and select \[ sign in ] if the login succeeds, the vault ui homepage displays enable the seal wrap feature you can enable seal wrap by using the following methods cli command web ui perform one of the methods described in the following sections method 1 cli command perform the following steps to execute the cli command method to compare seal wrapped data against unwrapped data, enable key/value v1 secrets engine at two different paths kv unwrapped and kv seal wrapped run the following command to enable k/v v1 without seal wrap at kv unwrapped vault secrets enable path=kv unwrapped kv run the following command to enable k/v v1 with seal wrap by using the seal wrap flag when you enable the kv workflow vault secrets enable path=kv seal wrapped seal wrap kv to enable seal wrap, pass the seal wrap flag when you enable a secrets engine run the following command to list the enabled secrets engines with details vault secrets list detailed if the command succeeds, the output is similar the the following example path plugin accessor seal wrap \ cubbyhole/ cubbyhole cubbyhole b36dd7e1 false identity/ identity identity b5650a96 false kv seal wrapped/ kv kv fe02767b true kv unwrapped/ kv kv 36d321c6 false notice that the seal wrap parameter value is true for kv seal wrapped/ method 2 web ui perform the following steps to execute the web ui method open a web browser and launch the vault ui (for example, http //127 0 0 1 8200/ui ) and then log in select enable new engine select kv from the list, and then select \[ next ] enter kv unwrapped in the path field and select version 1 for kv version return to the secrets engines page and select \[ enable engine ] select kv from the list, and then select \[ next ] enter kv seal wrapped in the path field select version 1 for kv version select \[ method options ] to expand, and select the check box for seal wrap select \[ enable engine ] test the seal wrap feature you can test seal wrap and view encrypted secrets by using one of the following methods cli command web ui perform one of the methods described in the following sections method 1 cli command perform the following steps to execute the cli command method run the following command to write a secret at kv unwrapped/unwrapped for testing vault kv put kv unwrapped/unwrapped password="my long password" run the following command to read the path to verify vault kv get kv unwrapped/unwrapped if the command succeeds, the output is similar the the following example ====== data ====== key value \ password my long password run the following command to write the same secret at kv seal wrapped/wrapped for testing vault kv put kv seal wrapped/wrapped password="my long password" run the following command to read the path to verify vault kv get kv seal wrapped/wrapped if the command succeeds, the output is similar the the following example ====== data ====== key value \ password my long password use a valid token to write and read secrets the same way, regardless of the seal wrap view the encrypted secrets remember that you configured the vault server to use the local file system ( /tmp/vault ) as its storage backend, as shown in the following example \# configure the storage backend for vault storage "file" { path = "/tmp/vault" } perform the following steps to view the encrypted secrets ssh into the machine where the vault server is running, and check the stored values in the /tmp/vault directory cd /tmp/vault/logical the /tmp/vault/logical directory has two sub directories one maps to kv unwrapped/ and another maps to kv seal wrapped/ although you cannot tell by the folder names view the secret at rest one of the directories maps to kv unwrapped/unwrapped example of viewing encrypted secrets the following example demonstrates viewing encrypted secrets go the first directory cd 2da357cd 55f2 7eed c46e c477b70bed18 run the following command to view its content the password value is encrypted cat unwrapped {"value" "aaaaaqick547prhuhmibxlq2lx8zkmpsb3p+gkhawumhkrzgseqsfevms6yoqtvlbvpu9b4zwpz2ha senz3ymw=="} go to the other directory that maps to kv seal wrapped/wrapped then, run the following command to view its content the password value is encrypted cat wrapped {"value" "clbag9on7zbbadbzcsildaygkl7sope7vba5+adaduyzo8guhzhb9ufn2nf1h0opkegcikg3jnhcxt tzqci6szcunbgf3pwhwgwb4frem3b5criqyk7239q92grgrcbbezd6ghogetsbdmzjbahk7n4liyf3x4ibqmwzgh vo4lzwur7rzncgasofciiheneegghoc21fzgvtbyinahntx2htywnfzgvtb3m="} secrets are encrypted, but the seal wrapped value is significantly longer even though both values are the same my long password method 2 web ui perform the following steps to execute the web ui method select kv unwrapped and select \[ create secret ] enter unwrapped in the path for this secret field use password in the secret key field and my longpassword in the value field select \[ save ] repeat the same step for kv seal wrapped to write the same secret at the kv seal wrapped/wrapped path select \[ save ] you can write and read secrets the same way regardless of the seal wrap by using a valid token view the encrypted secrets remember that you configured the vault server to use the local file system ( /tmp/vault ) as its storage backend, as shown in the following example \# configure the storage backend for vault storage "file" { path = "/tmp/vault" } ssh into the machine where the vault server is running, and check the stored values in the /tmp/vault directory cd /tmp/vault/logical the /tmp/vault/logical directory has two sub directories one maps to kv unwrapped/ and another maps to kv seal wrapped/ although you cannot tell by the folder names view the secret at rest one of the directories maps to kv unwrapped/unwrapped example of viewing encrypted secrets the following example demonstrates viewing encrypted secrets go to the first directory cd 2da357cd 55f2 7eed c46e c477b70bed18 run the following command to view its content the password value is encrypted cat unwrapped {"value" "aaaaaqick547prhuhmibxlq2lx8zkmpsb3p+gkhawumhkrzgseqsfevms6yoqtvlbvpu9b4zwpz2ha senz3ymw=="} another directory maps to kv seal wrapped/wrapped cd /5bcea44d 28a3 87af 393b c6d398fe41d8 run the following command to view its content the password value is encrypted cat wrapped {"value" "clbag9on7zbbadbzcsildaygkl7sope7vba5+adaduyzo8guhzhb9ufn2nf1h0opkegcikg3jnhcxt tzqci6szcunbgf3pwhwgwb4frem3b5criqyk7239q92grgrcbbezd6ghogetsbdmzjbahk7n4liyf3x4ibqmwzgh vo4lzwur7rzncgasofciiheneegghoc21fzgvtbyinahntx2htywnfzgvtb3m="} secrets are encrypted, but the seal wrapped value is significantly longer even though both values are the same my long password enable and test the entropy augmentation feature to leverage an external entropy source, you must set the external entropy access parameter to true when you enable a secrets engine or auth method perform the following steps to enable the kmes as the external entropy source on a transit secrets engine you must enable the entropy augmentation feature through the cli because we do not support using the web ui at this time run the following command to enable the transit secrets engine with an external entropy source by using the external entropy access flag vault secrets enable external entropy access transit run the following command to list the enabled secrets engine with detailed flag vault secrets list detailed example output path plugin accessor external entropy access \ cubbyhole/ cubbyhole cubbyhole a4084622 false identity/ identity identity b5738cb7 false sys/ system system a8b3552e false transit/ transit transit 88cd3066 true notice that the external entropy access is set to true for transit/ you can start using the transit secrets engine to encrypt your sensitive data which leverages the kmes as its external entropy source regardless, the user experience remains the same as before example workflow the following example demonstrates the workflow run the following command to create a new encryption key named orders vault write f transit/keys/orders run the following command to send a base64 encoded string for vault to encrypt vault write transit/encrypt/orders plaintext=$(base64 <<< "4111 1111 1111 1111") key value \ ciphertext vault\ v1\ ay3zf2bwgfwz9djlsztcldppuhkfl/kwaqeritvkgn74bgyymi+n34w1cmo8aeg= run the following command to test and verify that you can decrypt the string vault write transit/decrypt/orders \\ ciphertext="vault\ v1\ ay3zf2bwgfwz9djlsztcldppuhkfl/kwaqeritvkgn74bgyymi+n34w1cmo8aeg=" run the following command to decode to get the original data base64 decode <<< y3jlzgl0lwnhcmqtbnvtymvycg== credit card number when you enable the external entropy access, you must set the connectivity to the {{k}} if the {{k}} becomes unreachable for any reason, the transit secrets engine fails to generate new keys or rotate the existing keys, displaying an error similar to the following example error writing data to transit/encrypt/orders error making api request url put http //127 0 0 1 8200/v1/transit/encrypt/orders code 400 errors error performing token check failed to read entry error initializing session for decryption error logging in to hsm pkcs11 0xe0 ckr token not present