Secure your Server Keys

This topic describes using a master key to secure your server keys which include the data key, the DAP UI key, and SSL keys.

Overview

Securing the server keys is an important aspect of securing DAP in production.

To allow easy setup and testing when first getting started with DAP, these keys are automatically generated and stored in plaintext during initial configuration of the Master DAP Server. When moving to a production environment, we recommend encrypting these keys using an external encryption key, known as the master key.

Encrypting the server keys has the following advantages:

  • Operational DAP Servers do not store any keys in plaintext on the file system. The data key is stored in the Linux kernel keyring, and SSL private keys are stored in the container memory.
  • Seed files, which are used to initialize Standbys and Followers, contain only keys that are encrypted and are therefore no longer a part of the threat surface of DAP itself.
  • The master key that unlocks the server keys can be provided by a dedicated master key facility such Amazon Key Management Service (AWS KMS) or a hardware security module (HSM).

The following sections describe the evoke keys commands in general followed by step-by-step procedures for how to encrypt with a master key file, the AWS KMS, or an HSM.

Detailed information on using encrypted keys with high availability DAP configurations is included in each procedure.

Commands

evoke includes the following commands to encrypt the server keys and unlock the keys. "Unlocked" keys are transferred to the Linux kernel keyring and into memory (in the case of SSL keys). Using the kernel keyring ensures that plaintext keys are never stored on the file system, and also ensures that only authorized processes can access them.

For a full list of evoke keys commands, run evoke keys --help.

Master key parameter

Most commands require the master key. The master key can be provided either:

  • In a file (e.g. a volume mounted into Docker)
  • From stdin (by specifying - as the master key filename)
  • Automatically from the configured master key facility (by omitting the master key argument)

Location of the keys

Key

Name

Location

Data key

possum.key

/opt/conjur/etc/

DAP UI key

ui.key

/opt/conjur/etc/

SSL keys

For example:

  • conjur.key
  • ca.key

/opt/conjur/etc/ssl/

Command details

The results of the commands can be seen in these directories.

Command

Description

evoke keys encrypt

Synopsis:

evoke [global options] keys encrypt master.key?

Encrypts the server keys. The unencrypted server keys are deleted from the file system and are replaced with encrypted files, ending with the suffix *.enc.

Example:

evoke keys encrypt /secrets/master.key

evoke keys decrypt

Synopsis:

evoke [global options] keys decrypt key-name master.key?

Decrypts the specified key and prints it to stdout. The key name must match the key filename, as if the local working folder is /opt/conjur/etc.

Examples:

evoke keys decrypt possum.key

evoke keys decrypt ssl/my-follower /secrets/master.key

evoke keys decrypt-all

Synopsis:

evoke [global options] keys decrypt-all master.key?

Decrypts all keys and places them on the file system in plain text. This is the inverse of encrypt.

Example:

evoke keys decrypt-all /secrets/master.key

evoke keys exec

Synopsis:

evoke [global options] keys exec [command options] master.key? -- command [arg1, arg2 ...]

Executes a program that requires access to the server keys. The keys are unlocked before running the command. The -m parameter is used to place the master key into the Linux keyring along with the server keys.

After evoke keys encrypt has encrypted the server keys, evoke keys exec -m is required in any of the following evoke commands :

  • evoke ca issue
  • evoke ca regenerate
  • evoke unpack
  • evoke restore --accept-eula
  • evoke configure (except on creation of the initial Master)

Examples:

  • Print the keys in the keyring:

    evoke keys exec -- keyctl show

  • Unlock keys to the keyring using a master key file, and run evoke configure follower:

    evoke keys exec -m /secrets/master.key -- evoke configure follower

  • Use configured master key facility to unlock keys to the keyring, and restore from backup:

    evoke keys exec -m -- evoke restore --accept-eula

evoke keys lock

Synopsis:

evoke [global options] keys lock

Locks access to the encrypted server keys. This means that the plaintext keys are removed from the Linux kernel keyring and memory.

Once the server keys are removed from the keyring, the DAP services no longer start up and have no way to decrypt data from the database. For the services to start successfully, use evoke keys unlock or evoke keys exec.

Example:

evoke keys lock

evoke keys show-master-key

Synopsis:

evoke [global options] keys show-master-key

When HSM or KMS are configured, retrieves the master key from the master key facility ().

evoke keys unlock

Synopsis:

evoke [global options] keys unlock master.key?

Securely decrypts the server keys. The data key and DAP UI key are stored in the Linux kernel keyring and the SSL keys are stored in memory based file system (/dev/shm/ssl). The decrypted keys are available only to DAP services.

You must use this command or evoke keys exec before starting any of the following services:

  • pg (PostgreSQL database)
  • nginx (Webserver)
  • conjur (DAP services)

Limitations

OpenShift/Kubernetes integration: When server key encryption is enabled, the Seed service for auto-enrolling Followers in Kubernetes is not supported.

For more information about auto-enrolling Followers in Kubernetes, see Configure DAP for auto-enrollment of Followers.