Configure SSL for client-to-node connections

Client-to-node encryption protects in-flight data from client machines to a database cluster using SSL (Secure Sockets Layer), and it establishes a secure channel between the client and the coordinator node.

SSL on DSE Search nodes

On a DSE Search node, enabling SSL for the database automatically enables SSL in the DSE Search web.xml file and configures an SSL connector in Tomcat using the authentication or authorization filters. No changes are required for the web.xml or server.xml files.

If the TomcatSolrRunner does not find a connector in server.xml, it creates a default connector. The default connector binds to the native_transport_address.

The default location of the Tomcat server.xml file depends on the installation type:

  • Package installations: /etc/dse/tomcat/conf/server.xml

  • Tarball installations: <installation_location>/resources/tomcat/conf/server.xml

SSL without JCE Unlimited Strength Jurisdiction Policy

Starting in JDK 8u161, JCE Unlimited is enabled by default, which includes AES-256.

If you aren’t using the JCE Unlimited Strength Jurisdiction Policy, make sure that your ticket granting principal doesn’t use AES-256.

If your ticket granting principal uses AES-256, you might see a warning in the logs such as the following:

WARN [StreamConnectionEstablisher:18] 2015-06-22 14:12:18,589 SSLFactory.java (line 162) Filtering out
TLS_DHE_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA as it isnt supported by the socket

Enable SSL on nodes

Complete the following steps on every node in the cluster to configure SSL for client-to-node connections:

  1. Create SSL certificates, keystores, and truststores. You can either create local keystore files or use a remote keystore provider.

  2. Locate the cassandra.yaml configuration file. The location of this file depends on the type of installation:

    • Package installations: /etc/dse/cassandra/cassandra.yaml

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

  3. Edit cassandra.yaml and make the following changes in the client_encryption_options to enable SSL:

    1. Set enabled to true to enable SSL.

    2. Set optional to false (default) to only allow SSL connections.

    3. Set require_client_auth to true to require two-way host certificate validation.

  4. Configure the keystore and truststore, depending on whether you are using local keystore files or a remote keystore provider. All settings are configured in the client_encryption_options section of cassandra.yaml.

    Be aware that the store_type option is deprecated. Instead, use keystore_type and truststore_type.

    • Local files

    • Remote keystore provider

    Use the following settings:

    client_encryption_options:
    enabled: true
    optional: false
    keystore_type: JKS
    keystore: <path_to_keystore>
    keystore_password: <keystore_password>
    require_client_auth: true
    truststore_type: JKS
    truststore: <path_to_truststore>
    truststore_password: <truststore_password>
    protocol: ssl
    algorithm: SunX509
    cipher_suites: [TLS_RSA_WITH_AES_128_CBC_SHA]
    enabled

    Enables client-to-node encryption. You must also generate keys and provide the appropriate key and truststore locations and passwords. There are no custom encryption options enabled for DataStax Enterprise (DSE).

    Default: false

    optional

    When optional is true, both encrypted and unencrypted connections over native transport are allowed. This is a necessary transition state to facilitate enabling client to node encryption on live clusters without inducing an outage for existing unencrypted clients. Typically, once existing clients are migrated to encrypted connections, optional is set to false to enforce native transport encryption.

    Default: false

    keystore_type

    Valid types are JKS (default), JCEKS, PKCS11, or PKCS12. For file-based keystores, use PKCS12.

    DataStax supports PKCS11 as a keystore_type on nodes with cassandra or advanced workloads.

    If you need to use PKCS11, you must specify the keystore_type as PKCS11 and the keystore as NONE in either server_encryption_options or client_encryption_options depending on your use case.

    PKCS11 isn’t supported as a truststore_type.
    keystore

    Relative path from the DSE installation directory or the absolute path to the Java keystore (JKS) suitable for use with Java Secure Socket Extension (JSSE) (the Java version of the Secure Sockets Layer (SSL)) and Transport Layer Security (TLS) protocols. The keystore contains the private key used to encrypt outgoing messages.

    Default: resources/dse/conf/.keystore

    keystore_password

    Password for the keystore.

    Default: cassandra

    require_client_auth

    Enables certificate authentication for client-to-node encryption.

    • true: Require certificate authentication for client-to-node encryption. Client certificates must be present on all nodes in the cluster.

    • false (default): Do not require certificate authentication for client-to-node encryption.

    truststore_type

    Valid types are JKS (default), JCEKS, or PKCS12. For file-based truststores, use PKCS12.

    Due to an OpenSSL issue, PKCS12 truststores generated with OpenSSL can be incompatible with DSE.

    For example, a truststore generated with the following command might not work with DSE:

    openssl pkcs12 -export -nokeys -out truststore.pfx -in <intermediate.chain.pem>

    However, if you generate a truststore with Java’s keytool, and then convert it to PKCS12, it will work with DSE. For example:

    1. Create the truststore with keytool:

      keytool -importcert -alias <rootca> -file <rootca.pem> -keystore <truststore.jks>

    2. Import the intermediate certificate:

      keytool -importcert -alias <intermediate> -file <intermediate.pem> -keystore <truststore.jks>

    3. Convert the JKS truststore to PKCS12:

      keytool -importkeystore -srckeystore <truststore.jks> -destkeystore <truststore.pfx> -deststoretype pkcs12
    truststore

    Relative path from the DSE installation directory or the absolute path to the truststore containing the trusted certificate for authenticating remote servers.

    Default: resources/dse/conf/.truststore

    Truststore password and path are only required when require_client_auth is set to true.

    truststore_password

    Password for the truststore. This must match the password used when generating the keystore and truststore.

    Default: cassandra

    Truststore password and path are only required when require_client_auth is set to true.

    protocol

    Default: TLS

    algorithm

    Default: SunX509

    cipher_suites

    A comma-separated list of cipher suites for encryption. Enclose the list in square brackets. For example, the default value is as follows:

    [TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA]

    Supported ciphers include the following:

    • TLS_RSA_WITH_AES_128_CBC_SHA

    • TLS_RSA_WITH_AES_256_CBC_SHA

    • TLS_DHE_RSA_WITH_AES_128_CBC_SHA

    • TLS_DHE_RSA_WITH_AES_256_CBC_SHA

    • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

    • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA

    To encrypt the truststore and keystore passwords for local encryption, see Encrypting configuration file properties. For KMIP see Encrypting configuration file properties.

    The store_type option is deprecated. Instead, use keystore_type and truststore_type.

    The remote keystore option requires installation of a provider. See Using a remote keystore provider.

    Use the following settings to configure the remote keystore. Unused options can be blank or commented out.

    client_encryption_options:
    enabled: true
    optional: false
    keystore_type: PKCS12
    require_client_auth: true
    truststore_type: PKCS12
    protocol: ssl
    algorithm: SunX509
    cipher_suites: [TLS_RSA_WITH_AES_128_CBC_SHA]
    enabled

    Enables client-to-node encryption. You must also generate keys and provide the appropriate key and truststore locations and passwords. There are no custom encryption options enabled for DataStax Enterprise (DSE).

    Default: false

    optional

    When optional is true, both encrypted and unencrypted connections over native transport are allowed. This is a necessary transition state to facilitate enabling client to node encryption on live clusters without inducing an outage for existing unencrypted clients. Typically, once existing clients are migrated to encrypted connections, optional is set to false to enforce native transport encryption.

    Default: false

    keystore_type

    Valid types are JKS (default), JCEKS, PKCS11, or PKCS12. For file-based keystores, use PKCS12.

    DataStax supports PKCS11 as a keystore_type on nodes with cassandra or advanced workloads.

    If you need to use PKCS11, you must specify the keystore_type as PKCS11 and the keystore as NONE in either server_encryption_options or client_encryption_options depending on your use case.

    PKCS11 isn’t supported as a truststore_type.
    require_client_auth

    Enables certificate authentication for client-to-node encryption.

    • true: Require certificate authentication for client-to-node encryption. Client certificates must be present on all nodes in the cluster.

    • false (default): Do not require certificate authentication for client-to-node encryption.

    truststore_type

    Valid types are JKS (default), JCEKS, or PKCS12. For file-based truststores, use PKCS12.

    Due to an OpenSSL issue, PKCS12 truststores generated with OpenSSL can be incompatible with DSE.

    For example, a truststore generated with the following command might not work with DSE:

    openssl pkcs12 -export -nokeys -out truststore.pfx -in <intermediate.chain.pem>

    However, if you generate a truststore with Java’s keytool, and then convert it to PKCS12, it will work with DSE. For example:

    1. Create the truststore with keytool:

      keytool -importcert -alias <rootca> -file <rootca.pem> -keystore <truststore.jks>

    2. Import the intermediate certificate:

      keytool -importcert -alias <intermediate> -file <intermediate.pem> -keystore <truststore.jks>

    3. Convert the JKS truststore to PKCS12:

      keytool -importkeystore -srckeystore <truststore.jks> -destkeystore <truststore.pfx> -deststoretype pkcs12
    protocol

    Default: TLS

    algorithm

    Default: SunX509

    cipher_suites

    A comma-separated list of cipher suites for encryption. Enclose the list in square brackets. For example, the default value is as follows:

    [TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA]

    Supported ciphers include the following:

    • TLS_RSA_WITH_AES_128_CBC_SHA

    • TLS_RSA_WITH_AES_256_CBC_SHA

    • TLS_DHE_RSA_WITH_AES_128_CBC_SHA

    • TLS_DHE_RSA_WITH_AES_256_CBC_SHA

    • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

    • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA

    The store_type option is deprecated. Instead, use keystore_type and truststore_type.

  5. Save and close the cassandra.yaml file.

  6. Perform a rolling restart.

See also

Was this helpful?

Give Feedback

How can we improve the documentation?

© Copyright IBM Corporation 2025 | 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: Contact IBM