Server key encryption methods

This topic describes the available methods for encrypting the server keys which include the data key, the Conjur UI key, and SSL keys.

Encrypt server keys using a master key file

During the initial configuration of the Leader Conjur Server (Leader), evoke configure master generates server keys and places them in /opt/conjur/etc and /opt/conjur/etc/ssl.

For example:

  • Database encryption key: possum.key
  • UI encryption key: ui.key
  • SSL private keys: conjur.key, ca.key

Use the evoke keys commands to encrypt the keys and unlock the encrypted keys to the Linux keyring and memory based file system.

 

  • The master key file (for example, master,key) must be kept secure. It is used to encrypt all the server keys.

  • The master key file and evoke keys encrypt are used together to encrypt and unlock the server keys. This means you must copy and secure the master key file yourself.

    Alternatively, you can use one of the other master key facilities described below.

  1. Configure the Leader:

    Log in to the Leader and run the following:

      
    # Configure the Conjur Leader
evoke configure master -h conjur-master.yourcorp -p password mycorp

# Lock the server keys 
evoke keys lock

# Generate a random master key. Keep this file secure
openssl rand 32 > /secrets/master.key

# Encrypt the server keys with the 32-byte master key
evoke keys encrypt /secrets/master.key

# Unlock the server keys and restart the Conjur services

evoke keys unlock /secrets/master.key

# In the log, you will see "Searching keyring for key" and "Read key for" for all Conjur services

    Once complete, the Leader runs and uses the secured keys.

    The /opt/conjur/etc directory now contains only the encrypted server keys.

    Note the enc suffix:

    • possum.key.enc

    • ui.key.enc

    • conjur.key.enc, ca.key.enc (in /opt/conjur/etc/ssl)

    Now that the keys are encrypted, they must be unlocked before starting any services. Unlocking is required on every server/VM/container boot or restart. The key must be provided by the administrator.

  2. Configure a high availability (HA) cluster:

    The basic process for setting up a Standby/Follower in an HA cluster involves:

    • Creating the server keys on the Leader
    • Encrypting the server keys
    • Generating a Standby/Follower seed file on the Leader
    • Transferring the seed file to the Standby/Follower
    • Unpacking the seed file on the Standby/Follower and configuring the Standby/Follower

    Because the seed file contains 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.

    An HA cluster includes a Leader, Standbys, and Followers. The following procedure describes setting up a Follower but the process is the same for the other types of cluster nodes - simply replace the word follower with standby.

    1. Generate a Follower seed on the Leader

      Run the following commands on the Leader. The example assumes the master key file , master.key, created when configuring the Leader) is located in /secrets/.

        
      # Generate the certificate for the Follower
evoke keys decrypt-all /secrets/master.key
evoke ca issue conjur-east.yourcorp

# Encrypt the keys
evoke keys encrypt /secrets/master.key

# Create a secure seed file on the Leader
evoke seed follower conjur-east.yourcorp conjur-master.yourcorp > /seed/conjur-east.yourcorp.tar

    2. Copy files to the Follower

      Transfer conjur-east.yourcorp.tar to the Follower. Transfer /secrets/master.key to the Follower.

    3. Load the seed file on the Follower:

        
      # Unpack the Follower seed file
evoke unpack seed /seed/conjur-east.yourcorp.tar

# Configure the Follower
evoke keys exec -m /secrets/master.key -- evoke configure follower
     

    For an HA configuration, the evoke seed follower command ensures that the encrypted keys in /opt/conjur/etc are included in the seed file created on the Leader.

    It is not necessary to use the evoke keys encrypt command on the Follower because the keys are already encrypted in the seed file. However, prior to starting the service on the Follower you do need to use evoke keys unlock, or evoke keys exec, with the same master key used to encrypt the server keys on the Leader.

Backup and restore with a master key file

After encrypting the server keys, you must provide the master key file to use evoke restore.

This example assumes you have put the master key file, master.key, created when configuring the Leader, into /secrets/:

  
# Back up the Leader
evoke backup

# Copy the files from the backup directory
cp /opt/conjur/backup/* /backup

 

  
# Restore from backup
evoke unpack backup --key /backup/key /backup/<date-time>.tar.xz.gpg
evoke keys exec -m /secrets/master.key -- evoke restore

Encrypt the master key using AWS KMS

You can encrypt the master key using the Amazon Key Management Service (AWS KMS) master key facility.

  1. Create a KMS customer master key (CMK) using your preferred interface (for example: CLI, web console etc).

    This CMK must meet the following criteria:

    • The key must be symmetric.

    • The key policy must allow the role that deploys the Conjur node in EC2 to decrypt the KMS key, as shown in the following example:

      
              {

  "Version": "2012-10-17",
  "Id": "conjur-key-policy-<region>",
  "Statement": [
    {
      "Sid": "Allow use of the key by Conjur",
      "Effect": "Allow",
      "Principal": {
        "AWS": "<arn of role deploying Conjur>"
      },
      "Action": "kms:Decrypt",
      "Resource": "*"
    },
    {
      "Sid": "Allow access for Key Administrators",
      "Effect": "Allow",
      "Principal": {
        "AWS": "<arn of key administrator>"
      },
      "Action": [
        "kms:*",
      ],
      "Resource": "*"
    }
  ]
}
     

    Be sure to follow your organization's best practices and security policies when defining your AWS IAM policy for the key.

    AWS CLI example

    The following example uses the AWS CLI to create the CMK, however, the web console can also be used. For more information, see the AWS KMS documentation.

      
    aws kms create-key --policy <value> --description "Conjur regional master key encryption key" --key-usage "ENCRYPT_DECRYPT"

  2. Encrypted Conjur master keys are stored as ciphertextBlobs.

    1. Set the key_spec to 'AES_256'.

    2. Run generate_data_key_without_plaintext against the KMS CMK created in Server key encryption methods.

    AWS CLI example

    The following example uses the AWS CLI to generate an encrypted master key, however, the web console can also be used. For more information, see the AWS KMS documentation.

      
    aws kms generate-data-key-without-plaintext --key-id <arn of KMS key> --key-spec "AES_256" --encryption-context KeyType="Conjur master key"

  3. This procedure should be performed by a Conjur administrator.

    Run the evoke keys kms set command to import the ciphertextBlob into the Conjur node.

     

    The KMS key and the role associated with the Conjur node must be in the same AWS region.

  4. This procedure should be performed by a Conjur administrator.

    Run the evoke keys encrypt command.

     

    evoke keys encrypt locates its region either from the environment variable AWS_REGION or from the identity documents.

    The credentials for an AWS role can be retrieved from the role that deployed the Conjur node. For additional methods for retrieving these credentials, see the AWS documentation.

    For more information, see Evoke command reference.

Encrypt the master key using an HSM (4.9.2.0+)

Conjur supports the use of a PKCS#11-compliant hardware security module (HSM) to securely manage the master key (master.key). The evoke pkcs11 subcommand uses the HSM to:

  • generate a key encryption key
  • wrap (i.e. encrypt) the master key (master.key) with the key encryption key
  • encrypt the service keys with the master key
  • store the wrapped master key

The key encryption key never leaves the HSM.

Once the master key has been wrapped, the evoke keys subcommands use the HSM to unwrap it when performing their respective functions.

Terminology

These are some of the terms specific to using an HSM.

Term

Description
Hardware security module (HSM)

According to 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 that is generated and maintained by the HSM, and is used to encrypt other keys.

Security token

Often shortened to "token", this is a storage device that plugs in to 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:

  • Obtaining a Linux x86_64 shared library for your HSM, and copying it to the Conjur Server.

  • Configuring Conjur's PKCS#11 support to use the shared library

  • Having the HSM generate a new key encryption key

  • Wrapping the master key (optionally generating a new one) with the key encryption key

  • Encrypting the server keys with the master key

Configure the appliance

To use an HSM with Conjur, you must first obtain the Linux x86_64 shared library appropriate for your HSM. Copy it to the Conjur Server.

Once you have the shared library, you must create the file /opt/conjur/etc/pkcs11.yml and add configuration information to it.

Next, validate that the file has the appropriate permissions:

  
chmod 600 /opt/conjur/etc/pkcs11.yml

This command validates that only the owner has read and write permissions on the file.

The following settings can appear in the file:

Element

Description

library

Full path to the shared object containing the PKCS#11 module to use.

Required

wrapping_key

Module ID of the key used to wrap the master key. If you choose to generate a key encryption key, it will be stored with this ID.

Required

parameters

A hash or a string with additional parameters to be passed to the module.

Optional

slot

Index of the HSM slot containing the token to use (zero-based). If omitted, the first slot supporting key storage is automatically used.

Optional

pin

PIN for logging into the module. If omitted, an empty password is assumed.

Optional

As an example, this pkcs11.yml file configures the Conjur Server to use the NSS Softoken Cryptographic Module. Softoken, available as part of the 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

Generate 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.

 

For help on this function, run:

# evoke pkcs11 generate --help

Wrap the master key

After creating the key encryption key, use evoke pkcs11 wrap to wrap the master key.

If you have previously encrypted your keys, you will need to provide that master key. Otherwise, evoke pkcs11 wrap will generate a new random 32-byte master key.

 

For help on this function, run:

# evoke pkcs11 wrap --help

Use the wrapped master key

Once the master key has been wrapped, you no longer need to provide a master key to evoke keys subcommands.

For example, evoke keys lock will unwrap the master key, and then use it to encrypt the server keys. Similarly, evoke keys unlock will unwrap the master key, and then use it to decrypt the server keys and put them in the kernel keyring.

For example:

  
# 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.