Enable SSL Encryption for HCD

There are two main types of SSL encryption available in Hyper-Converged Database (HCD):

  • Node-to-node encryption (internode encryption)

  • Client-to-node encryption

Enabling node-to-node encryption in HCD automatically enables encrypted communication between HCD nodes. HCD nodes with client-to-node encryption enabled allow SSL connections from client applications.

Configure SSL encryption

HCD includes comprehensive SSL support with the following components:

  • SSL libraries and native implementations for multiple platforms

  • Client-to-server encryption configuration

  • Server-to-server encryption configuration

  • SSL certificate validation and management

  • Client-to-node encryption

  • Server-to-server encryption

To enable client-to-node SSL encryption, modify the client_encryption_options section in cassandra.yaml:

client_encryption_options:
    enabled: true
    optional: true
    keystore: conf/.keystore
    keystore_password: cassandra
    require_client_auth: false
    truststore: conf/.truststore
    truststore_password: cassandra
    protocol: TLS
    algorithm: SunX509
    store_type: JKS
    cipher_suites: [
      TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
      TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,
      TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, TLS_RSA_WITH_AES_128_GCM_SHA256, TLS_RSA_WITH_AES_128_CBC_SHA,
      TLS_RSA_WITH_AES_256_CBC_SHA
    ]

To enable server-to-server SSL encryption, modify the server_encryption_options section:

server_encryption_options:
    internode_encryption: all
    keystore: conf/.keystore
    keystore_password: cassandra
    require_client_auth: false
    truststore: conf/.truststore
    truststore_password: cassandra
    protocol: TLS
    algorithm: SunX509
    store_type: JKS
    cipher_suites: [
      TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
      TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,
      TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, TLS_RSA_WITH_AES_128_GCM_SHA256, TLS_RSA_WITH_AES_128_CBC_SHA,
      TLS_RSA_WITH_AES_256_CBC_SHA
    ]

SSL configuration steps

  1. Enable SSL with Optional Mode.

    1. Set enabled: true in the encryption options.

    2. Set optional: true to allow both encrypted and unencrypted connections.

    3. Perform a rolling restart of all nodes in the cluster.

  2. Configure SSL Certificates.

    1. Generate SSL certificates and keystores.

    2. Update the keystore and truststore paths in the configuration.

    3. Set appropriate passwords for the keystores.

  3. Test SSL Connections.

    1. Test SSL connections using cqlsh with SSL options.

    2. Verify SSL certificate validation.

    3. Monitor SSL connection logs.

Test client SSL connection

Test SSL client connections using cqlsh:

./bin/hcd cqlsh --ssl -e "SELECT release_version FROM system.local;"

Test non-SSL connection

Verify that non-SSL connections still work when SSL is optional:

./bin/hcd cqlsh -e "SELECT release_version FROM system.local;"

SSL configuration validation

The system will properly validate SSL configurations and provide appropriate error messages when:

  • SSL is enabled but certificates are missing

  • SSL certificate validation fails

  • SSL configuration is invalid

When SSL is properly configured and enabled, the system will validate SSL certificates and provide appropriate error messages for missing or invalid certificates.

SSL Configuration Files

cqlsh SSL Configuration

Configure SSL settings for cqlsh in ~/.cassandra/cqlshrc:

[ssl]
certfile = ~/keys/cassandra.cert
validate = true
userkey = ~/key.pem
usercert = ~/cert.pem

SSL environment variables

Set SSL environment variables for client applications:

export SSL_CERTFILE=~/keys/cassandra.cert
export SSL_VALIDATE=true

SSL libraries and components

HCD includes the following SSL components:

  • Netty SSL Handler: netty-handler-ssl-ocsp-4.1.118.Final.jar

  • Native SSL Libraries: Platform-specific SSL implementations for Linux, macOS, and Windows

  • SSL Handling: Python SSL handling modules for cqlsh

  • Certificate Management: Support for JKS, PKCS12, and PEM certificate formats

SSL security best practices

  • Use strong cipher suites: Configure modern TLS cipher suites.

  • Validate certificates: Enable certificate validation for production environments.

  • Secure keystores: Use strong passwords for keystore files.

  • Regular certificate rotation: Implement certificate rotation procedures.

  • Monitor SSL connections: Monitor SSL connection logs and metrics.

SSL configuration validation

The system validates SSL configurations and provides appropriate error messages for:

  • Missing certificate files

  • Invalid certificate formats

  • Incorrect keystore passwords

  • Unsupported cipher suites

  • SSL protocol version mismatches

Troubleshoot SSL issues

The following issues are common when configuring SSL:

  • Certificate not found: Ensure certificate files exist and paths are correct.

  • Invalid certificate: Verify certificate validity and trust chain.

  • SSL handshake failure: Check cipher suite compatibility.

  • Connection refused: Verify SSL port configuration.

SSL Debugging

Enable SSL debugging by setting JVM options:

-Djavax.net.debug=ssl:handshake

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2025 DataStax, an IBM Company | 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