Configure KMIP encryption
Set up encryption using keys from a Key Management Interoperability Protocol (KMIP
) host to protect sensitive configuration file properties, system resources, and tables.
DataStax recommends using |
Add a KMIP Host
Hyper-Converged Database (HCD) supports using encryption keys from one or more remote Key Management Interoperability Protocol (KMIP
) hosts to encrypt or decrypt table data or sensitive properties, or both, in the hcd.yaml
and cassandra.yaml
configuration files.
The location of each configuration file depends on the type of installation:
Filename | Package installations | Tarball installations |
---|---|---|
|
|
|
|
|
|
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 |
Set up a KMIP host
Perform all steps on every node in the cluster.
-
Set up
KMIP
agents and registered DSE with theKMIP
service:Refer to the
KMIP
key provider documentation for detailed steps.-
Download and install the
KMIP
agent. -
Connect to the
KMIP
host. -
Register the HCD node.
-
Locate the
SSL key pair
generated by theKMIP
agent.
-
-
Convert the key pair from PEM to an HCD compatible
JKS
format:-
Secure the
KMIP
agent private key files by removing read access for all users. For example, theVormetric DSM agents
creates two files namedkmip-key.pem
andkmip-<host_name>.pem
. -
Copy both keys to another directory, such as your
home
directory. -
Generate a
PKCS12
format file from thePEM
files:openssl pkcs12 -export -out <kmip_keystore>.p12 -inkey <kmip-key.pem> -in <kmip-host_name.pem>
Where
<kmip_keystore>.p12
is the output file name and<kmip-host_name.pem>
is part of the key pair created by theKMIP
agent.
-
Due to an OpenSSL issue, you cannot use a PKCS12 truststore that was generated via OpenSSL. For example, a truststore generated via the following command will not work with DSE:
openssl pkcs12 -export -nokeys -out truststore.pfx -in <intermediate.chain.pem>
However, truststores generated via Java’s keytool
and then converted to PKCS12 work with DSE.
Example:
keytool -importcert -alias <rootca> -file <rootca.pem> -keystore <truststore.jks>
keytool -importcert -alias <intermediate> -file <intermediate.pem> -keystore <truststore.jks>
keytool -importkeystore -srckeystore <truststore.jks> -destkeystore <truststore.pfx> -deststoretype pkcs12
-
Create a
JKS
keystore:keytool -importkeystore -destkeystore <kmip_keystore.jks> -srcstoretype PKCS12 -srckeystore <kmip_keystore.p12>
Where
-
<kmip_keystore.jks>
is the keystore file name that is created -
<kmip_keystore.p12>
is thePKC12
file generated in the previous stepEnter a password for the keystore at the prompt and fill out the host information.
-
-
Install the KMIP root certificate into the JKS truststore:
keytool -import -alias <kmipCA> -file <kmip-host_CA.pem> -keystore <kmip_truststore.jks>
Enter a password for the truststore at the prompt and fill out the host information.
-
Move the keystore and truststore to a directory accessible by HCD and change the file to allow the HCD account read/write access.
-
Delete or secure the files used to create the keystore and truststore.
-
Add the host details to the kmip_hosts section of the
hcd.yaml
:kmip_hosts: <kmip_group_name>: hosts: <FQDN>[, <FQDN> , ...] keystore_path: </etc/hcd/conf/kmip_keystore.jks> keystore_type: jks keystore_password: <password> truststore_path: </etc/hcd/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 theKMIP
host in HCD related commands. -
hosts
: Comma separated list of Fully-Qualified Domain Names (FQDN
) ofKMIP
hosts. HCD 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 HCD refreshes the key cache on the node in milliseconds. The default is300000
(five minutes). -
timeout: <N>
whereN
is the socket timeout in milliseconds. The default is1000
. -
protocol: <protocol>
for communicating between the node andKMIP
key server. When not specified,JVM
default is used. -
cipher_suites: supported_cipher
for communicating between the node andKMIP
key server. When not specified,JVM
default is used.
-
-
-
Verify that the node can connect to the
KMIP
host by testing the connection:HCD does not include a built-in tool for listing KMIP keys directly. You must use your KMIP server’s native management interface or API to verify the connection and list keys.
-
Using your KMIP server’s management interface or API, verify the connection and list available keys.
-
Using your KMIP server’s command-line tools (if available):
# Example using a generic KMIP client (actual command depends on your KMIP server) kmip-client list-keys --server <kmip_server_host> --port <kmip_port>
HCD picks up
hcd.yaml
changes without requiring a restart.If problems connecting to the
KMIP
server occur, see TroubleshootKMIP
connections.
-
-
Repeat these steps on all nodes in the cluster.
-
Encrypt KMIP system resources
Use a KMIP
key to encrypt the system.batchlog
and system.paxos
tables, hint
files and commit
logs.
Prerequisites
Complete the steps in Adding a KMIP
host.
If any of the defined |
Procedure
-
Locate the
hcd.yaml
configuration file. The location of this file depends on the type of installation:-
Package installations:
/etc/hcd/hcd.yaml
-
Tarball installations:
<installation_location>/resources/hcd/conf/hcd.yaml
-
-
In the
hcd.yaml
file, configure encryption settings for system tables, thecommit
log, and thehints
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, usenodetool upgradesstables
to apply encryption. -
key_provider
: Set toKmipKeyProviderFactory
. -
kmip_host
: Use the group name from thekmip_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. HCD supports the following algorithms:Supported cipher algorithm 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 default64
is used if the option is excluded. When these properties are set, HCD only uses a key that matches; if no matching key exists, start up fails.
-
-
-
To encrypt existing data, run
nodetool upgradesstables -a system batchlog paxos
on all nodes in the cluster.
Encrypt table data with KMIP keys
Encrypt data stored in a table using a Key Management Interoperability Protocol (KMIP
) key.
Prerequisites
Complete the steps in Adding a KMIP
host.
If any of the defined |
Use the hcd.yaml
file to encrypt table data
-
Locate the
hcd.yaml
configuration file. The location of this file depends on the type of installation:-
Package installations:
/etc/hcd/hcd.yaml
-
Tarball installations:
<installation_location>/resources/hcd/conf/hcd.yaml
-
-
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_keyspace': 'kmip_keyspace'], 'cipher_algorithm': 'AES/ECB/PKCS5Padding', 'secret_key_strength': 128 };
-
'key_provider': 'KmipKeyProviderFactory'
tells the encryptor to use aKMIP
key server to manage its encryption keys. Include the'key provider'
entry only to specify to use aKMIP
key server, otherwise omit this entry. -
'kmip_host': 'kmip_group_name' ['key_keyspace': 'kmip_keyspace'] specify an optional
KMIP
keyspace. Use keyspaces to allow granular management of 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 };
-
-
To encrypt a pre-existing table:
-
Change the table compression settings:
-
Encryption without compression:
ALTER TABLE customers ... WITH COMPRESSION = { 'class': 'Encryptor', 'key_provider': 'KmipKeyProviderFactory', 'kmip_host': 'kmip_group_name' ['key_keyspace': 'kmip_keyspace'], 'cipher_algorithm': 'AES/ECB/PKCS5Padding', 'secret_key_strength': 128 };
-
'key_provider': 'KmipKeyProviderFactory'
tells the encryptor to use aKMIP
key server to manage its encryption keys. Include the'key provider'
entry only to specify to use aKMIP
key server, otherwise omit this entry. -
['key_keyspace': 'kmip_keyspace'] specify an optional
KMIP
keyspace. Use keyspaces to allow granular management of keys on a per table or keyspace basis.
-
-
Compression and encryption:
ALTER TABLE customers ... WITH COMPRESSION = { 'class': 'EncryptingDeflateCompressor', 'key_provider': 'KmipKeyProviderFactory', 'kmip_host': 'kmip_group_name', 'cipher_algorithm': 'AES/ECB/PKCS5Padding', 'secret_key_strength': 128 };
-
-
Encrypt existing data on all nodes in the cluster:
nodetool upgradesstables -a [keyspace_name [table_name[ tablename]...]
-
Rekey tables using a new key
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 key_cache_millis
(default setting is 5
minutes).
To get a new key, either wait for the key cache refresh interval or perform a rolling restart.
HCD supports KMIP key management through direct KMIP server interaction. The KMIP commands affect encryption keys as follows: |
-
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 periodic switching of the encryption key.
-
revoke
: Permanently disables the key on theKMIP
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 theKMIP
server.Use this command as the first step when replacing a compromised key.
-
destroy
: Completely removes the key from theKMIP
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.
Procedure
-
Revoke the compromised key.
You must manage KMIP keys directly through your KMIP server’s interface or API. |
-
Get the ID of the KMIP encryption key you want to revoke from the
KMIP
server:-
Using your KMIP server’s management interface or API, list the available keys and their states.
-
Using your KMIP server’s command-line tools (if available):
# Example using a generic KMIP client (actual command depends on your KMIP server) kmip-client list-keys --server <kmip_server_host> --port <kmip_port>
The following is an example of a
KMIP
server that has two keys,active
anddeactivated
:ID Name Cipher State Activation Date Creation Date Protect Stop Date Keyspace 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 n/a
HCD supports one or more
KMIP
hosts. EachKMIP
host is defined under a user-defined<kmip_group_name>
in thekmip_hosts
section of thehcd.yaml
configuration file.The location of the
hcd.yaml
file depends on the type of installation:-
Package installations:
/etc/hcd/hcd.yaml
-
Tarball installations:
<installation_location>/resources/hcd/conf/hcd.yaml
-
-
-
Revoke the key you want to replace using the ID:
-
Using your KMIP server’s management interface or API, revoke the key with the specified ID.
-
Using your KMIP server’s command-line tools (if available):
# Example using a generic KMIP client (actual command depends on your KMIP server) kmip-client revoke-key --server <kmip_server_host> --port <kmip_port> --key-id <key_id>
Revoking permanently deactivates the key on the
KMIP
server. When the key cache refreshes, a new key for encryption or decryption is automatically created. Revoked keys are used to decrypt existing data. DO NOT destroy the revoked key until after re-encrypting the existing data.
-
-
Verify that the key State is
Deactivated
:-
Using your KMIP server’s management interface or API, verify the key state has changed to
Deactivated
. -
Using your KMIP server’s command-line tools (if available):
# Example using a generic KMIP client (actual command depends on your KMIP server) kmip-client list-keys --server <kmip_server_host> --port <kmip_port>
The following is an example of a
KMIP
server that has two keys:ID Name Cipher State Activation Date Creation Date Protect Stop Date Keyspace 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 Deactivated Tue May 31 12:57:59 UTC 2016 n/a Thu Jul 27 17:16:38 UTC 2017
-
Refresh the database key cache using one of the following methods:
-
-
Wait the amount of time specified in the
key_cache_millis
setting before continuing to the next step. -
Perform a rolling restart.
KMIP
keys are cached on the HCD node. HCD refreshes the cache and a new key is automatically generated by the KMIP server afterkey_cache_millis
lapses; the default setting is5
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
nodetool upgradesstables
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
-
Optional: Remove the encryption key so that it is no longer available for decryption:
-
-
Using your KMIP server’s management interface or API, destroy the key with the specified ID.
-
Using your KMIP server’s command-line tools (if available):
# Example using a generic KMIP client (actual command depends on your KMIP server) kmip-client destroy-key --server <kmip_server_host> --port <kmip_port> --key-id <key_id>
The backed up SSTables are only accessible using the old key. Ensure that the data is accessible before removing the key.
-
Troubleshoot KMIP connections
The following error message may occur if the HCD SSL certificate is self-signed or from a CA that has not been added to the certificate chain on the KMIP
server.
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 HCD and KMIP
host has been properly configured, see Creating local SSL certificate and keystore files.