6.4.4.6 Using the HashiCorp Vault Keyring Plugin

Prepare the company and HashiCorp Vault server keys.

Use the following commands to generate the key files:

openssl genrsa -aes256 -out company.key 4096
openssl genrsa -aes256 -out vault.key 2048

The commands produce files holding the company private key (company.key) and the Vault server private key (vault.key). The keys are randomly generated RSA keys of 4,096 and 2,048 bits, respectively.

Each command prompts for a password. (For testing purposes, the password is not required. To disable it, omit the -aes256 argument.)

The key files hold sensitive information and should be stored in a secure location. The password (also sensitive) is required later, so write it down and store it in a secure location.

(Optional) To check key file content and validity, use the following commands:

openssl rsa -in company.key -check
openssl rsa -in vault.key -check

Create the company CA certificate.

Use the following command to create a company CA certificate file named company.crt that is valid for 365 days (enter the command on a single line):

openssl req -x509 -new -nodes -key company.key
  -sha256 -days 365 -out company.crt

You will be prompted for the company key password during CA certificate creation, if you used the -aes256 argument to perform key encryption during key generation. You will also be prompted for information about the certificate holder (that is, you or your company), as shown here:

Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:
Email Address []:

Answer the prompts with appropriate values.

Create a certificate signing request.

To create a HashiCorp Vault server certificate, a Certificate Signing Request (CSR) must be prepared for the newly created server key. Create a configuration file named request.conf containing the following lines. If the HashiCorp Vault server does not run on the local host, substitute appropriate CN and IP values, and make any other changes required.

[req]
distinguished_name = vault
x509_entensions = v3_req
prompt = no

[vault]
C = US
ST = CA
L = RWC
O = Company
CN = 127.0.0.1

[v3_req]
subjectAltName = @alternatives
authorityKeyIdentifier = keyid,issuer
basicConstraints = CA:TRUE

[alternatives]
IP = 127.0.0.1

Use this command to create the signing request:

openssl req -new -key vault.key -config request.conf -out request.csr

The output file (request.csr) is an intermediate file that serves as input for creation of the server certificate.

Create the HashiCorp Vault server certificate.

Sign the combined information from the HashiCorp Vault server key (vault.key) and the CSR (request.csr) with the company certificate (company.crt) to create the HashiCorp Vault server certificate (vault.crt). Use the following command to do this (enter the command on a single line):

openssl x509 -req -in request.csr
  -CA company.crt -CAkey company.key -CAcreateserial
  -out vault.crt -days 365 -sha256

To make the vault.crt server certificate useful, append the contents of the company.crt company certificate to it. This is required so that the company certificate is delivered along with the server certificate in requests.

cat company.crt >> vault.crt

If you open the vault.crt file with a text editor, its content should look like this:

-----BEGIN CERTIFICATE-----
... content of HashiCorp Vault server certificate ...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... content of company certificate ...
-----END CERTIFICATE-----

Fetch the HashiCorp Vault binary.

Download the HashiCorp Vault binary appropriate for your platform from https://www.vaultproject.io/downloads.html.

Extract the content of the archive to produce the executable vault command, which is used to perform HashiCorp Vault operations. If necessary, add the directory where you install the command to the system path.

(Optional) HashiCorp Vault supports autocomplete options that make it easier to use. For more information, see https://learn.hashicorp.com/vault/getting-started/install#command-completion.

Create the HashiCorp Vault server configuration file.

Prepare a configuration file named config.hcl with the following content. For the tls_cert_file, tls_key_file, and path values, substitute path names appropriate for your system.

listener "tcp" {
  address="127.0.0.1:8200"
  tls_cert_file="/home/username/certificates/vault.crt"
  tls_key_file="/home/username/certificates/vault.key"
}

storage "file" {
  path = "/home/username/vaultstorage/storage"
}

ui = true

Start the HashiCorp Vault server.

To start the Vault server, use the following command, where the -config option specifies the path to the configuration file just created:

vault server -config=config.hcl

During this step, you may be prompted for a password for the Vault server private key stored in the vault.key file.

The server should start, displaying some information on the console (IP, port, and so forth).

So that you can enter the remaining commands, put the vault server command in the background or open another terminal before continuing.

Initialize the HashiCorp Vault server.

Issue the following commands (assuming Bourne shell syntax):

export VAULT_SKIP_VERIFY=1
vault operator init -n 1 -t 1

The first command enables the vault command to temporarily ignore the fact that no company certificate has been added to the system trust store. It compensates for the fact that our self-signed CA is not added to that store. (For production use, such a certificate should be added.)

The second command creates a single unseal key with a requirement for a single unseal key to be present for unsealing. (For production use, an instance would have multiple unseal keys with up to that many keys required to be entered to unseal it. The unseal keys should be delivered to key custodians within the company. Use of a single key might be considered a security issue because that permits the vault to be unsealed by a single key custodian.)

Vault should reply with information about the unseal key and root token, plus some additional text (the actual unseal key and root token values will differ from those shown here):

...
Unseal Key 1: I2xwcFQc892O0Nt2pBiRNlnkHzTUrWS+JybL39BjcOE=
Initial Root Token: s.vTvXeo3tPEYehfcd9WH7oUKz
...

Store the unseal key and root token in a secure location.

Unseal the HashiCorp Vault server.

Use this command to unseal the Vault server:

vault operator unseal

When prompted to enter the unseal key, use the key obtained previously during Vault initialization.

Vault should produce output indicating that setup is complete and the vault is unsealed.

Log in to the HashiCorp Vault server and verify its status.

Prepare the environment variables required for logging in as root:

vault login s.vTvXeo3tPEYehfcd9WH7oUKz

For the token value in that command, substitute the content of the root token obtained previously during Vault initialization.

Verify the Vault server status:

vault status

The output should contain these lines (among others):

...
Initialized     true
Sealed          false
...

Set up HashiCorp Vault authentication and storage.

Enable the AppRole authentication method and verify that it is in the authentication method list:

vault auth enable approle
vault auth list

Enable the Vault KeyValue storage engine:

vault secrets enable -version=1 kv

Create and set up a role for use with the keyring_hashicorp plugin (enter the command on a single line):

vault write auth/approle/role/mysql token_num_uses=0
  token_ttl=20m token_max_ttl=30m secret_id_num_uses=0

Add an AppRole security policy.

Prepare a policy that to permit the previously created role to access appropriate secrets. Create a new file named mysql.hcl with the following content:

path "kv/mysql/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

Import the policy file to the Vault server to create a policy named mysql-policy, then assign the policy to the new role:

vault policy write mysql-policy mysql.hcl
vault write auth/approle/role/mysql policies=mysql-policy

Obtain the ID of the newly created role and store it in a secure location:

vault read auth/approle/role/mysql/role-id

Generate a secret ID for the role and store it in a secure location:

vault write -f auth/approle/role/mysql/secret-id

After these AppRole role ID and secret ID credentials are generated, they are expected to remain valid indefinitely. They need not be generated again and the keyring_hashicorp plugin can be configured with them for use on an ongoing basis. For more information about AuthRole authentication, visit https://www.vaultproject.io/docs/auth/approle.html.

Use SET statements to assign the desired new values to the configuration system variables shown in the preceding table. These assignments in themselves have no effect on ongoing plugin operation.

Invoke keyring_hashicorp_update_config() to cause the plugin to reconfigure and reconnect to the HashiCorp Vault server using the new variable values.

If the connection is successful, the plugin stores the updated configuration values in corresponding system variables that have _commit_ in their name.