.. _https_connection:

========================
HTTPS Connection support
========================

The CrateDB Client is able to connect via https.

.. note::

    By default, ssl server certificates are **NOT** verified.

To enable verification, use the keyword argument ``verify_ssl_cert``.
If it is set to ``True``, the server certificate is validated, if set to
``False`` or ommitted, no verification will be done whatsoever.

One can check against a single CA certificate
by creating the client with the a path to a CA certificate file to check against
in keyword argument ``ca_cert``.

.. rubric:: Table of Contents

.. contents::
   :local:

Examples
--------

By default, certificates are not verified. This call is against a server with
a self signed certificate::

    >>> http_client = HttpClient([crate_host])
    >>> http_client.server_infos(http_client._get_server())
    ('https://localhost:65534', 'test', '0.0.0')

When switching on verification without a ``ca_cert`` file provided, the
connection will fail::

    >>> verifying_client = HttpClient([crate_host], verify_ssl_cert=True)
    >>> verifying_client.server_infos(crate_host)
    Traceback (most recent call last):
    ...
    crate.client.exceptions.ConnectionError: Server not available, ...certificate verify failed...

Also when providing an invalid ``ca_cert`` an error is raised::

    >>> verifying_client = HttpClient([crate_host], ca_cert=invalid_ca_cert, verify_ssl_cert=True)
    >>> verifying_client.server_infos(crate_host)
    Traceback (most recent call last):
    ...
    crate.client.exceptions.ConnectionError: Server not available, ...certificate verify failed...

Without verification, the given ``ca_cert`` is ignored and the connection will be
established, to Eves satisfaction.

    >>> non_verifying_client = HttpClient([crate_host], ca_cert=invalid_ca_cert, verify_ssl_cert=False)
    >>> non_verifying_client.server_infos(crate_host)
    ('https://localhost:65534', 'test', '0.0.0')

Connecting to a host whose certificate is verified with a valid CA certificate::

    >>> verifying_valid_client = HttpClient([crate_host], ca_cert=valid_ca_cert, verify_ssl_cert=True)
    >>> verifying_valid_client.server_infos(verifying_valid_client._get_server())
    ('https://localhost:65534', 'test', '0.0.0')


Client Certificate
------------------

The client supports client certificates.

The ``HttpClient`` constructor takes two keyword arguments: ``cert_file`` and
``key_file``. Both should be a string pointing to the path of the client
certificate and key file.

Below an example, in this case it fails because the supplied certificate is
invalid::

    >>> client = HttpClient([crate_host], cert_file=invalid_ca_cert, key_file=invalid_ca_cert, verify_ssl_cert=True)
    >>> client.server_infos(crate_host)
    Traceback (most recent call last):
    ...
    crate.client.exceptions.ConnectionError: Server not available, exception: ...[SSL: ...

