Configure SSL for client-to-node connections

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

Complete the following procedure on every node in the cluster to configure SSL for client-to-node connections.

Prerequisites

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

Procedure

Locate the cassandra.yaml configuration file.

The location of the cassandra.yaml file depends on your installation type:
- Package installations: /etc/hcd/cassandra/cassandra.yaml
- Tarball installations: INSTALL_DIRECTORY/resources/cassandra/conf/cassandra.yaml
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.

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:

Local files: Use the following settings.

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

client_encryption_options:
    enabled: true
    optional: false
    keystore_type: JKS
    keystore: KEYSTORE_PATH
    keystore_password: KEYSTORE_PASSWORD
    require_client_auth: true
    truststore_type: JKS
    truststore: TRUSTSTORE_PATH
    truststore_password: TRUSTSTORE_PASSWORD
    protocol: ssl
    algorithm: SunX509
    cipher_suites: [TLS_RSA_WITH_AES_128_CBC_SHA]

Replace the following:

KEYSTORE_PATH: The path to the JKS keystore file.
KEYSTORE_PASSWORD: The password for the keystore.
TRUSTSTORE_PATH: The path to the JKS truststore file.
TRUSTSTORE_PASSWORD: The password for the truststore.

Remote keystore provider: Use the following settings.

The store_type option is deprecated. Use keystore_type and truststore_type instead. Unused options can be blank or commented out.

Requires installation of a provider.

See Use a remote keystore provider.
```
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]
```

PEM files: Use the following settings.

client_encryption_options:
    enabled: true
    optional: false
    require_client_auth: true
    ssl_context_factory:
        class_name: org.apache.cassandra.security.PEMBasedSslContextFactory
        parameters:
            private_key: PRIVATE_KEY_PATH
            private_key_password: PRIVATE_KEY_PASSWORD
            trusted_certificates: TRUSTED_CERTIFICATES_PATH

Replace the following:

PRIVATE_KEY_PATH: The path to the PEM file containing the node’s private key and certificate chain.
PRIVATE_KEY_PASSWORD: The password for the private key. Omit private_key_password if the private key is not encrypted.

TRUSTED_CERTIFICATES_PATH: The path to the PEM file containing the trusted CA certificates.

enabled

Enables client-to-node encryption. Default: false

optional

When optional is selected (true), both encrypted and unencrypted connections over native transport are allowed. That 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 unselected in order to enforce native transport encryption.

Default: false

keystore_type

Valid types are JKS (default), JCEKS, PKCS11, or PKCS12. For file-based keystores, use PKCS12. PKCS11 is not supported as a truststore_type.

DataStax supports PKCS11 as a keystore_type on nodes with cassandra (transactional) workloads. If PKCS11 is needed, in server_encryption_options or client_encryption_options, specify the keystore_type as PKCS11 and the keystore as NONE.

client_keystore_path

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

HCD does not include default keystore files. You must create your own keystore file for SSL/TLS encryption to work.

The default path where HCD expects to find the keystore is resources/cassandra/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, JCEKS, or PKCS12. For file-based truststores, use PKCS12.

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 does not work with HCD:

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

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

Default: JKS

client_truststore_path

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

The truststore path must be accessible to the HCD process.

There is no default truststore path. You must create your own truststore file for SSL/TLS encryption to work.

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.

Save and close the cassandra.yaml file.
Complete a rolling HCD restart.

Troubleshoot client-to-node-encryption

If you disabled JCE Unlimited Strength Jurisdiction Policy, and your ticket-granting principal uses AES-256, you might see warnings such as the following in logs:

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 isn't supported by the socket

Either configure your ticket-granting principal to not use AES-256, or enable the JCE Unlimited Strength Jurisdiction Policy so that AES-256 is supported.

Configure SSL for client-to-node connections

Prerequisites

Procedure

Troubleshoot client-to-node-encryption

See also

Was this helpful?

Give Feedback