Getting started

In this section, we will go through the steps to:

  • Create a Vault Unseal configuration file
  • Encrypt the configuration file using the SGX Sealing capabilities
  • Run the Vault Unseal utility using the Anjuna SGX Runtime to unseal a running Vault instance.

Prerequisites

Note

Reminder: it is important to run the following command to make it possible to run the Anjuna tools (replace or define ANJUNA_HOME with the correct value):

$ source ${ANJUNA_HOME}/env.sh

Anjuna Vault-Unseal tool installation

If Anjuna Vault-Unseal tool was properly installed, and the environment set using env.sh, running anjuna-encrypt should work and produce the following output:

$ anjuna-encrypt
Usage: anjuna-encrypt [OPTIONS]... FILE

If the command fails with the following message, the Anjuna Vault-Unseal tool environment is not setup correctly.

$ anjuna-encrypt
anjuna-encrypt: command not found

See the note above to correct the issue.

Vault instance

We assume Vault has been properly setup:

  • Vault is running
  • Vault is configured with a TLS listener
  • Vault is sealed
  • The Vault CA Certificate is available
  • The Vault unseal keys are available

If such an instance is not available, the next section will describe a few simple steps to quickly setup a test instance suitable for this tutorial.

Setup a working directory

Create a working directory where the files for unsealing a specific instance of Vault will be located.

$ mkdir vault-unseal-tutorial
$ cd vault-unseal-tutorial

Create a test Vault instance

Note

The instructions in this section are optional. If you already have a running Vault instance, just proceed to the Create the Vault Unseal Configuration File section.

If you do not have a running Vault instance, or if you do not want to use your existing Vault instance to learn about the Vault Unseal utility, follow the steps in this section.

To create a test instance for the purpose of going through the steps of this tutorial, you can just enter the following commands to quickly create a test configuration of a Vault server running with a TLS certificate:

$ anjuna-tutorial-quick-vault-setup --port 9980
$ anjuna-tutorial-quick-vault-setup --start

These commands will create a Vault configuration and start it after displaying the configuration parameters (notice the different port used by this Vault instance to avoid conflicting with any running Vault instance on this host).

$ anjuna-tutorial-quick-vault-setup --port 9980
Launching Anjuna Tutorial Vault instance...
Initializing Vault...
Unsealing Vault...
Using unseal key #1...
Using unseal key #2...
Using unseal key #3...
Vault server unsealed
Connection to Vault...
Generating test wildcard certificate...
TLS certificates generated
Success: A test Vault configuration was created!
Vault Address          : https://vault.anjuna.test:9980
Vault Server CA-CERT   : /home/anjuna/vault-unseal-tutorial/config/ca.crt
Vault Root Token       : # root_token: 1gDYjJsGKW65L7SXPw55WIOD
Vault Unseal keys      :
- jZYf9QD5KGXyV4uPFsWBDMTpqCrj9kOreq2RaAlBRI24
- 9riaEZETGJg7FP8rI5PkPxOvowNDZc4N1UOXiwkIA7HR
- yQ6niGrXCweJRB9/jId+sQRDQhYpgY9GYLm2sQk7beAJ


To start Vault, run the following command:
  anjuna-tutorial-quick-vault-setup --start


$ anjuna-tutorial-quick-vault-setup --start
Starting Vault...
Vault Address          : https://vault.anjuna.test:9980
Vault Server CA-CERT   : /home/anjuna/vault-unseal-tutorial/config/ca.crt
Vault Root Token       : # root_token: 1gDYjJsGKW65L7SXPw55WIOD
Vault Unseal keys      :
- jZYf9QD5KGXyV4uPFsWBDMTpqCrj9kOreq2RaAlBRI24
- 9riaEZETGJg7FP8rI5PkPxOvowNDZc4N1UOXiwkIA7HR
- yQ6niGrXCweJRB9/jId+sQRDQhYpgY9GYLm2sQk7beAJ

Note

The first execution of anjuna-tutorial-quick-vault-setup --start will trigger the following message:

$ anjuna-tutorial-quick-vault-setup --start
Warning:
To use the Vault TLS certificate, the following entry should be added to /etc/hosts:
127.0.0.1 vault.anjuna.test

Run the following command to add this entry to /etc/hosts
    $ echo '127.0.0.1 vault.anjuna.test' | sudo tee -a /etc/hosts

This occurs only because the test TLS certificate generated for the Vault instance assumes the value vault.anjuna.test for the hostname. Just run the following command (as indicated in the message)

echo '127.0.0.1 vault.anjuna.test' | sudo tee -a /etc/hosts

and re-run the anjuna-tutorial-quick-vault-setup --start command again:

$ anjuna-tutorial-quick-vault-setup --start

We now have a test Vault instance with the required information to create the Vault Unseal Configuration File:

  • The server address
  • The CA Certificate
  • The unseal keys

Create the Vault Unseal Configuration File

Run

$ anjuna-create-unseal-config

It will prompt you for the information needed to create a configuration file:

  • The Vault server URL
  • The path to the Vault server certificate (or the CA certificate associated with the Vault server certificate)
  • Vault unseal keys

Here is an example of running the script:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
$ anjuna-create-unseal-config
Anjuna Vault Unseal Configuration
-----
[Vault URL]       : https://vault.anjuna.test:9980
[Vault CA-CERT]   : /home/anjuna/vault-unseal-tutorial/config/ca.crt
[Unseal Key #1]   : jZYf9QD5KGXyV4uPFsWBDMTpqCrj9kOreq2RaAlBRI24
[Unseal Key #2]   : 9riaEZETGJg7FP8rI5PkPxOvowNDZc4N1UOXiwkIA7HR
[Unseal Key #3]   : yQ6niGrXCweJRB9/jId+sQRDQhYpgY9GYLm2sQk7beAJ
[Unseal Key #4]   :
Using Vault endpoint: https://vault.anjuna.test:9980
Using Vault CA-CERT: /home/anjuna/vault-unseal-tutorial/config/ca.crt
Using Unseal Keys:
- jZYf9QD5KGXyV4uPFsWBDMTpqCrj9kOreq2RaAlBRI24
- 9riaEZETGJg7FP8rI5PkPxOvowNDZc4N1UOXiwkIA7HR
- yQ6niGrXCweJRB9/jId+sQRDQhYpgY9GYLm2sQk7beAJ
Generating unseal-config.yml in current directory
Encrypting unseal-config.yml
Sealed unseal-config.yml to unseal-config.yml.sealed
Deleting unseal-config.yml
Success: unseal-config.yml.sealed generated => the Vault unseal configuration was created and encrypted
  • Line 4: Enter the URL for the Vault server. This should be an HTTPS URL, and it should include the port Vault is listening on. This is the same address as what would be specified in the --address= command line parameter when running the vault client or in the VAULT_ADDR environment variable (see Vault Commands (CLI) for more information on the Vault client tool).
  • Line 5: Enter the path of a PEM-encoded CA certificate. It is used to verify the Vault server’s TLS certificate.
  • Line 6-9: Enter each one of unseal keys for this Vault instance (one per line). Enter an empty string to indicate that all the keys have been provided.
  • Line 11-18: The script checks for the Vault URL and the Vault CA certificate.

If the provided values are correct, the configuration will be created and encrypted.

Unseal Vault

Using the previous created Vault Unseal configuration, we can now securely unseal Vault:

$ anjuna-vault-unseal

which produces the following output:

Found Vault Unseal configuration => unsealing now...
2019/03/05 11:01:23 - Unsealing Vault https://vault.anjuna.test:9980 using token 1/3
2019/03/05 11:01:23 - Unsealing Vault https://vault.anjuna.test:9980 using token 2/3
2019/03/05 11:01:23 Vault is now unsealed

Summary

Congratulations! You have created a Vault Unseal encrypted configuration that can securely unseal your Vault instance!