Configure the Futurex PKCS #11 Library with HashiCorp Vault

the vault hsm auto unseal and seal wrap features require vault enterprise with the governance and policy module to configure the {{futurex}} pkcs #11 library for use with hashicorp vault, perform the following tasks download vault install vault configure systemd configure vault settings start the vault server enable and test the seal wrap feature enable and test the entropy augmentation feature 1 | download vault download precompiled vault binaries at https //releases hashicorp com/vault/ you can download vault enterprise binaries by following the instructions made available to hashicorp vault customers this integration requires the enterprise hsm binary you can use this for testing and find it at the following link https //releases hashicorp com/vault/1 7 2+ent hsm/ 2 | install vault unzip the downloaded package and move the vault binary to /usr/local/bin/ unzip vault ${vault version}+ent hsm linux amd64 zip set the owner of the vault binary sudo chown root\ root vault check that vault is available on the system path sudo mv vault /usr/local/bin/ verify the vault version vault version enable autocompletion flags, subcommands, and arguments (where supported) vault autocomplete install enable autocompletion complete c /usr/local/bin/vault vault give vault the ability to use the mlock syscall without running the process as root the mlock syscall prevents the system from swapping memory to disk sudo setcap cap ipc lock=+ep /usr/local/bin/vault create a unique, non privileged system user to run vault sudo useradd system home /etc/vault d shell /bin/bash vault 3 | configure systemd systemd uses documented sane defaults , so you need to set only non default values in the configuration file create a vault service file at /etc/systemd/system/vault service sudo touch /etc/systemd/system/vault service add the following configuration to the vault service file \[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 4 | configure vault settings this section shows you how to perform the following tasks configure vault configure auto unseal and entropy augementation configure vault vault uses documented sane defaults so you need to set only non default values in the configuration file create /etc/vault d directory sudo mkdir parents /etc/vault d create a vault configuration file, vault hcl sudo touch /etc/vault d/vault hcl set the ownership of the /etc/vault d directory sudo chown recursive vault\ vault /etc/vault d 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 need a quorum of existing unseal keys to unseal it by integrating vault with an hsm, you can set the vault server to be automatically unsealed by the trusted hsm key provider to integrate the vault enterprise server with an hsm cluster, the configuration file must define the pkcs11 seal stanza providing necessary connection information, as shown in the following example example vault hcl 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 path to the pkcs #11 library on the machine where vault enterprise is installed slot the slot number to use (this should be set to 0 because that is the default slot in the fxpkcs11 config file) key label defines the label of the key to use hmac key label defines 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 time, vault generates a key for this integration, the generate key parameter needs to be set to true so that vault automatically creates the encryption keys that it uses for the seal wrap functionality on the hsm the values set for the key label and hmac key label parameters correspond with the special key label defines that must be set in the \<config> section of the fxpkcs11 cfg file for the full list of configuration parameters, prefer to the vault documentation here 5 | start the vault server this section shows you haw to perform the following tasks start vault initialize vault access the vault ui start vault log in with the vault user set the pkcs #11 pin for log in with the following command for the value of vault hsm pin , use the password of the identity created on the hsm and defined in the fxpkcs11 config file export vault hsm pin='safest' you can also set the pkcs #11 pin can in the vault configuration file ( vault hcl ) with the pin parameter, but we don't recommend this in a production setting best practice is to specify the pin with the vault hsm pin environment variable, as shown here this prevents the password from being exposed if the config file is compromised or you store it in an unsecure location if set through the environment variable, vault obfuscates the environment variable after reading it the one caveat is that you need to re set the vault hsm pin environment variable if you restart the vault now, start the vault server with the following command vault server config=/etc/vault d/vault hcl if this command is successful, you should see 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 and leave the terminal running where you started the vault server initialize vault in the new terminal, first, set the vault addr environment variable export vault addr='http //0 0 0 0 8200' check the vault status vault status the output should be similar to the following 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 vault operator init recovery shares=1 recovery threshold=1 the output should be similar to the following 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 set the vault token environment variable value to the generated root token value displayed in the terminal output to interact with vault, you must provide a valid token setting this environment variable enables interaction with vault through the cli export vault token="s mvx8cihrfqmweim9yfnlw9e1" access the vault ui go to http //localhost 8200 in a web browser copy and paste the initial root token from the output of the vault initialization command into the token field, and select \[ sign in ] if the log in succeeds, you see the vault ui homepage 6 | enable and test the seal wrap feature to enable and test the seal wrap feature, perform the tasks in this section enable seal wrap to enable seal wrap , choose the appropriate method and perform the instructions to compare seal wrapped data against unwrapped data, enable key/value v1 secrets engine at two different paths kv unwrapped and kv seal wrapped enable k/v v1 without seal wrap at kv unwrapped vault secrets enable path=kv unwrapped kv enable k/v v1 with seal wrap to do so, use 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 list the enabled secrets engines with details $ vault secrets list detailed 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 unwrapped/ open a web browser and launch the vault ui (for examole, http //127 0 0 1 8200/ui ) and then log in select secrets engines in the left menu select \[ enable new engine ] select kv from the list, and then select \[ next ] enter kv unwrapped in the path field and select \[ enable new engine ] 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, expand method options , select the seal wrap checkbox, and select \[ enable engine ] select method options to expand and select the seal wrap checkbox test the seal wrap feature to test the seal wrap feature, perform the following tasks test the feature view the encrypted sectets test the feature to test the seal wrap feature, choose the appropriate method and follow the instructions write a secret at kv unwrapped/unwrapped for testing vault kv put kv unwrapped/unwrapped password="my long password" read the path to verify vault kv get kv unwrapped/unwrapped \====== data ====== key value \ password my long password write the same secret at kv seal wrapped/wrapped for testing vault kv put kv seal wrapped/wrapped password="my long password" read the path to verify vault kv get kv seal wrapped/wrapped \====== data ====== key value \ password my long password using a valid token, you can write and read secrets the same way regardless of the seal wrap select kv unwrapped and select \[ create secret ] enter the following information in path for this secret , enter unwrapped in secret key , enter password in value , enter my longpassword select \[ save ] repeat the same step for kv seal wrapped to write the same secret at the kv seal wrapped/wrapped path select \[ save ] using a valid token, you can write and read secrets the same way regardless of the seal wrap view the encrypted secrets to view the encrypted secrets, choose the appropriate method and follow the instructions the following examples assume the vault server is configured to use the local file system ( /tmp/vault ) as its storgage backend # 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 in the /tmp/vault/logical directory, there are 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 cd 2da357cd 55f2 7eed c46e c477b70bed18 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 view its content the password value is encrypted cat wrapped {"value" "clbag9on7zbbadbzcsildaygkl7sope7vba5+adaduyzo8guhzhb9ufn2nf1h0opkegcikg3jnhcxt tzqci6szcunbgf3pwhwgwb4frem3b5criqyk7239q92grgrcbbezd6ghogetsbdmzjbahk7n4liyf3x4ibqmwzgh vo4lzwur7rzncgasofciiheneegghoc21fzgvtbyinahntx2htywnfzgvtb3m="} secrets are encrypted regardless; however, the seal wrapped value is significantly longer despite the fact that both values are the same, my long password ssh into the machine where the vault server is running, and check the stored values in the /tmp/vault directory cd /tmp/vault/logical under the /tmp/vault/logical directory, there are 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 cd 2da357cd 55f2 7eed c46e c477b70bed18 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 view its content the password value is encrypted cat wrapped {"value" "clbag9on7zbbadbzcsildaygkl7sope7vba5+adaduyzo8guhzhb9ufn2nf1h0opkegcikg3jnhcxt tzqci6szcunbgf3pwhwgwb4frem3b5criqyk7239q92grgrcbbezd6ghogetsbdmzjbahk7n4liyf3x4ibqmwzgh vo4lzwur7rzncgasofciiheneegghoc21fzgvtbyinahntx2htywnfzgvtb3m="} secrets are encrypted regardless; however, the seal wrapped value is significantly longer despite the fact that both values are the same, my long password 7 | enable and test the entropy augmentation feature to leverage the external entropy source, set the external entropy access parameter to true when you enable a secrets engine or auth method this step shows how to enable external entropy source on a transit secrets engine you must enable the entropy augmentation feature through the cli at this time, we do not support enabling entropy augmentation through the web ui execute the following command to enable the transit secrets engine with external entropy source by using the external entropy access flag vault secrets enable external entropy access transit list the enabled secrets engine with detailed flag vault secrets list detailed 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 hsm as its external entropy source regardless, the user experience remains the same as before example 1 create a new encryption key named, orders vault write f transit/keys/orders 2 send a base64 encoded string to be encrypted by vault vault write transit/encrypt/orders plaintext=$(base64 <<< "4111 1111 1111 1111") key value \ ciphertext vault\ v1\ ay3zf2bwgfwz9djlsztcldppuhkfl/kwaqeritvkgn74bgyymi+n34w1cmo8aeg= 3 now, test to verify that you can decrypt vault write transit/decrypt/orders \\ ciphertext="vault\ v1\ ay3zf2bwgfwz9djlsztcldppuhkfl/kwaqeritvkgn74bgyymi+n34w1cmo8aeg=" 4 decode to get the original data base64 decode <<< y3jlzgl0lwnhcmqtbnvtymvycg== credit card number when the external entropy access is enabled, the connectivity to the hsm is required if the hsm becomes unreachable for any reason, the transit secrets engine fails to generate new keys or rotate the existing keys 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