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 your installation type.

Configuration file location
Filename	Package installations	Tarball installations
`cassandra.yaml`	`/etc/hcd/cassandra/cassandra.yaml`	`<installation_location>/resources/cassandra/conf/cassandra.yaml`
`hcd.yaml`	`/etc/hcd/hcd.yaml`	`<installation_location>/resources/hcd/conf/hcd.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.

Set up a KMIP host

Perform all steps on every node in the cluster.

Set up KMIP agents and registered HCD 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 HCD node.
4. Locate the SSL key pair generated by the KMIP agent.
Convert the key pair from PEM to an HCD 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 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.
1. 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 the KMIP host in HCD related commands.
    
    hosts: Comma separated list of Fully-Qualified Domain Names (FQDN) of KMIP 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 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 HCD 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 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 Troubleshoot KMIP connections.
3. Repeat these steps on all nodes in the cluster.

Add a KMIP Host

Set up a KMIP host

Was this helpful?

Give Feedback