Configuring KMIP encryption
Protect sensitive data using encryption keys from a remote KMIP (Key Management Interoperability Protocol).
Adding a KMIP host
Configure a KMIP host to use a key from that remote server to encrypt and decrypt table or configuration properties.
DataStax Enterprise supports using encryption keys from one or more remote KMIP hosts to encrypt/decrypt table data and/or sensitive properties in the dse.yaml and cassandra.yaml configuration files. Follow these steps to add a KMIP server information to the list of available hosts.
DataStax recommends limiting the number of nodes that can remotely manage KMIP keys using a security policy on the KMIP host.
cassandra.yaml
The location of the cassandra.yaml file depends on the type of installation:Package installations | /etc/dse/cassandra/cassandra.yaml |
Tarball installations | installation_location/resources/cassandra/conf/cassandra.yaml |
dse.yaml
The location of the dse.yaml file depends on the type of installation:Package installations | /etc/dse/dse.yaml |
Tarball installations | installation_location/resources/dse/conf/dse.yaml |
Procedure
-
Set up KMIP agents and registered DSE with the KMIP service:
Note: Refer to the KMIP key provider documentation for detailed steps.
- Download and install the KMIP agent.
- Connect to the KMIP host.
- Register the DSE node.
- Locate the SSL key pair generated by the KMIP agent.
-
Convert the key pair from PEM to a DSE compatible JKS format:
-
Add the host details to the kmip_hosts section
of the dse.yaml:
kmip_hosts: kmip_group_name: hosts: FQDN[, FQDN , ...] keystore_path: /etc/dse/conf/kmip_keystore.jks keystore_type: jks keystore_password: password truststore_path: /etc/dse/conf/kmip_truststore.jks truststore_type: jks truststore_password: password key_cache_millis: N timeout: N protocol: protocol cipher_suites: supported_cipher
- Required settings:
- kmip_group_name: User-defined group name that identifies the KMIP host in DSE related commands.
hosts
: Comma separated list of fully qualified domain names (FQDN) of KMIP hosts. DSE tries the hosts in the order listed.keystore_path
: Location of the keystore created in 2.keystore_type: jks
Keystore format. Must be set tojks
.keystore_password
: Password of the keystore file created in 2.truststore_path
: Location of the truststore file created in 2.truststore_type: jks
Truststore format. Must be set tojks
.truststore_password
: Password of the truststore file created in 2.
- Optional settings:
key_cache_millis: N
where N is the interval at which DSE refreshes the key cache on the node in milliseconds. The default is 300000 (five minutes).timeout: N
where N is the socket timeout in milliseconds. The default is 1000.protocol: protocol
for communicating between the node and KMIP key server. When not specified, JVM default is used.cipher_suites: supported_cipher
for communicating between the node and KMIP key server. When not specified, JVM default is used.
- Required settings:
-
Verify that the node can connect to the KMIP host by listing encryption keys on
the remote KMIP server:
dsetool managekmip list kmip_group_name
Note:If problems connecting to the KMIP server occur, see Troubleshooting KMIP connections.dsetool
picks up dse.yaml changes without requiring a restart. - Repeat steps on all nodes in the cluster.
Encrypting configuration file properties
Protect LDAP search and truststore passwords in the dse.yaml and SSL truststore passwords in the cassandra.yaml using a KMIP key from a remote host.
-
dse.yaml LDAP values:
ldap_options.search_password ldap_options.truststore_password
Restriction: Use plain text for the KMIP keystore or truststore passwords. -
cassandra.yaml SSL values:
server_encryption_options.keystore_password server_encryption_options.truststore_password client_encryption_options.keystore_password client_encryption_options.truststore_password
cassandra.yaml
The location of the cassandra.yaml file depends on the type of installation:Package installations | /etc/dse/cassandra/cassandra.yaml |
Tarball installations | installation_location/resources/cassandra/conf/cassandra.yaml |
dse.yaml
The location of the dse.yaml file depends on the type of installation:Package installations | /etc/dse/dse.yaml |
Tarball installations | installation_location/resources/dse/conf/dse.yaml |
Prerequisites
Procedure
- Back up the configuration files.
-
Get the URL of the KMIP encryption key:
- To create a new key and get the
URL:
dsetool createsystemkey 'AES/ECB/PKCS5' 128 -k kmip_group_name
The example output shows the URL for thehost_name
in the dse.yaml with ID: 02-1655.kmip://host_name/02-1655
- To use an existing KMIP key, the URL syntax is
kmip://kmip_group_name/ID
. To look up the key ID:dsetool managekmip list kmip_group_name
For example, thehost_name
has the following keys:
The URL of the second key in the list isKeys on host_name: ID Name Cipher State Activation Date Creation Date Protect Stop Date Namespace 02-449 82413ef3-4fa6-4d4d-9dc8-71370d731fe4_0 AES/CBC/PKCS5 Deactivated Mon Apr 25 20:25:47 UTC 2016 n/a n/a n/a 02-540 0eb2277e-0acc-4adb-9241-1dd84dde691c_0 AES Active Tue May 31 12:57:59 UTC 2016 n/a n/a`
kmip://host_name/02-540
.
- To create a new key and get the
URL:
-
Configure system property
encryption settings in the
dse.yaml.
-
For each property, replace plain text passwords with encrypted passwords
returned by running the
command:
- Optional. Set up system resource encryption.
- Perform a rolling restart.
Encrypting system resources
Use a KMIP key to encrypt the system.batchlog and system.paxos tables, hint files and commit logs.
Use a KMIP key to encrypt the system.batchlog and system.paxos tables, hint files and commit logs.
dse.yaml
The location of the dse.yaml file depends on the type of installation:Package installations | /etc/dse/dse.yaml |
Tarball installations | installation_location/resources/dse/conf/dse.yaml |
Prerequisites
Procedure
-
In the dse.yaml file, configure encryption
settings for system tables, the commit log, and the hints files.
system_info_encryption: enabled: ( true | false ) cipher_algorithm: cipher_name secret_key_strength: length key_provider: KmipKeyProviderFactory kmip_host: kmip_group_name chunk_length_kb: 64
- Required properties:
-
enabled
: Set totrue
. On the next startup, system resources are encrypted. If the system tables have existing data, use nodetool upgradesstables to apply encryption. key_provider
: Set toKmipKeyProviderFactory
.kmip_host
: Use the group name from the kmip_hosts section.
-
- Optional. To ensure that KMIP generates a compatible key, configure the
type of encryption key to use:
cipher_algorithm
: Set the name of a supported JCE cipher algorithm to use. DSE supports the following algorithms:Table 1. Supported cipher algorithms names cipher_algorithm secret_key_strength AES 128, 192, or 256 DES 56 DESede 112 or 168 Blowfish 32-448 RC2 40-128 secret_key_strength
: Specify the key length.chunk_length_kb
: Configures chuck size for SSTables. The default (64) is used if the option is excluded.
- Required properties:
- Perform a rolling restart.
-
To encrypt
existing data, run
-a system batchlog paxos
on all nodes in the cluster.
Encrypting table data
Encrypt data stored in a table data using a KMIP key.
Encrypt data stored in a table data using a KMIP key.
dse.yaml
The location of the dse.yaml file depends on the type of installation:Package installations | /etc/dse/dse.yaml |
Tarball installations | installation_location/resources/dse/conf/dse.yaml |
Prerequisites
Procedure
-
To create a new encrypted table using a key from a KMIP
server:
- Encryption without
compression:
CREATE TABLE customers ... WITH COMPRESSION = { 'class': 'Encryptor', 'key_provider': 'KmipKeyProviderFactory', 'kmip_host': 'kmip_group_name' ['key_namespace' = 'kmip_namespace'], 'cipher_algorithm': 'AES/ECB/PKCS5Padding', 'secret_key_strength': 128 };
-
'key_provider': 'KmipKeyProviderFactory'
tells the encryptor to use a KMIP key server to manage its encryption keys. Include the'key provider'
entry only to specify to use a KMIP key server, otherwise omit this entry. 'kmip_host': 'kmip_group_name'
specifies the user-defined KMIP key server group name defined in the kmip_hosts section of the dse.yaml file.- 'kmip_host': 'kmip_group_name' ['key_namespace' = 'kmip_namespace'] specify an optional KMIP namespace. Using namespaces allows you to granularly manage keys on a per table or keyspace basis.
-
- Compression and
encryption:
CREATE TABLE customers ... WITH COMPRESSION = { 'class': 'EncryptingDeflateCompressor', 'key_provider': 'KmipKeyProviderFactory', 'kmip_host': 'kmip_group_name', 'cipher_algorithm': 'AES/ECB/PKCS5Padding', 'secret_key_strength': 128 };
- Encryption without
compression:
-
To encrypt an already existing table:
nodetool upgradesstables -a [keyspace_name [table_name[ tablename]...]
Expiring an encryption key
Change the KMIP key used for encrypting data, without changing the key used for decryption.
Security policies generally limit the amount of time an encryption key is in use; this section describes how to expire a key without re-encrypting the exiting data. After a key expires, it is no longer used to encrypt new data, but is still used to decrypt existing data.
dse.yaml
The location of the dse.yaml file depends on the type of installation:Package installations | /etc/dse/dse.yaml |
Tarball installations | installation_location/resources/dse/conf/dse.yaml |
Procedure
-
Get a list of the available keys and states from the KMIP server:
dsetool managekmip list kmip_group_name
For example, the host_group has two keys:Keys on host_group: ID Name Cipher State Activation Date Creation Date Protect Stop Date Namespace 02-449 82413ef3-4fa6-4d4d-9dc8-71370d731fe4_0 AES/CBC/PKCS5 Deactivated Mon Apr 25 20:25:47 UTC 2016 n/a n/a n/a 02-540 0eb2277e-0acc-4adb-9241-1dd84dde691c_0 AES Active Tue May 31 12:57:59 UTC 2016 n/a n/a
Note: DSE supports one or more KMIP hosts. Each KMIP host is defined under a user-defined kmip_group_name in the kmip_hosts section of the dse.yaml. -
Expire the key:
- Immediately expire the
key:
dsetool managekmip expirekey kmip_group_name key_id
- Schedule an expiration
date:
dsetool managekmip expirekey kmip_group_name key_id datetime
Note: After the key expires, the database gets a new key for encryption the next time it refreshes the key cache (); the default setting is five minutes. Expired keys are still available to decrypt data.
- Immediately expire the
key:
- Optionally, force a refresh of the DSE key cache by performing a rolling restart.
Rekeying tables using a new key
Revoke a compromised key that is currently used to encrypt table data and use a new key to re-encrypt existing data.
Change the encryption key that is used for both encrypting new data and decrypting the existing data. Use these steps to secure the data after an event that potentially compromised an encryption key, such as a change in security administration staff. Before destroying the old key, revoke the compromised KMIP key, wait for the database key cache refresh, and then re-encrypt existing SSTables with the new key.
The database caches the encryption keys and refreshes the cache at an interval set by the (default setting is 5 minutes). To get a new key, either wait for the key cache refresh interval or perform a rolling restart.
expirekey
: Database stops using the key for encryption at the specified time and continues to use the expired key to decrypt existing data. Data re-keying is not required.Use this command to satisfy security policies that require periodically switching the encryption key.
revoke
: Permanently disables the key on the KMIP server. Database can no longer use the key for encryption, but continues to use the key for decryption of existing data. Re-encrypt existing data before completely removing the key from the KMIP server.Use this command as the first step when replacing a compromised key.
destroy
: Completely removes the key from the KMIP server. Database can no longer use the key for encryption or decryption. Existing data that has not been re-encrypted becomes inaccessible.Use this command only after revoking a key and re-encrypting existing data.
dse.yaml
The location of the dse.yaml file depends on the type of installation:Package installations | /etc/dse/dse.yaml |
Tarball installations | installation_location/resources/dse/conf/dse.yaml |
Procedure
- Back up SSTables.
-
Revoke the compromised key using the :
-
Refresh the database key cache using one of the following methods:
- Wait the amount of time specified in the setting before continuing to the next step.
- Perform a rolling restart, see .
Note: KMIP keys are cached on the DSE node. DSE refreshes the cache and a new key is automatically generated by the KMIP server after lapses; the default setting is 5 minutes. -
(Optional) Get a list of the affected tables to re-encrypt using the new key
using the DESC keyspace command:
For example to find all tables in the cycling keyspace that use the KMIP group:
DESC KEYSPACE cycling
-
Use to rewrite the encrypted SSTables
using the new key. Run the following command on every node in the cluster:
- Target only specific
tables:
nodetool upgradesstables --include-all-sstables keyspace_name table_name [table_name …]
- Target specific
keyspace:
nodetool upgradesstables --include-all-sstables keyspace_name
- All keyspaces and
tables:
nodetool upgradesstables --include-all-sstables
- Target only specific
tables:
-
(Optional) Remove the encryption key so that it is no longer available for
decryption:
dsetool managekmip destroy key_id
Warning: The backed up SSTables are only accessible using the old key. Ensure that the data is accessible before removing the key.
Troubleshooting KMIP connections
Unable to connect to KMIP host error
WARN 14:46:42,928 Unable to connect to KMIP host: 10.120.15.100:9005
com.cryptsoft.kmip.TTLVReadException: Error reading TTLV ResponseMessage. Got end-of-stream after reading 0 byte(s). Read bytes: (0) []
Ensure that trust between DSE and KMIP host has been properly configured, see Creating local SSL certificate and keystore files.