Client Security:
Python

This tutorial shows you how to set up a Riak Python client to authenticate itself when connecting to Riak.

If you are using trust- or PAM-, you can use the security setup described below. Password-based authentication is covered in a later section. If you are using certificate-based authentication, follow the instructions in the section below.

OpenSSL Versions

The Riak Python client requires that you install OpenSSL 1.0.1g or later. If you have an earlier version installed, you will receive a warning along the following lines:

Found OpenSSL 0.9.8za 5 Jun 2014 version, but expected at least OpenSSL 1.0.1g.  Security may not support TLS 1.2.

Python Client Basics

When connecting to Riak using a Python-based client, you typically instantiate an object from the RiakClient class that then handles all interactions with Riak. All authentication-related information that needs to be used by the client object can be passed to the object upon instantiation by creating a SecurityCreds object.

If you are using Riak Security, all connecting clients should have access to the same Certificate Authority (CA) used on the server side, regardless of which security source you choose. All clients should also provide a username. The example below sets up a client object (we’ll simply call it client) that connects to Riak on localhost and on port 8087 without any security credentials:

from riak import RiakClient

client = RiakClient(host='127.0.0.1', pb_port=8087)

To provide security credentials, we’ll create an object called creds and specify riakuser as the username. We’ll also point the client to a CA stored at /ssl_dir/cacertfile.pem.

creds = SecurityCreds(username='riakuser',
                      cacert_file='/ssl_dir/cacertfile.pem')

Now we can specify those credentials when we create our client object.

client = RiakClient(host='127.0.0.1', pb_port=8087, credentials=creds)

This client object is not currently set up to use any of the available security sources with the exception of trust-based auth, provided that the CIDR from which the client is connecting has been specified as trusted. More on specifying trusted CIDRs can be found in Trust-based Authentication.

Note: The examples in the following sections specify certs on the basis of their filepaths, e.g. /ssl_dir/cacertfile.pem. In addition to specifying certs by location, you can also provide OpenSSL objects instead. You can find out how to do so in Using OpenSSL Objects below.

Password-based Authentication

To enable our client to use password-based auth, we can use most of the information from the above, with the exception that we’ll also specify a password for the client in the creds object from above. We’ll use the password rosebud here and in the rest of the examples.

creds = SecurityCreds(username='riakuser',
                      cacert_file='/ssl_dir/cacertfile.pem',
                      password='rosebud')

PAM-based Authentication

If you have specified that a specific client be authenticated using PAM, you will need to provide a CA as well as the username and password that you specified when creating the user in Riak. For more, see our documentation on User Management.

Certificate-based Authentication

Using certificated-based authentication requires us to specify the location of a general CA (as with all security sources), a username, a CA-generated cert, and a private key. We’ll assume that all certs are stored in /ssl_dir, as in the previous examples.

creds = SecurityCreds(username='riakuser',
                      cacert_file='/ssl_dir/cacertfile.pem',
                      cert_file='/ssl_dir/cert.pem',
                      pkey_file='/ssl_dir/key.pem')

Specifying a Certificate Revocation List

If you are using a CA-generated Certificate Revocation List (CRL), you can specify its filepath using the crl_file parameter.

creds = SecurityCreds(username='riakuser',
                      # Using the cert information from above
                      crl_file='/ssl_dir/revocation.crl')

Specifying Ciphers

To specify a list of preferred security ciphers, you can pass in a colon-delimited string to the ciphers parameter:

creds = SecurityCreds(username='riakuser',
                      # Using the cert information from above
                      ciphers='X-CIPHER-1:X-CIPHER-2:X-CIPHER-3:ETC')

Using OpenSSL Objects

Whenever you specify certs, you have the option of either passing in file paths as strings (as in the examples above) or properly created OpenSSL objects, e.g. objects created using the pyOpenSSL library. If you generate OpenSSL objects this way, you should note that they must be specified differently when creating a SecurityCreds object. The table below lists the appropriate parameter names for each method, as well as the pyOpenSSL class to which each cert must belong if you create OpenSSL objects.

If you specify filepaths, the appropriate certs will be loaded and converted into the appropriate OpenSSL object. The functions used for this are OpenSSL.crypto.load_privatekey() for the private key and OpenSSL.crypto.load_certificate for the cert and CA cert.