Creating local SSL certificate and keystore files

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 CA signed certificates for each node or you can create your own root Certificate Authority (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 DataStax Enterprise (DSE), which supports SSL certificates in local and external keystores.

Warning: Use this method of generating a root key/certificate pair only for development and test environments. Secure these files, as 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.

OpsCenter Lifecycle Manager can configure DSE clusters to use client-to-node and node-to-node encryption, and automates the process of preparing server certificates. See Configuring SSL using LCM.

Important: DataStax recommends using a computer outside of the DSE 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.

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

Creating a root CA certificate

Bring your own root CA for signing node certificates.

In development and testing environments, you can set up your own root Certificate Authority (CA) to sign DataStax Enterprise (DSE) node certificates for SSL. In this model, generate your own root certificate that will 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, see Using a remote keystore provider.

Procedure

Create a directory for the root CA signing certificate/key, and then change to that directory:
```
mkdir -p rootca_path
```
```
cd rootca_path
```
rootca_path

Directory where root certificate is created and stored. DataStax recommends securing this directory, ideally on a computer isolated from the network.
Create a rootca.conf configuration file:
```
touch rootca.conf
```
rootca.conf

Root CA configuration file.
Edit the rootca.conf file and add the following minimal settings:
```
# rootca.conf
[ req ]
distinguished_name = CA_DN
prompt             = no
output_password    = rootca_password
default_bits       = 2048

[ CA_DN ]
C  = CC
O  = org_name
OU = cluster_name
CN = CA_CN
```
CA_DN

Title for the section containing the Distinguished Name (DN) properties for the CA.

rootca_password

Password for the generated file used to sign certificates.

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.

org_name

Name of your organization.

cluster_name

Name of your DataStax Enterprise (DSE) cluster.

CA_CN

Common Name (CN) for the root CA.
Use openssl to create a root key/certificate pair:
```
openssl req -config rootca.conf \
-new -x509 -nodes \
-keyout rootca.key \
-out rootca.crt \
-days 3650
```
Note: The -x509 option outputs a signed certificate used as the root CA. The number of days specified by the -days option affects the duration that all signed certificates are valid for. 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.

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

Creating a truststore for all nodes

Use the same truststore that contains the certificate authority (CA) certificate.

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 DataStax Enterprise (DSE) Java implementation.

Procedure

Create a single truststore, and add the root certificate to the truststore. For the keystore_type, enter JKS:
Tip: If prompted whether to import the certificate, enter yes.
```
keytool -keystore dse-truststore.jks \
-storetype keystore_type \
-importcert -file 'rootca.crt' \
-keypass keystore_password \
-storepass truststore_password \
-alias rootca_name \
-noprompt
```
dse-truststore.jks

Truststore that contains the root certificate.
Note: Use the same truststore that contains the root certificate on all nodes.

keystore_type

Valid types are JKS, JCEKS, PKCS11, PKCS12. For file-based keystores, use PKCS12.
Attention: DataStax supports PKCS11 as a keystore_type on nodes with cassandra or advanced workloads. The cassandra workload support is specific to DSE 6.7.7 and later releases. The advanced workload support is specific to DSE 6.7.9 and later. 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 in DSE 6.0.x and 5.1.x releases. PKCS11 is not supported as a truststore_type.
Default: JKS

rootca.crt

Certificate used to sign (authorize) DSE 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
```

Verify the truststore to ensure that it contains the root certficate:

keytool -list \
-keystore dse-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-hash

Creating a key and certificate for each node

For each node in the cluster, create a keystore, key pair, and certificate signing request using the FQDN of the 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.

Note: 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

Create a directory to store the keystores and change to the directory:
```
mkdir -p dse/keystores
```
```
cd dse/keystores
```
For each node, generate a keystore with key pair. Each node will have its own keystore, such as node1-keystore.jks:

Important: 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"
```
Note: The -validity option specifies how long the generated key pair for the node is valid for. 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. If 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 DataStax Enterprise (DSE) 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
If 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"
```

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

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

Signing the certificate signing request

For each node, 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

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
```
signing_request.csr

Certificate signing request (CSR) that is passed to the Certificate Authority (CA) to sign the certificate. The CSR typically includes the public key, plus associated metadata such as the Common Name (CN), Organization (O), Organization Unit (OU), and Country (C).

signing_request.crt_signed

The signed certificate file to create, using the certificate signing request (CSR) (signing_request.csr) as the input file.

san_config_file.conf
If using the domain name as the node_name and the node IP address as a subject alternative name (SAN), create a temporary configuration file and pass it in using the -extfile option. In the configuration file, use the subjectAltName parameter to specify the DNS and IP. For example:
```
subjectAltName=DNS:node_name,IP:node_ip_address
```
You can specify multiple SANs in the same configuration file:
subjectAltName=DNS:domain1,IP:10.200.100.52 subjectAltName=DNS:domain1,IP:10.200.101.63 subjectAltName=DNS:domain1,IP:10.200.111.74 subjectAltName=DNS:domain1,IP:10.200.121.85
Note: Use the rootca_password entered when Creating the root CA signing certificate.

A signed certificate file signing_request.crt_signed is created.

Verify the root certificate file was properly signed:

openssl verify -CAfile 'path/to/rootca.crt' signing_request.crt_signed

signing_request.crt_signed: OK

Delete the temporary configuration file san_config_file.conf to protect the SAN for a node.
```
rm -f san_config_file.conf
```

Importing the signed certificate into the node keystore

For each node, create a keystore with the node's signed certificate that is hosted locally.

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

Procedure

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

You created the root certificate when Creating 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.
Warning: 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
```
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
```
Important: 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
```

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

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