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
-
To enable client-to-node SSL encryption, modify the
client_encryption_options
section incassandra.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
]
- Server-to-server encryption
-
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
-
Enable SSL with Optional Mode.
-
Set
enabled: true
in the encryption options. -
Set
optional: true
to allow both encrypted and unencrypted connections. -
Perform a rolling restart of all nodes in the cluster.
-
-
Configure SSL Certificates.
-
Generate SSL certificates and keystores.
-
Update the keystore and truststore paths in the configuration.
-
Set appropriate passwords for the keystores.
-
-
Test SSL Connections.
-
Test SSL connections using cqlsh with SSL options.
-
Verify SSL certificate validation.
-
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.