# 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 Unseal tool installation¶

If Anjuna 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 Unseal tool environment is not setup correctly. $ anjuna-encrypt


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 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!