Running cqlsh with Kerberos/SSL

Sample files are provided to help configure authentication for Kerberos, SSL, and Kerberos and SSL.

To run cqlsh with Kerberos, SSL, or Kerberos and SSL, use the sample files and make changes as appropriate for your environment.

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

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

Package installations: /etc/dse/cassandra
Installer-Services installations: /usr/share/dse/resources/cassandra/conf
Installer-No Services and Tarball installations: install_location/resources/cassandra/conf

Kerberos example

[connection]
hostname = 192.168.1.2
port = 9160
factory = cqlshlib.kerberos.kerberos_transport_factory

[kerberos]
hostname = cassandra01.example.com
service = cassandra
principal = bill/cassandra-admin@example.com ;; Optional.
qops = auth-conf ;; Optional, see the paragraph below.

[kerberos-hostnames] ;; Optional section, overrides default hostname in [kerberos] section.
192.168.1.3 = cassandra01.example.com
192.168.1.4 = cassandra02.example.com

If qops is not specified the default (auth) is used. On the client side, the qops option is a comma-delimited list of the QOP values allowed by the client for the connection. The client (cqlsh) value list must contain at least one of the QOP values specified on the server. To clarify, the client can have multiple QOP values, while the server can have only a single QOP value (specified in the dse.yaml).

The Kerberos hostname and service are mandatory settings and must be provided either in the configuration file or as environment variables. The environment variables (KRB_HOST, KRB_SERVICE, and KRB_PRINCIPAL) override any options set in this file. For more information about these settings, see Kerberos guidelines. The hostname and service must match the values set in dse.yaml.

The location of the dse.yaml file depends on the type of installation:

Installer-Services	/etc/dse/dse.yaml
Package installations	/etc/dse/dse.yaml
Installer-No Services	`install_location`/resources/dse/conf/dse.yaml
Tarball installations	`install_location`/resources/dse/conf/dse.yaml

SSL example

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

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

[ssl]
certfile = ~/keys/cassandra.cert
validate = true ;; Optional, true by default. False means no server authentication. 
userkey = ~/key.pem ;; Provide when require_client_auth=true
usercert = ~/cert.pem ;; Provide when require_client_auth=true

[certfiles] ;; Optional section, overrides the default certfile in the [ssl] section.
10.209.182.160 = /etc/dse/cassandra/conf/dsenode0.cer 
10.68.65.199 = /etc/dse/cassandra/conf/dsenode1.cer

Note: When generating the certificate, be sure to set the CN to the hostname of the node.

To validate/authenticate the server, you must use validate = true and generate the pem certificate that is used in the cqlshrc file.

When validate = false there is no server authentication, only data encryption.
When validate = true cqlsh will validate the server's certificate against the certfile.

The client uses the pem certificate to validate the server. For example:

$ keytool -importkeystore -srckeystore .keystore -destkeystore user.p12 -deststoretype PKCS12
openssl pkcs12 -in user.p12 -out user.pem -nodes

This pem key is required. The SSL certificate must be provided in the configuration file or as an environment variable. The environment variables (SSL_CERTFILE and SSL_VALIDATE) override options that are set in the configuration file.

Kerberos and SSL

For information about using Kerberos with SSL, see Using Kerberos and SSL at the same time.

The settings for using both Kerberos and SSL are a combination of the Kerberos and SSL sections in the preceding examples, except the factory setting:

factory = cqlshlib.kerberos_ssl.kerberos_ssl_transport_factory

The supported environmental variables are KRB_HOST, KRB_SERVICE, KRB_PRINCIPAL, SSL_CERTFILE, and SSL_VALIDATE variables.