Commit 850eb094 authored by Stavros Sachtouris's avatar Stavros Sachtouris

Document secure connections in kamaki.clients lib

Refs grnet/kamaki#59

Add an SSL Authentication section under "Developers Guide".
Update existing examples and descriptions with SSL related information.
parent 14ef92cb
......@@ -16,6 +16,22 @@ of the modules implement the Synnefo extensions (i.e., *cyclades* and
*cyclades_rest_api* extents *compute*, *pithos* and *pithos_rest_api* extent
*storage*).
Secure connections
------------------
Before setting up any clients, developers are advised to check whether a CA
certificates chain file is set, or set one themselves.
.. code-block:: python
from kamaki import defaults
from kamaki.clients.utils import https
if not defaults.CACERTS_DEFAULT_PATH:
https.patch_with_certs(CA_CERTS_PATH)
Check the :ref:`clients-ssl` section for more details on the subject.
Setup a client instance
-----------------------
......
......@@ -29,6 +29,40 @@ This is the pseudocode:
#. Register the image file to the **Plankton** *image* service
#. Create a number of virtual servers to the **Cyclades** *compute* service
Secure connections
------------------
To facilitate secure connections, the https connection module should be
patched before initializing any clients. The rational and the details are
sketched in the :ref:`clients-ssl` section.
.. code-block:: python
from kamaki import defaults
from kamaki.cli import config
from kamaki.clients.utils import https
# kamaki.config
cnf = config.Config()
# If kamaki has default CA certificates path, it uses it automatically
if not defaults.CACERTS_DEFAULT_PATH:
# There is no default CA certificates path - look it up in config
ca_certs = cnf.get('global', 'ca_certs')
if not ca_certs:
# There is no CA certificates path in config - ask the user
ca_certs = raw_input(
'Warning: No CA certificates path\n Options:\n'
' * <RETURN> for insecure connection\n'
' * <ctrl-C> to cancel\n'
' * Provide a CA certificates path\n: ')
if ca_certs:
# Use this CA certificates path
https.patch_with_certs(ca_certs)
else:
# Risk insecure connections
https.patch_to_raise_ssl_errors(False)
Credentials and endpoints
-------------------------
......@@ -575,15 +609,33 @@ logging more. We also added some command line interaction candy.
from kamaki.cli.logger import get_logger, add_file_logger
from progress.bar import Bar
from logging import DEBUG
from kamaki.cli import config
from kamaki import defaults
from kamaki.clients.utils import https
# Define loggers
log = get_logger(__name__)
add_file_logger('kamaki.clients', DEBUG, '%s.log' % __name__)
add_file_logger(__name__, DEBUG, '%s.log' % __name__)
# Create progress bar generator
# kamaki.config
cnf = config.Config()
# Setup SSL authentication
if not defaults.CACERTS_DEFAULT_PATH:
ca_certs = cnf.get('global', 'ca_certs')
if not ca_certs:
ca_certs = raw_input(
'Warning: No CA certificates path\n Options:\n'
' * <RETURN> for insecure connection\n'
' * <ctrl-C> to cancel\n'
' * Provide a CA certificates path\n: ')
if ca_certs:
https.patch_with_certs(ca_certs)
else:
https.patch_to_raise_ssl_errors(False)
# Create progress bar generator
def create_pb(msg):
def generator(n):
bar = Bar(msg)
......@@ -592,22 +644,18 @@ logging more. We also added some command line interaction candy.
yield
return generator
# kamaki.config
# Identity,Account / Astakos
def init_astakos():
from kamaki.clients.astakos import AstakosClient
from kamaki.cli.config import Config, CONFIG_PATH
print(' Get the credentials')
cnf = Config()
# Get default cloud name
try:
cloud_name = cnf.get('global', 'default_cloud')
except KeyError:
log.debug('No default cloud set in file %' % CONFIG_PATH)
log.debug('No default cloud set in file %' % config.CONFIG_PATH)
raise
try:
......
.. _clients-ssl:
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 file (see the discussion on
`Certificates <https://docs.python.org/2/library/ssl.html#ssl-certificates>`_
at docs.python.org, for more information).
The 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 <#set-ca-certificates-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 <#ignore-ssl-errors>`_ and connect insecurely
instead.
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.
.. code-block:: python
from kamaki.clients.utils import https
https.patch_with_certs(CA_CERTS_PATH)
Ignore SSL Errors
-----------------
.. code-block:: python
from kamaki.clients.utils import https
https.patch_to_raise_ssl_errors(False)
.. note:: Ignoring SSL errors works like this:
The https connection module attempts a secure connection.
If it fails, it falls back to an insecure connection.
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 typical CA certifications path for the
system is set automatically when a kamaki client is initialized.
If the copy is system-ignorant, the caller has to
`provide a CA certificates path <#set-ca-certificates-path>`_.
To check if kamaki is equipped with a default path:
.. code-block:: python
from kamaki import defaults
assert defaults.CACERTS_DEFAULT_PATH, 'No default CA certificates'
CA certificates path from config
--------------------------------
The following concerns developers who have set a CA certificates path in kamaki
config. To check if kamaki config is aware of a CA path:
.. code-block:: console
$ kamaki config get ca_certs
To extract the CA certificates path from config:
.. code-block:: python
from kamaki.cli import config
cnf = config.Config()
ca_certs = cnf.get('global', 'ca_certs')
.. note:: If the configuration file does not contain a ca_certs field, config
returns the value of CACERTS_DEFAULT_PATH from "kamaki.defaults".
Building 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, set the CA certificates path for a Debian system.
.. code-block:: console
$ 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 (in 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`
......@@ -7,6 +7,7 @@ Developers Guide
developers/clients-api
developers/config
developers/ssl
developers/logging
developers/adding-commands
developers/extending-clients-api
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment