Set up local encryption keys for production environments

The location of the hcd.yaml file depends on the type of installation:

  • Package installations: /etc/hcd/hcd.yaml

  • Tarball installations: <installation_location>/resources/dse/conf/hcd.yaml

Prerequisites

To ensure support for all encryption algorithms, enable JCE.

Starting in JDK 8u161, JCE Unlimited is enabled by default. Refer to the Release Notes for JDK 8u161.

Procedure

  1. If the directory does not exist, create the /conf directory based on your HCD installation type:

    • Package installation: /etc/hcd/conf

    • Tarball installation: <installation_location>/resources/dse/conf

  2. Configure the file name and the location of the encryption key in the hcd.yaml file:

    1. Set system_key_directory property to the path where you want to store the encryption keys.

      system_key_directory: /etc/hcd/conf
    2. Change the directory owner to the HCD account and ensure that the HCD account has read/write permissions.

    3. Set the config_encryption_key_name to the <key_name>. The default name is system_key.

      config_encryption_key_name: system_key

      Encryption key files can have any valid Unix name.

  3. Go to the directory specified by the system_key_directory property in your hcd.yaml file:

    For example:

    cd /etc/hcd/conf
  4. Create an encryption key using the nodetool createsystemkey command:

    nodetool createsystemkey 'AES/ECB/PKCS5Padding' 128 KEY_NAME

    Replace KEY_NAME with the name of the key file to create. You can use any valid Unix name for encryption key files. If you don’t specify a name, the system creates the key file as system_key.

    If you set config_encryption_active to true in the hcd.yaml file, the system generates a warning, but the system key still successfully generates.

    HCD supports the following JCE cipher algorithms and corresponding length:

    • cipher_algorithm[/mode/padding]

      HCD supports the following JCE cipher algorithms:

      • AES/CBC/PKCS5Padding (valid with length 128)

      • AES/ECB/PKCS5Padding (valid with length 128)

        Only AES algorithms with 128-bit key strength are supported in HCD 1.2.

  1. Copy the key file to all other nodes in the cluster. Put keys on all nodes in the same directory.

  2. Update the system_key_directory and config_encryption_key_name in the hcd.yaml file.

    nodetool reads current values from the hcd.yaml. A restart is not required to continue setting up encryption.

  3. Ensure that the DSE account owns the key files and has read/write access on them. If necessary, change the ownership of the file to the DSE user.

    chown cassandra /etc/hcd/conf/system_key

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2025 DataStax | Privacy policy | Terms of use | Manage Privacy Choices

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, info@datastax.com