Encrypting using off-server encryption keys

Configure KMIP (Key Management Interoperability Protocol) encryption to use encryption keys that are stored on another server.

1. Back up SSTables.
2. Set the system_key_directory property in the dse.yaml file.
   • On a packaged installation, accept the default system_key_directory: /etc/dse/conf. Go to the next step to set permissions on the directory.
   • On a tarball installation, optionally change the directory on each node in the cluster from /etc/dse/conf to another directory, or skip this step and adjust permissions as described in the next step. You must configure the path to the system key to relocate the key to a directory that you have permission to access.
     • Navigate to install-directory/resources/dse/conf.
     • Open the dse.yaml file for editing.
     • Change the path of the system_key_directory to the path of a directory that you have permission to access.
3. Set permissions on the directory that is set for the system_key_directory property in the dse.yaml file to give rights to change the keytab file only to the user role that is running DataStax Enterprise. JNA takes care of setting these permissions.
4. Ensure that the role who encrypts data has been granted ALTER permission on the table that contains the data to be encrypted. You can use LIST PERMISSIONS to view the permissions that are granted to a role.
5. Perform host configuration for one or more KMIP key server groups.
   1. Configure the KMIP key manager and authorize each DataStax Enterprise node to the KMIP key server group. Consult the KMIP key server documentation.
   2. On each DataStax Enterprise node, open the dse.yaml file in a text editor and configure the KMIP key server group or key server groups in the kmip_hosts section. Create a user-defined name for a group of options to configure a KMIP server or servers, key settings, and certificates. Configure options for a kmip_groupname section for each KMIP key server or group of KMIP key servers. Using separate key server configuration settings allows use of different key servers to encrypt table data, and eliminates the need to enter key server configuration information in DDL statements and other configurations. Multiple KMIP hosts are supported.

   Option	Description
   hosts	A comma-separated list of hosts[:port] for the KMIP key server. There is no load balancing. In failover scenarios, failover occurs in the same order that servers are listed. For example: hosts: kmip1.yourdomain.com, kmip2.yourdomain.com
   keystore_path	The path to a java keystore that identifies the DSE node to the KMIP key server. For example: /path/to/keystore.jks
   keystore_type	The type of key store. The default value is jks.
   keystore_password	The password to access the key store.
   truststore_path	The path to a java truststore that identifies the KMIP key server to the DataStax Enterprise node. For example: /path/to/truststore.jks
   truststore_type	The type of truststore. The default value is jks.
   truststore_password	The password to access the truststore.
   key_cache_millis	Milliseconds to locally cache the encryption keys that are read from the KMIP hosts. The longer the encryption keys are cached, the fewer requests are made to the KMIP key server, but the longer it takes for changes, like revocation, to propagate to the DataStax Enterprise node. DataStax Enterprise uses concurrent encryption, so multiple threads fetch the secret key from the KMIP key server at the same time. Default: 300000. DataStax recommends using the default value.
   timeout	Socket timeout in milliseconds. Default: 1000.

   This example shows configuration settings for Vormetric and Thales key servers:

   kmip_hosts:  
     vormetricgroup:
       hosts: vormetric1.mydomain.com, vormetric2.mydomain.com, vormetric3.mydomain.com 
       keystore_path: pathto/kmip/keystore.jks
       keystore_type: jks
       keystore_password: password
       truststore_path: pathto/kmip/truststore.jks
       truststore_type: jks
       truststore_password: password
       
     thalesgroup:
       hosts: thales1.mydomain.com, thales2.mydomain.com
       keystore_path: pathto/kmip/keystore.jks 
       keystore_type: jks
       keystore_password: password
       truststore_path: pathto/kmip/truststore.jks 
       truststore_type: jks
       truststore_password: password

6. On each DataStax Enterprise node, confirm communication with the KMIP key server and restart the node.
   1. Use the dsetool utility to confirm communication.

      $ dsetool managekmip list kmip_groupname

   2. After communication between the DataStax Enterprise node and the KMIP key server or servers is verified, restart the node. Repeat this step on each node.
      The DataStax Enterprise node will not start if it cannot connect to the configured KMIP key server.
7. Set and use KMIP as the encryption key provider.
   1. Set KMIP encryption options when you create a table or alter an existing table.
   2. Optional: Configure password encryption to encrypt stored passwords in the configuration files. Use dsetool to generate the required URL:

      dsetool createsystemkey 'AES/ECB/PKCS5' 128 -k kmip_groupname

      Edit the dse.yaml file in a text editor. For the config_encryption_key_name property, paste the URL that is returned from the dsetool createsystemkey utility. See Encrypting sensitive property values.
   3. Optional: Configure system table encryption to encrypt system tables that contain sensitive information, including the Cassandra commit log. Edit the dse.yaml file in a text editor. In the system_info_encryption section, comment out key_name if it exists, and uncomment or add key_provider and kmip_host:

      system_info_encryption:   
        enabled: false
        cipher_algorithm: AES
        secret_key_strength: 128
        chunk_length_kb: 64
        key_provider: KmipKeyProviderFactory
        kmip_host: kmip_groupname

      Use key_provider: KmipKeyProviderFactory only to specify a KMIP key server.
8. Use the dsetool managekmip command to manage encryption keys that are stored on the KMIP key server. See Managing off-server encryption keys.
9. Rewrite all SSTables using nodetool upgradesstables --include-all-sstables to immediately store the tables on disk.