ScyllaDB Docs Scylla Python Driver Security

For AI agents: a documentation index is available at https://python-driver.docs.scylladb.com/master/llms.txt. A Markdown version of this page is at https://python-driver.docs.scylladb.com/master/security.md.

Caution

You're viewing documentation for an unstable version of Scylla Python Driver. Switch to the latest stable version.

Security¶

The two main security components you will use with the Python driver are Authentication and SSL.

Authentication¶

Versions 2.0 and higher of the driver support a SASL-based authentication mechanism when protocol_version is set to 2 or higher. To use this authentication, set auth_provider to an instance of a subclass of AuthProvider. When working with Cassandra’s PasswordAuthenticator, you can use the PlainTextAuthProvider class.

For example, suppose Cassandra is setup with its default ‘cassandra’ user with a password of ‘cassandra’:

from cassandra.cluster import Cluster
from cassandra.auth import PlainTextAuthProvider

auth_provider = PlainTextAuthProvider(username='cassandra', password='cassandra')
cluster = Cluster(auth_provider=auth_provider, protocol_version=2)

Custom Authenticators¶

If you’re using something other than Cassandra’s PasswordAuthenticator, SaslAuthProvider is provided for generic SASL authentication mechanisms, utilizing the pure-sasl package. If these do not suit your needs, you may need to create your own subclasses of AuthProvider and Authenticator. You can use the Sasl classes as example implementations.

SSL¶

SSL should be used when client encryption is enabled in Cassandra.

To give you as much control as possible over your SSL configuration, our SSL API takes a user-created SSLContext instance from the Python standard library. These docs will include some examples for how to achieve common configurations, but the ssl.SSLContext documentation gives a more complete description of what is possible.

To enable SSL with version 3.17.0 and higher, you will need to set Cluster.ssl_context to a ssl.SSLContext instance to enable SSL. Optionally, you can also set Cluster.ssl_options to a dict of options. These will be passed as kwargs to ssl.SSLContext.wrap_socket() when new sockets are created.

If you create your SSLContext using ssl.create_default_context, be aware that SSLContext.check_hostname is set to True by default, so the hostname validation will be done by Python and not the driver. For this reason, we need to set the server_hostname at best effort, which is the resolved ip address. If this validation needs to be done against the FQDN, consider enabling it using the ssl_options as described in the following examples or implement your own EndPoint and EndPointFactory.

The following examples assume you have generated your Scylla certificate and keystore files with these instructions:

Scylla TLS/SSL Guide

TLS Session Resumption¶

A shard-aware driver opens one connection per shard to every node, and a full TLS handshake on each is the expensive part of that. Whenever Cluster.ssl_context is set, the driver caches the TLS session each connection establishes and offers it on the next one, so the connections that follow resume instead of handshaking in full. This is on by default and needs no configuration.

There is one thing to weigh before leaving it on. A resumed handshake carries no Certificate message, so nothing about the server’s certificate is checked again while a cached session is being offered – not its expiry, and not a revocation list the SSLContext carries. A certificate that expires or is revoked goes on being accepted by connections that resume, until the cached entry goes: that is the lifetime the server announced with the ticket, which the driver caps at seven days. Connections that handshake in full verify as they always have. The hostname is not re-checked either, which is why the driver keys each cached session by the name verified when it was established, so a session is never offered to a connection expecting a different one. Where that window is not acceptable, turn resumption off with ssl_session_cache=None.

It does need the server to issue something to resume from. Scylla sends session tickets only when enable_session_tickets is set in its client_encryption_options, which defaults to true from Scylla 2026.3 and to false in the releases before it:

client_encryption_options:
    enabled: true
    certificate: /path/to/scylla.crt
    keyfile: /path/to/scylla.key
    enable_session_tickets: true

Without that, nothing resumes and every connection performs a full handshake, as it did before.

Resumption also needs a reactor that can offer a session before the handshake begins: the libev reactor, and asyncore on the Python versions that still ship it, which is up to 3.11. The asyncio reactor performs its handshake inside loop.create_connection(), leaving no point at which to restore a session, so resumption is unavailable there – worth knowing, because that is the default reactor on Python 3.12 and newer when the libev extension is not installed. It is unavailable too with the deprecated Cluster.ssl_options-only configuration below, since each of those connections builds its own SSLContext and a session cannot be replayed onto a different one.

Where resumption is unavailable, no cache is created and Cluster.ssl_session_cache reads as None; asking for one anyway is reported when Cluster.connect() is called. To turn resumption off, or to size the cache or share it between clusters, see Cluster.ssl_session_cache:

from cassandra.cluster import Cluster
from cassandra.ssl_session_cache import SSLSessionCache

cluster = Cluster(ssl_context=ssl_context, ssl_session_cache=None)

cluster = Cluster(ssl_context=ssl_context,
                  ssl_session_cache=SSLSessionCache(max_size=64))

SSL Configuration Examples¶

Here, we’ll describe the server and driver configuration necessary to set up SSL to meet various goals, such as the client verifying the server and the server verifying the client. We’ll also include Python code demonstrating how to use servers and drivers configured in these ways.

No identity verification¶

No identity verification at all. Note that this is not recommended for for production deployments.

The Cassandra configuration:

client_encryption_options:
  enabled: true
  keystore: /path/to/127.0.0.1.keystore
  keystore_password: myStorePass
  require_client_auth: false

The driver configuration:

from cassandra.cluster import Cluster, Session
from ssl import SSLContext, PROTOCOL_TLS

ssl_context = SSLContext(PROTOCOL_TLS)

cluster = Cluster(['127.0.0.1'], ssl_context=ssl_context)
session = cluster.connect()

Client verifies server¶

Ensure the python driver verifies the identity of the server.

The Cassandra configuration:

client_encryption_options:
  enabled: true
  keystore: /path/to/127.0.0.1.keystore
  keystore_password: myStorePass
  require_client_auth: false

For the driver configuration, it’s very important to set ssl_context.verify_mode to CERT_REQUIRED. Otherwise, the loaded verify certificate will have no effect:

from cassandra.cluster import Cluster, Session
from ssl import SSLContext, PROTOCOL_TLS, CERT_REQUIRED

ssl_context = SSLContext(PROTOCOL_TLS)
ssl_context.load_verify_locations('/path/to/rootca.crt')
ssl_context.verify_mode = CERT_REQUIRED

cluster = Cluster(['127.0.0.1'], ssl_context=ssl_context)
session = cluster.connect()

Additionally, you can also force the driver to verify the hostname of the server by passing additional options to ssl_context.wrap_socket via the ssl_options kwarg:

from cassandra.cluster import Cluster, Session
from ssl import SSLContext, PROTOCOL_TLS, CERT_REQUIRED

ssl_context = SSLContext(PROTOCOL_TLS)
ssl_context.load_verify_locations('/path/to/rootca.crt')
ssl_context.verify_mode = CERT_REQUIRED
ssl_context.check_hostname = True
ssl_options = {'server_hostname': '127.0.0.1'}

cluster = Cluster(['127.0.0.1'], ssl_context=ssl_context, ssl_options=ssl_options)
session = cluster.connect()

Server verifies client¶

If Cassandra is configured to verify clients (require_client_auth), you need to generate SSL key and certificate files.

The cassandra configuration:

client_encryption_options:
  enabled: true
  keystore: /path/to/127.0.0.1.keystore
  keystore_password: myStorePass
  require_client_auth: true
  truststore: /path/to/truststore.jks
  truststore_password: myStorePass

The Python ssl APIs require the certificate in PEM format. First, create a certificate conf file:

cat > gen_client_cert.conf <<EOF
[ req ]
distinguished_name = req_distinguished_name
prompt = no
output_password = ${ROOT_CERT_PASS}
default_bits = 2048

[ req_distinguished_name ]
C = ${CERT_COUNTRY}
O = ${CERT_ORG_NAME}
OU = ${CERT_OU}
CN = client
EOF

Make sure you replaced the variables with the same values you used for the initial root CA certificate. Then, generate the key:

openssl req -newkey rsa:2048 -nodes -keyout client.key -out client.csr -config gen_client_cert.conf

And generate the client signed certificate:

openssl x509 -req -CA ${ROOT_CA_BASE_NAME}.crt -CAkey ${ROOT_CA_BASE_NAME}.key -passin pass:${ROOT_CERT_PASS} \
    -in client.csr -out client.crt_signed -days ${CERT_VALIDITY} -CAcreateserial

Finally, you can use that configuration with the following driver code:

from cassandra.cluster import Cluster, Session
from ssl import SSLContext, PROTOCOL_TLS

ssl_context = SSLContext(PROTOCOL_TLS)
ssl_context.load_cert_chain(
    certfile='/path/to/client.crt_signed',
    keyfile='/path/to/client.key')

cluster = Cluster(['127.0.0.1'], ssl_context=ssl_context)
session = cluster.connect()

Server verifies client and client verifies server¶

See the previous section for examples of Cassandra configuration and preparing the client certificates.

The following driver code specifies that the connection should use two-way verification:

from cassandra.cluster import Cluster, Session
from ssl import SSLContext, PROTOCOL_TLS, CERT_REQUIRED

ssl_context = SSLContext(PROTOCOL_TLS)
ssl_context.load_verify_locations('/path/to/rootca.crt')
ssl_context.verify_mode = CERT_REQUIRED
ssl_context.load_cert_chain(
    certfile='/path/to/client.crt_signed',
    keyfile='/path/to/client.key')

cluster = Cluster(['127.0.0.1'], ssl_context=ssl_context)
session = cluster.connect()

The driver uses SSLContext directly to give you many other options in configuring SSL. Consider reading the Python SSL documentation for more details about SSLContext configuration.

Versions 3.16.0 and lower¶

To enable SSL you will need to set Cluster.ssl_options to a dict of options. These will be passed as kwargs to ssl.wrap_socket() when new sockets are created. Note that this use of ssl_options will be deprecated in the next major release.

By default, a ca_certs value should be supplied (the value should be a string pointing to the location of the CA certs file), and you probably want to specify ssl_version as ssl.PROTOCOL_TLS to match Cassandra’s default protocol.

For example:

from cassandra.cluster import Cluster
from ssl import PROTOCOL_TLS, CERT_REQUIRED

ssl_opts = {
    'ca_certs': '/path/to/my/ca.certs',
    'ssl_version': PROTOCOL_TLS,
    'cert_reqs': CERT_REQUIRED  # Certificates are required and validated
}
cluster = Cluster(ssl_options=ssl_opts)

This is only an example to show how to pass the ssl parameters. Consider reading the python ssl documentation for your configuration.

Was this page helpful?

ScyllaDB Python Driver is available under the Apache v2 License. ScyllaDB Python Driver is a fork of DataStax Python Driver. See Copyright here.