Connecting to SSL-enabled Nodes using `cqlsh`

Use the CQL shell (cqlsh) to connect to nodes where SSL is configured for client-to-node connections. cqlsh can use its own key and certificate that can either be signed by the same root Certificate Authority (CA) used for nodes in the cluster or by a different CA.

Use the DataStax Enterprise sample cqlshrc.sample.ssl file as a starting point. See the SSL example for reference.

The default location of the cqlshrc.sample.ssl file depends on the type of installation:

Package installations: /etc/dse/cassandra/cqlshrc.sample.ssl
Tarball installations: <installation_location>/resources/cassandra/conf/cqlshrc.sample.ssl

The environment variables (SSL_CERTFILE and SSL_VALIDATE) override any options set in the cqlshrc file.

If problems authenticating occur, then use the --debug option to show CQL shell settings and connection details.

Procedure

Create a client.conf configuration file:
```
touch client.conf
```

Edit the client.conf file and add the following settings:

# <client.conf>
[ req ]
distinguished_name = <CA_DN>
prompt             = no
output_password    = <rootca-cqlsh_password>
default_bits       = 2048

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

Generate a separate key and certificate for cqlsh, using the client.conf file you created in the previous step.

openssl req -newkey rsa:2048 \
-nodes \
-keyout <client_key.key> \
-out <signing_request.csr> \
-config `client.conf`

Sign the certificate using the same root CA certificate used on the node where you are running cqlsh. You created the root CA to sign DSE node certificates for SSL.
```
openssl x509 -req -CA '<path/to/rootca.crt>' \
-CAkey '<path/to/rootca.key>' \
-in <signing_request.csr> \
-out <client_cert.crt_signed> \
-days 3650 \
-CAcreateserial \
-passin pass:<rootca_password>
```
- rootca.crt
  
  Certificate used to sign (authorize) DSE node SSL certificates.
Copy the cqlshrc.sample.ssl file to the ~/.cassandra directory. The following example uses the default location for a package installation:
```
cp /etc/dse/cassandra/cqlshrc.sample.ssl ~/.cassandra
```
Rename the file to cqlshrc. The file is typically located in ~/.cassandra/cqlshrc.

If cqlsh finds the cqlshrc file located in the home directory, cqlsh moves the file to ~/.cassandra/cqlshrc upon its next invocation and shows a message that the file moved.

Specify the location of the SSL certificate file either using the SSL_CERTFILE environment variable or the [ssl] cqlshrc parameters.

If you created your own root CA, use the root certificate rootca.crt. If using an external certificate from a well-known root CA, extract the certificate from the <dse-truststore.jks> truststore.

Environment variable:

Use the SSL_CERTFILE variable to specify the path to the certificate file:
```
EXPORT SSL_CERTFILE='<path/to/rootca.crt>'
```
cqlshrc parameter:

In the [ssl] section of the cqlshrc file, use the certfile parameter to specify the path to the root certificate:
```
[ssl]
certfile = <path/to/rootca.crt>
validate = true
userkey = <client_key.key>
usercert = <client_cert.crt_signed>
```
rootca.crt

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

client_key.key

Key certificate used for cqlsh.

client_cert.crt_signed

Signed security certificate to use when connecting to a node using cqlsh.

Restart cqlsh.

SSL example

DataStax Enterprise provides a sample cqlshrc.sample.ssl file that you can use as a starting point.

[authentication]
username = fred
password = !!bang!!$

[connection]
hostname = 127.0.0.1
port = 9042
factory = cqlshlib.ssl.ssl_transport_factory

[ssl]
certfile = <path/to/rootca.crt>
; Optional, true by default.
validate = true
userkey = <client_key.key>
usercert = <client_cert.crt_signed>

[certfiles]
; Optional section, overrides the default certfile in the [ssl] section.
10.209.182.160 = ~/keys/cassandra01.cert
10.68.65.199 = ~/keys/cassandra02.cert

When validate is enabled, you must create a Policy Enforcement Manager (PEM) key which is used in the cqlshrc file.

This PEM key is required because the host in the certificate is compared to the host of the machine to which it is connected. The SSL certificate must be provided either in the configuration file or as an environment variable. The environment variables (SSL_CERTFILE and SSL_VALIDATE) override any options set in this file.

Connecting to SSL-enabled Nodes using cqlsh

Procedure

SSL example

Connecting to SSL-enabled Nodes using `cqlsh`