Server Setup » Tools » Evoke
evoke is a command-line utility for configuring, backing up and restoring Conjur servers.
It is pre-installed on every Conjur server.
- setup a standalone, master, standby, or follower system on a bare Conjur system
- generate seeds for the creation of a follower or standby from a Conjur master
- create backups and restore a Conjur server from a backup
Complete operational documentation, including
evoke usage is available from Conjur Support.
The rest of this page illustrates how to encrypt Conjur's database keys with evoke.
Securing Conjur Master Database Keys with Evoke (4.6+)
Securing Conjur's database encryption keys and SSL private keys is an important aspect of securing
Conjur in production. Each Conjur services, including
has its own key for encrypting data in the Conjur database. In addition, each Conjur server operates
with an SSL private key.
To allow easy setup and testing when first getting started with Conjur,
these keys are automatically generated and stored in plain text during initial configuration of a
Conjur Master server. When moving to a production environment, we recommend that you encrypt the keys
using the Conjur
evoke server management tool.
Encrypting the server keys has the following advantages:
- Operational Conjur servers do not store any keys in plaintext on the filesystem. Application keys are stored in the Linux kernel keyring, and SSL private keys are stored only in memory.
- Conjur "seed" files, which are used to initialize Standby and Follower servers, contain only encrypted keys and are therefore no longer a part of the threat surface to Conjur itself.
- The master key that unlocks the server keys can be provided by a dedicated master key facility such as an HSM or Amazon Key Management Service.
The following sections describe the
evoke keys commands in general followed by step-by-step procedures
for how to encrypt with either a master key file or Amazon Web Services (AWS) Key Management Services (KMS).
Detailed information on using encrypted keys with Conjur HA configurations is included in each procedure.
evoke includes the following commands to encrypt the
Conjur database keys and unlock the keys. "Unlocked" keys are transferred to the Linux kernel keyring
and into memory (in the case of SSL private keys). Conjur's use of the kernel keyring ensures that
plain text keys are never stored on the file system, and also ensures that only authorized
processes can access them.
NAME keys - Commands to lock and unlock master keys SYNOPSIS evoke [global options] keys decrypt key-name master-key-file? evoke [global options] keys decrypt-all master-key-file? evoke [global options] keys encrypt master-key-file? evoke [global options] keys exec [-m|--propagate-master-key] master-key-file? -- command [arg1 arg2 ...] evoke [global options] keys kms <region> evoke [global options] keys lock evoke [global options] keys show-master-key evoke [global options] keys unlock master-key-file? COMMANDS decrypt - Decrypt a Conjur service key decrypt-all - Decrypts all the encrypted key material and restores the plain-text files encrypt - Encrypt the master keys exec - Run a child process with the unlocked keys in the keyring kms - Bind a Conjur master key to an AWS KMS region lock - Lock the master keys show-master-key - Obtain and print the master key unlock - Unlock the master keys
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)
- By Amazon KMS (by omitting the master key argument)
Location of the keys
Application keys are located in
/opt/conjur/etc. SSL private keys are in
/opt/conjur/etc/ssl. The results of the below commands can be seen in these directories.
evoke keys encrypt
Encrypts the Conjur application keys and SSL private keys, which are generated by
evoke configure master.
evoke keys decrypt
Decrypts the specified key and prints it to stdout.
evoke keys decrypt-all
Decrypts all keys and places them on the file system in plain text. This is the inverse of
evoke keys exec
Executes a program (e.g. shell script) that requires access to the Conjur keys.
The keys are decrypted and placed into the Linux kernel keyring before running the command.
-m parameter is used to place the Conjur master key into the Linux keyring along with the Conjur keys.
# Print the keys in the keyring (which will be cleaned up as soon as the command exits) $ 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 # In AWS environment use KMS conjur master keys to unlock keys to the keyring, # and restore from backup $ evoke keys exec -m -- evoke restore
evoke keys exec -m -- is required to use any of the following evoke commands after
evoke keys encrypt has encrypted the Conjur keys:
evoke ca issue
evoke ca regenerate
evoke configure(except on creation of the initial master)
evoke keys kms
Generates AWS IAM Assets for encrypting and decrypting the Conjur master database key and SSL private keys with AWS KMS keys for the aws-region specified.
This command creates the following AWS assets:
AWS IAM Role
conjur-appliance- Enables Conjur servers running in EC2 to read the master key from KMS. Before launching an EC2 instance, you will need to select this IAM Role for the EC2 instance.
AWS IAM Encryption Keys (KMS master keys)
conjur-_aws-region_-timestamp- One key will be created for each AWS region. AWS KMS master keys cannot be shared across regions. Conjur’s master data key must be encrypted with a key from every AWS region where you plan to run Conjur servers.
After generating the AWS assets, conjur aws keys create also generates:
- Encrypted Conjur master key file - A KMS encrypted master key file is generated in /opt/conjur/etc for the aws-region specified, e.g. kms-master-key.aws-region.enc
evoke keys lock
Locks access to the encrypted Conjur database keys. The decrypted keys are removed from the Linux kernel keyring, and the Conjur services and nginx are stopped. Once the service keys are removed from the keyring, the Conjur services will no longer start up and have no way to decrypt data from the database.
evoke keys show-master-key
Retrieves the master key encrypted by AWS KMS master keys. The command can only be used on a
Conjur server EC2 instance or an environment configured with a User AWS access key and AWS
region with permissions to use the KMS key generated for that region by
evoke keys kms.
evoke keys unlock
Securely decrypts the Conjur keys stored in
/opt/conjur/etc/(*.key.enc) and stores the plain
text keys in the Linux kernel keyring. The decrypted keys are available only to Conjur system services.
You must use this command before starting any of the following services:
There are two options detailed below to encrypt the Conjur master keys
- Encrypt using a master key file
- Encrypt using AWS KMS
Encrypt using a master key file
During the initial configuration of a Conjur master server,
evoke configure master will generate plain text
service keys for all Conjur services and place them in
- authn.key, authz.key, core.key, host-factory.key, pubkeys.key
- ssl/conjur.key, ssl/ca.key
Use the evoke keys commands to encrypt the keys and unlock the encrypted keys to the Linux keyring.
Note: The master-key file must be kept secure. It is used to encrypt all of Conjur's database passwords. To encrypt and unlock Conjur's database keys requires the master-key file used with evoke keys encrypt.
That means you must copy and secure the master-key file yourself. Use AWS KMS keys instead to securely automate the process as described further in the document.
1. Configure the Conjur Master
# Configure the Conjur master server master # evoke configure master -h conjur-master.yourcorp -p password mycorp # Stop the Conjur services and nginx master # evoke keys lock # Generate a random password for the master key. Keep this file secure. master # openssl rand 32 > /secrets/master-key # Encrypt the plain text Conjur key files and SSL private keys # Encrypt the keys with a 32-byte master key. master # evoke keys encrypt /secrets/master-key Encrypted 9 key files and adjusted 2 symlinks # Unlock the Conjur service keys and start the Conjur service master # evoke keys unlock /secrets/master-key # In the Conjur container log, you will see “Searching keyring for key…” # and “Read key for…” for all Conjur services
Once complete the Conjur Master is running and using the Conjur keys from the secure Linux kernel keyring.
/opt/conjur/etc directory will now contain only the encrypted keys instead of unencrypted keys:
- authn.key.enc, authz.key.enc, core.key.enc, host-factory.key.enc, pubkeys.key.enc
- ssl/conjur.key.enc, ssl/ca.key.enc
As the keys are now encrypted, it's necessary to
unlock them before starting any services.
Unlocking will be required on every server/VM/container boot or restart.
The key will need to be provided by an administrator.
2. Configure Conjur HA servers
The basic process for setting up a Conjur Follower involves:
- Create the certificate and private key on the Master
- Encrypt the keys
- Generate a Follower seed file on the Master
- Transfer the seed file to the Follower
- Unpack the seed file on the Follower and configure the Follower
Because the seed file will contain only encrypted key material, the seed file is secure. Only someone with the master key is able to decrypt the key material in the seed file.
Conjur HA servers types include Standby, Follower, and Auditor. The following procedure describes setting up a Conjur Follower after encrypting the Conjur keys but the process is the same for the other types of Conjur HA servers - simply replace the word follower with standby or auditor.
a. Generate a Follower seed on the Conjur Master
Run the following commands on the Conjur Master. This example assumes you have put the master-key file created in Step 1 in "/secrets/master-key".
# Generate the certificate for the follower master # evoke keys decrypt-all /secrets/master-key master # evoke ca issue conjur-east.yourcorp # Encrypt the keys master # evoke keys encrypt /secrets/master-key # Create a secure seed file on the Conjur Master master # evoke seed follower conjur-east.yourcorp conjur-master.yourcorp > /seed/conjur-east.yourcorp.tar
b. Copy files to the follower
conjur-east.yourcorp.tar to the Follower. Transfer the /secrets/master-key file to the Follower.
c. Load the seed file on the Follower
# Unpack the seed file follower # evoke unpack seed /seed/conjur-east.yourcorp.tar # Configure the follower follower # evoke keys exec -m /secrets/master-key -- evoke configure follower
Note: For a Conjur High Availability configuration,
the encrypted keys in `/opt/conjur/etc` are included in the seed file created on the Conjur Master by the
evoke seed follower.
It is not necessary to use the `evoke keys encrypt` command on the Follower since the keys are already encrypted in the seed file. But it is necessary to use `evoke keys unlock` with the same master key used to encrypt the keys on the master prior to starting the service on the Follower.
Backup and Restore with a master key file
After encrypting the master keys, it will be necessary to provide the master key file to use `evoke restor``.
This example assumes you have put the master-key file created in Step 1 in "/secrets/master-key":
# Take a backup from the master master # evoke backup # Copy the files from the backup directory master # cp /opt/conjur/backup/* /backup
# Restore from backup master # evoke unpack backup --key /backup/key /backup/2016-02-03T05-11-12Z.tar.xz.gpg master # evoke keys exec -m /secrets/master-key -- evoke restore