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 Amazon Key Management Service or an HSM.
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 three options detailed below to encrypt the Conjur keys
- Encrypt using a master key file
- Encrypt using AWS KMS
- Encrypt using a PKCS#11-compliant HSM
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
Encrypt using AWS KMS
Encrypt using an HSM (220.127.116.11+)
Conjur supports the use of a PKCS#11-compliant Hardware Security
Module (HSM) to securely manage a Conjur master key. Using the
evoke pkcs11 subcommand, you can use an HSM to generate a key
encryption key, wrap (i.e. encrypt) the Conjur master key, encrypt
the Conjur service keys with that master key, then store the wrapped
master key. Both the key encryption key and the plaintext Conjur
master key never leave the HSM.
Once the Conjur master key has been wrapped, the
subcommands use the HSM to unwrap it when performing their
These are some of the terms specific to using an HSM.
- Hardware Security Module (HSM)
- Per Wikipedia, an HSM is "a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing".
- Key Encryption Key (KEK)
- A key, generated and maintained by the HSM, used to encrypt other keys.
- Security Token
- Often shortened to "token", this is a storage device that plugs into the HSM and stores key encryption keys.
- Wrap and Unwrap
- HSM operations to encrypt and decrypt a key, respectively.
Overview of Operation with an HSM
At the highest level, using the PKCS#11 support involves the following steps:
Obtain a Linux x86_64 shared library for your HSM, copy it into the Conjur container.
Configure Conjur's PKCS#11 support to use the shared library.
Have the HSM generate a new key encryption key.
Wrap the Conjur master key (optionally generating a new one).
Encrypt the Conjur service keys with the master key.
Configuring the Appliance
To use an HSM with Conjur, you must first obtain the Linux x86_64 shared library appropriate for your HSM. Copy it into the container for your Conjur appliance.
Once you have the shared library, you must create the file
/opt/conjur/etc/pkcs11.yml and add configuration information to
The following settings can appear in the file:
- required, full path to the shared object containing the PKCS#11 module to use.
- required, module ID of the key to wrap the Conjur master key with. If you choose to generate a Conjur master key, it will be stored with this ID.
- optional, a hash or a string with additional parameters to be passed to the module.
- optional, index of the HSM slot containg the token to use (zero-based). If omitted, the first slot supporting key storage is automatically used.
- optional, PIN for logging into the module. If omitted, an empty password will be assumed.
As an example, this
pkcs11.yml file configures the appliance to
use NSS Softoken Cyptographic Module. Softoken, available as part of
libnss3 package, is a PKCS#11 module that stores key
encryption keys in the file system.
# pkcs11.yml example library: /usr/lib/x86_64-linux-gnu/nss/libsoftokn3.so parameters: configDir: /var/lib/softokn wrapping_key: CONJUR
Generating a Key Encryption Key
Once HSM support is configured, use
evoke pkcs11 generate to have
the HSM create a key encryption key and store it on the token.
# evoke pkcs11 generate --help NAME generate - Generate a master key wrapping key SYNOPSIS evoke [global options] pkcs11 generate DESCRIPTION Generate a new master key wrapping key in the configured PKCS#11 token. For convenience, the token will be initialized if required.
Wrapping the Master Key
After creating the key encryption key, use
evoke pkcs11 wrap to
wrap the Conjur master key.
If you've previously encrypted your Conjur keys, you'll need to
provide that master key. Otherwise,
evoke pkcs11 wrap will
generate a new, random, 32-byte master key.
# evoke pkcs11 wrap --help NAME wrap - Wrap the master key SYNOPSIS evoke [global options] pkcs11 wrap [command options] [(master-key-file | STDIN)] DESCRIPTION Wrap the Conjur master key using configured PKCS#11 token and key. The Conjur master key can be obtained by other mechanisms or generated. COMMAND OPTIONS -g, --[no-]generate - Force generation of a new master key even if one can be found --[no-]no-generate - Prevent generation of a new master key even if none can be found
Using the Wrapped Master Key
Once the master key has been wrapped, you no longer need to provide
a master key to
evoke keys subcommands.
evoke keys lock will unwrap the master key then use
it to encrypt the Conjur keys. Similarly,
evoke keys unlock will
unwrap the master key, then use it to decrypt the Conjur keys and
put them in the kernel keyring.
# evoke keys encrypt Using NSS Internal Crypto Services library. Using NSS User Private Key and Certificate Services token. Using wrapping key ID 'CONJUR'. Unwrapping the key... Encrypted 9 key files and adjusted 3 symlinks # evoke keys lock Locked. Services and scripts can no longer access encrypted data. # evoke keys unlock Using NSS Internal Crypto Services library. Using NSS User Private Key and Certificate Services token. Using wrapping key ID 'CONJUR'. Unwrapping the key... Keys are unlocked. You may now 'sv start conjur' and follow the progress in syslog.