Adding a KMIP host

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.


Perform all steps on every node in the cluster.

  1. 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.

  2. 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.

    4. Create a JKS keystore:

      keytool -importkeystore -destkeystore <kmip_keystore.jks> -srcstoretype PKCS12 -srckeystore <kmip_keystore.p12>


      • <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.

    5. 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.

    6. Move the keystore and truststore to a directory accessible by DSE and change the file to allow the DSE account read/write access.

    7. Delete or secure the files used to create the keystore and truststore.

  3. Add the host details to the kmip_hosts section of the dse.yaml:

        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 step 2.

      • keystore_type: jks Keystore format. Must be set to jks.

      • keystore_password: Password of the keystore file created in step 2.

      • truststore_path: Location of the truststore file created in step 2.

      • truststore_type: jks Truststore format. Must be set to jks.

      • truststore_password: Password of the truststore file created in step 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: https:/[supported_cipher] for communicating between the node and KMIP key server. When not specified, JVM default is used.

  4. 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.

  5. Repeat steps on all nodes in the cluster.

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2024 DataStax | Privacy policy | Terms of use

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: +1 (650) 389-6000,