Adding a KMIP Host
DataStax Enterprise 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 dse.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 |
Procedure
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 DSE node.
-
Locate the
SSL key pair
generated by theKMIP
agent.
-
-
Convert the key pair from PEM to a DSE 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 DSE and change the file to allow the DSE 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
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 theKMIP
host in DSE related commands. -
hosts
: Comma separated list of Fully-Qualified Domain Names (FQDN
) ofKMIP
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 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 listing encryption keys on the remoteKMIP
server:dsetool managekmip list <kmip_group_name>
dsetool
picks updse.yaml
changes without requiring a restart.If problems connecting to the
KMIP
server occur, see TroubleshootingKMIP
connections. -
Repeat these steps on all nodes in the cluster.
-