deb-python-cassandra-driver/docs/security.rst

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 ~.Cluster.protocol_version is set to 2 or higher. To use this authentication, set ~.Cluster.auth_provider to an instance of a subclass of ~cassandra.auth.AuthProvider. When working with Cassandra's PasswordAuthenticator, you can use the ~cassandra.auth.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)

When working with version 2 or higher of the driver, the protocol version is set to 2 by default, but we've included it in the example to be explicit.

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.

Protocol v1 Authentication

When working with Cassandra 1.2 (or a higher version with ~.Cluster.protocol_version set to 1), you will not pass in an ~.AuthProvider instance. Instead, you should pass in a function that takes one argument, the IP address of a host, and returns a dict of credentials with a username and password key:

from cassandra.cluster import Cluster

def get_credentials(host_address):
    return {'username': 'joe', 'password': '1234'}

cluster = Cluster(auth_provider=get_credentials, protocol_version=1)

SSL

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. This should be used when client encryption is enabled in Cassandra.

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_TLSv1 to match Cassandra's default protocol.

For example:

from cassandra.cluster import Cluster
from ssl import PROTOCOL_TLSv1

ssl_opts = {'ca_certs': '/path/to/my/ca.certs',
            'ssl_version': PROTOCOL_TLSv1}
cluster = Cluster(ssl_options=ssl_opts)

For further reading, Andrew Mussey has published a thorough guide on Using SSL with the DataStax Python driver.