8.4. SSL authentication

Kamaki supports SSL authenticated connections since version 0.13.

In order to establish secure connections, the https connection module uses a CA certificates PEM file (see the discussion on Certificates at docs.python.org, for more information).

The system CA certificates file location depends on the platform (e.g., /etc/ssl/certs/ca-certifications.crt on Debian Linux), but developers can also provide a custom path.

If the CA certificates path (a) is not set, (b) the file is invalid or (c) the server fails to authenticate against it, a KamakiSSLError ensues. Developers can deactivate SSL errors and connect insecurely instead.

8.4.1. Set CA certificates path

To set the CA certificates path for all connections, use the following piece of code before any kamaki clients are initialized.

from kamaki.clients.utils import https

https.patch_with_certs(CA_CERTS_PATH)

8.4.2. Ignore SSL Errors

from kamaki.clients.utils import https

https.patch_ignore_ssl()

Note

When the connection module is instructed not to use SSL, it won’t attempt to connect securely, even if a certificate is provided.

8.4.3. System CA certificates

The vast majority of systems is equipped with a CA certificates bundle. The location of the file may be different across platforms.

Some copies of kamaki are packaged for specific operating systems, while others are system-ignorant (i.e., installed through pypi, cloned from a GitHub repository or installed from source code).

If a kamaki package is system-aware, the system CA certifications path is set automatically when a kamaki client is initialized. Otherwise, the caller has to provide a CA certificates path.

To check if kamaki is equipped with a default path:

from kamaki import defaults

assert defaults.CACERTS_DEFAULT_PATH, 'No default CA certificates'

8.4.4. CA certificates from CLI config

Some developers use the kamaki CLI config file (e.g., ~/.kamakirc) to configure their application. The kamaki CLI has a global variable ca_certs for the SSL certificates.

from kamaki.cli import config

cnf = config.Config()
ca_certs = cnf.get('global', 'ca_certs')

Note

For convenience, if the configuration file does not contain a ca_certs field, config returns the value of CACERTS_DEFAULT_PATH from kamaki.defaults.

8.4.5. Building kamaki packages with SSL support

To build a kamaki package with SSL support, maintainers must explicitly set the system provided CA certificates path of the target system to CACERTS_DEFAULT_PATH in “kamaki.defaults” module.

The purpose of “kamaki.defaults” is to let package maintainers set constants, the values of which are used at runtime.

In the following example, the CA certificates path is set for a Debian system.

$ tar xvfz kamaki.tar.gz
...
$ echo 'CACERTS_DEFAULT_PATH = /etc/ssl/certs/ca-certificates.crt' \
  >> kamaki/kamaki/defaults.py

Warning

editing the kamaki/kamaki/defaults.py file should be avoided. Maintainers should rather append their settings (valid python code) at the end of the file.

The typical paths for CA certificates differ from system to system. Some of them are listed bellow:

*Debian / Ubuntu / Gentoo / Arch*
`/etc/ssl/certs/ca-certificates.crt`

*Fedora / RedHat*
`/etc/pki/tls/certs/ca-bundle.crt`

*OpenSuse*
`/etc/ssl/ca-bundle.pem`