Connecting to SSL-enabled nodes using cqlsh

Connect cqlsh to an SSL enabled node by setting up SSL with environment variables or cqlshrc parameters.

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 be signed by the same root Certificate Authority (CA) used for nodes in the cluster, or signed by a different CA.

When validation is enabled, cqlsh requires a PEM key file (OpenSSL format) to connect to DataStax Enterprise (DSE) nodes. If the keystore is in the JKS format (.jks), you must first generate an intermediate PKCS12 format (.p12) and then convert to a PEM format (.pem).

After converting the key to the PEM format that cqlsh requires, provide the SSL environment variables or parameters in a cqlshrc file. Use the DataStax Enterprise sample cqlshrc.sample.ssl file as a starting point. See the SSL example for reference.

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

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

cqlshrc.sample.ssl

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

Procedure

  1. Create a client.conf configuration file:
    touch client.conf
  2. 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
  3. 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
  4. 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.
  5. 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
  6. Rename the file to cqlshrc. The file is typically located in ~/.cassandra/cqlshrc.
    Note: 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.
  7. Specify the location of the SSL certificate file, either using the SSL_CERTFILE environment variable or the [ssl] cqlshrc parameters.
    Important: 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 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.
  8. 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 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 that it is connected to. 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.