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:

Configuration File Location
Filename	Package installations	Tarball installations
`cassandra.yaml`	`/etc/dse/cassandra/cassandra.yaml`	`<installation_location>/resources/cassandra/conf/cassandra.yaml`
`dse.yaml`	`/etc/dse/dse.yaml`	`<installation_location>/resources/dse/conf/dse.yaml`

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.

Procedure

Perform all steps on every node in the cluster.

Set up KMIP agents and registered DSE with the KMIP service:

Refer to the KMIP key provider documentation for detailed steps.
1. Download and install the KMIP agent.
2. Connect to the KMIP host.
3. Register the DSE node.
4. Locate the SSL key pair generated by the KMIP agent.
Convert the key pair from PEM to a DSE compatible JKS format:
1. Secure the KMIP agent private key files by removing read access for all users. For example, the Vormetric DSM agents creates two files named kmip-key.pem and kmip-<host_name>.pem.
2. Copy both keys to another directory, such as your home directory.
3. Generate a PKCS12 format file from the PEM 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 the KMIP 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 the PKC12 file generated in the previous step
  
  Enter 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.
1. 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 to jks.
    
    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 to jks.
    
    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.
2. 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>
  dsetool picks up dse.yaml changes without requiring a restart.
  
  If problems connecting to the KMIP server occur, see Troubleshooting KMIP connections.
3. Repeat these steps on all nodes in the cluster.

Adding a KMIP Host

Procedure

Was this helpful?

Give Feedback