Create SSL certificates, keystores, and truststores

Use these steps as a general guide to create and distribute SSL certificates using OpenSSL and Java keytool.

Use SSL certificates for client-to-node encryption and node-to-node encryption. DataStax supports SSL using well-known Certificate Authority (CA) signed certificates for each node or you can create your own root CA. DataStax recommends using certificates signed by a well-known CA to reduce SSL certificate management tasks. However, you can use self-signed certificates with Hyper-Converged Database (HCD), which supports SSL certificates in local and external keystores.

Use this method of generating a root key/certificate pair only for development and test environments. Secure these files, because anyone with access to the root CA files can sign certificates and authorize hosts as the root certificate authority.

Creating your own CA in a production environments typically involves using an intermediary certificate chain, where the root CA signs one or more intermediate certificates with its private key. These intermediary certificates chain together to link back to the root CA, which owns one or more trusted roots.

DataStax recommends using a computer outside of the HCD environment to generate and manage SSL certificates. Complete the steps on a dedicated CA server that is fully secured and permanently isolated from the network.

Use a well-known CA

If using a third-party signed certificate, or when adding a node using an existing root CA, skip to the steps for Creating a key and certificate for each node.

Create a root CA certificate

In development and testing environments, you can set up your own root Certificate Authority (CA) to sign Hyper-Converged Database (HCD) node certificates for SSL. In this model, generate your own root certificate that is to be used to sign the certificate on every node, generate certificates for individual nodes, sign them, and generate corresponding keystores for every node.

If you want to use a remote keystore provider instead, then see Use a remote keystore provider.

Procedure

  1. Create a directory for the root CA signing certificate/key, and then change to that directory:

    mkdir -p <rootca_path>
    cd <rootca_path>

    include::ROOT:partial$certificate pair:

    openssl req -config rootca.conf \
-new -x509 -nodes \
-keyout rootca.key \
-out rootca.crt \
-days 3650

    The -x509 option outputs a signed certificate used as the root CA. The number of days specified by the -days option affects the duration for which all signed certificates are valid. Indicating a higher number of days means that the certificates are valid for a longer period. In the previous example, the root CA is valid for 3650 days, which is approximately 10 years.

    Two files are created: rootca.key and rootca.crt.

  2. Verify the root certificate:

    openssl x509 -in <rootca.crt> -text -noout
    Certificate:
    Data:
        Version: 1 (0x0)
        Serial Number: <serial_number> (0xcd4bc943beeb35ce)
    Signature Algorithm: sha256WithRSAEncryption
        Issuer: C=US, O=datastax, OU=pw-j-dse, CN=rootCa
        Validity
            Not Before: Jul 23 20:15:06 2019 GMT
            Not After : Jul 23 20:15:06 2020 GMT
        Subject: C=US, O=datastax, OU=pw-j-dse, CN=rootCa
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                Public-Key: (2048 bit)
                Modulus:
                    00:d8:71:e0:51:07:ad:f1:f7:0b:4d:2c:10:4c:24:
                    19:9f:1f:d4:2a:a1:a6:89:3d:e1:12:81:3b:4d:bd:
                    2d:da:fb:9e:d5:c5:ba:ed:82:80:28:35:e5:00:86:
                    ...
                Exponent: 65537 (0x10001)
    Signature Algorithm: sha256WithRSAEncryption
         43:8d:98:8c:d7:26:52:41:ad:de:c9:80:8d:4f:d6:6e:21:69:
         81:7d:eb:af:93:6e:15:ad:9d:fe:ee:1a:60:d6:aa:92:86:a2:
         fd:e1:8f:95:b9:ee:db:59:63:fd:cd:05:72:63:d6:6b:14:cf:
         ...

Create a truststore for all nodes

Create a truststore that is used to ensure that all nodes recognize the certificate authority (CA). Even when using a well-known certificate authority, DataStax recommends creating a truststore with the signing CA certificate or certificate chain (following the instructions from your CA). Most well-known CA certificates are already available through the Hyper-Converged Database (HCD) Java implementation.

Procedure

  1. Create a single truststore, and add the root certificate to the truststore. For the <keystore_type>, enter JKS:

    If prompted whether to import the certificate, enter yes.

    		 
    keytool -keystore <hcd-truststore.jks> \
-storetype <keystore_type> \
-importcert -file '<rootca.crt>' \
-keypass <keystore_password> \
-storepass <truststore_password> \
-alias <rootca_name> \
-noprompt
    truststore.jks

    Truststore that contains the root certificate.

    Use the same truststore that contains the root certificate on all nodes.
    keystore_type

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

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

    PKCS11 is not supported as a truststore_type.

    Default: JKS

    rootca.crt

    Certificate used to sign (authorize) HCD node SSL certificates.

    keystore_password

    Password used to protect the private key of the key pair.

    Default: none

    truststore_password

    Password required to access the keystore.

    Default: none

    rootca_name

    Name (alias) used to identify the root certificate when importing into the node’s keystore. For example, in a rootca.conf file, the CN = CA_CN entry shown in Creating a root CA certificate.

    A message displays indicating that the certificate was added. The truststore now contains a single entry.

    Certificate was added to keystore

  2. Verify the truststore to ensure that it contains the root certificate:

    keytool -list \
-keystore <hcd-truststore.jks> \
-storepass <truststore_password>

    The command output indicates the keystore type, provider, number of entries, creation date, and certification details.

    Keystore type: jks
Keystore provider: SUN

Your keystore contains 1 entry

<rootca_name>, Aug 8, 2019, trustedCertEntry,
Certificate fingerprint (SHA1): <SHA1-has>h

Create a key and certificate for each node

For each node in the cluster, create a keystore, key pair, and certificate signing request using the Fully Qualified Domain Name (FQDN) of the node.

These steps are required even when using a third-party CA, or when adding a node to an existing DSE environment with SSL enabled.

Prerequisites

On each node, run the following command to obtain the FQDN for each node:

nslookup $(hostname --fqdn) && hostname --fqdn && hostname -i
Server:    10.200.1.10
Address:   10.200.1.10#53

Name:      ip-10-200-182-183.example.com
Address:   10.200.182.183

ip-10-200-182-183.example.com
10.200.182.183

In this example, ip-10-200-182-183.example.com is the Common Name (CN), which is used to generate the SSL certificate. The CN must match the DNS-resolvable host name. Mismatches between the CN and node hostname cause an exception and the connection is refused.

Procedure

  1. Create a directory to store the keystores and change to the directory:

    mkdir -p <dse/keystores>
    cd <dse/keystores>

  2. For each node, generate a keystore with key pair. Each node is to have its own keystore, such as node1-keystore.jks:

    Ensure the passwords entered for <truststore_password> and <keystore_password> are the same. If the passwords are different, DSE fails to start and returns an error message: “Cannot recover key”.

    		 
    keytool -genkeypair -keyalg RSA \
-alias <node_name> \
-keystore <node-keystore.jks> \
-storepass <truststore_password> \
-keypass <keystore_password> \
-validity 730 \
-keysize 2048 \
-dname "CN=<node_name>, OU=<cluster_name>, O=<org_name>, C=<CC>" \
-ext "san=ip:<node_ip_address>"

    The -validity option specifies the timeframe for which the generated key pair for the node is valid. In the previous example the key pair is valid for 730 days, which is approximately 2 years.
    node_name

    Fully Qualified Domain Name (FQDN) of the node, such as ip-10-200-182-183.example.com. When using the FQDN as the node_name, you can add the IP address as a subject alternative name (SAN) so that the certificate protects the IP address in addition to the domain name.

    node-keystore.jks

    Keystore for the individual node.

    Default: none

    truststore_password

    Password required to access the keystore.

    Default: none

    keystore_password

    Password used to protect the private key of the key pair.

    Default: none

    cluster_name

    Name of your Hyper-Converged Database (HCD) cluster.

    org_name

    Name of your organization.

    CC

    Two letter country code, such as US for United States or JP for Japan. See Nations Online for a complete list of country codes.

    node_ip_address

    When using the domain name as the node_name for the CA, add san=ip:ip_address to the -ext option. Using the IP address as a subject alternative name (SAN) ensures that the certificate protects the IP address in addition to the domain name.

    For example:

    -ext "san=ip:10.200.100.52"

  3. Verify each SSL keystore and key pair:

    keytool -list \
-keystore <node-keystore.jks> \
-storepass <truststore_password>

    The command output indicates the keystore type, provider, and number of entries. The alias used the example is dc1_node1.

    Keystore type: JKS
Keystore provider: SUN

Your keystore contains 1 entry

dc1_node1, Jul 23, 2019, PrivateKeyEntry,
Certificate fingerprint (SHA1): <SHA1_hash>

  4. Generate a signing request from each keystore:

    keytool -keystore <node-keystore.jks> \
-alias <node_name> \
-certreq -file <signing_request.csr> \
-keypass <node-key_password> \
-storepass <keystore_password>
    node-key_password

    Password used to protect the individual private key.

    Default: none

    keystore_password

    Password used to protect the private key of the key pair.

    Default: none

    The certificate signing request file (<signing_request.csr>) is created.

  5. Repeat the previous steps on each node to generate a signing request, ensuring that the dname information matches the node information (such as <node_name> and <cluster_name>).

Sign the certificate signing request

For each node, sign the certificate signing request. If you created your own root CA, follow the instructions below. Alternatively, send the certificate signing request to a well-known CA for signing.

Procedure

  1. Sign each node certificate:

    openssl x509 -req -CA 'path/to/rootca.crt' \
-CAkey 'path/to/rootca.key' \
-in signing_request.csr \
-out signing_request.crt_signed \
-days 3650 \
-CAcreateserial \
-passin pass:rootca_password \
-extfile san_config_file.conf

  2. Verify the signed certificate:

    openssl verify -CAfile 'path/to/rootca.crt' <signing_request.crt_signed>
    <signing_request>.crt_signed: OK

  3. Delete the temporary configuration <file san_config_file>.conf to protect the SAN for a node.

    rm -f <san_config_file.conf>

Import the signed certificate into the node keystore

For each node in the cluster, create a keystore and import the signed certificate. The variables that you enter in the following commands must match the information that you entered in Create a key and certificate for each node.

Procedure

  1. Import the root certificate (rootca.crt) into each node’s keystore:

    You created the root certificate when Create a truststore for all nodes.

    keytool -keystore <node-keystore.jks> \
-alias <rootca_name> \
-importcert -file '<path/to/rootca.crt>' \
-keypass <keystore_password> \
-storepass <truststore_password> \
-noprompt
    rootca_name

    Name (alias) used to identify the root certificate when importing into the node’s keystore. For example, in a rootca.conf file, the CN = CA_CN entry shown in Creating a root CA certificate.

    If the signed certificate for the node is imported before the root certificate, an error occurs:

    keytool error: java.lang.Exception: Failed to establish chain from reply

  2. Import the node’s signed certificate (signing_request.crt_signed) into the corresponding keystore on the node:

    keytool -keystore <node-keystore.jks> \
-alias <node_name> \
-importcert -file <signing_request.crt_signed> \
-keypass <node-key_password> \
-storepass <keystore_password> \
-noprompt

    The alias <node_name> must match the alias name used to generate the signing request. See Creating a key and certificate for each node.

    Confirmation of the installation appears:

    Certificate was added to keystore

  3. Verify your keystore again, which should now contain two entries. One entry is for the node keystore, and the other for the imported root certificate:

    keytool -list \
-keystore <node-keystore.jks> \
-storepass <truststore_password>

    Each keystore entry is identified by the name you entered for the -alias:

    Keystore type: jks
Keystore provider: SUN

Your keystore contains 2 entries

<node_name>, Aug 8, 2019, trustedCertEntry,
Certificate fingerprint (SHA1): <SHA1-hash>
<rootca_name>, Aug 8, 2019, trustedCertEntry,
Certificate fingerprint (SHA1): <SHA1-hash>

  4. Repeat the previous steps on each node to import the root certificate, and then import the signed certificate into the keystore.

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