.. _encryption:

=======================
Encrypted Communication
=======================

.. warning::

    This document is not complete.

`Thrift documentation on SSL <https://thrift.apache.org/lib/cpp#thriftssl>`_

It is possible to use an encrypted connection when interacting with the Xpert Client through its API.

.. todo::

   provide a high-level description


.. note::

    Usage of encryption must be set in the System Manager. See :ref:`api-smconfig`


Certificate deployment
======================

Diagnosis Tool
--------------

OpenScape Xpert Diagnosis Tool has a feature built in for certificate deployment.
For more information: :download:`Service Manual <../../../Documents/OSX_Service_Manual_V7_Issue2.pdf>`:  6.11 -  Mass deployment of HTEMS certificates for OSX Devices.

.. note::

    It talks about HTEMS certificate replacement but that also replaces the certificates used by the API.


Manual deployment
-----------------

If you only want to deploy certificates for the API - for now - you have to do it manually.
For that you will need the following files:

* ``<platform dir>/api_tls/trusted-cert.pem``: the trusted CA certificate (chain)
* ``<platform dir>/api_tls/server-cert.pem``: the public key
* ``<platform dir>/api_tls/.key/server-key.pem``: the private key

Where ``<platform dir>`` is ``/etc/cert`` for a Linux Turret, and ``C:/Program Files (x86)/Trading_E/Tb/`` for Windows soft-client.

On Linux Turret the file permissions, owners and groups are the following:

.. code-block:: none

    api_tls/:
    -rw-rw-r-- 1 ttadmin certificate 4.6K Jan 22 04:39 server-cert.pem
    -rw-rw-r-- 1 ttadmin certificate 4.3K Jan 22 04:39 trusted-cert.pem

    api_tls/.key/:
    -r---w---- 1 turret certificate 1.7K Nov 30 08:28 server-key.pem

You can set these with the following commands:

.. code-block:: console

    # chown ttadmin:certificate /etc/cert/api_tls/*
    # chmod 664 /etc/cert/api_tls/*

    # chown turret:certificate /etc/cert/api_tls/.key/*
    # chmod 420 /etc/cert/api_tls/.key/*


Generating certificates for development purposes
================================================

For the two-way authentication to work, both parties will need to trust each other. Instead of copying self-signed certificates both ways, setting up our own root CA and signing the certificates with it should be easier and expandable.

.. uml::
   :caption: Overview of the certificate chain

   rectangle "Certificate Authority" {
    file "Root CA" as ca
   }

    'rectangle "Turret" {
      file "Turret Certificate" as sc
      file "Turret Key" as sk
    '}

    file "Client Certificate" as cc
    file "Client Key" as ck

    ca <<-- sc : signed by
    ca <<-- cc : signed by

    sc -- sk
    cc -- ck

.. highlight:: console

.. _enc-keycreate:

Creating a private key
----------------------

Using OpenSSL, generating a private key can be as simple as:

.. code-block::

   $ openssl genrsa -out <filename> 2048

.. note::

    The genrsa command can be supplied with different arguments for example a cipher for encrypting the key. More info in the `OpenSSL documentation for genrsa <https://www.openssl.org/docs/man1.1.1/man1/genrsa.html>`_.

Create CA certificate
---------------------

First we need a private key for the certificate authority, for example ``trusted.key``. (See :ref:`enc-keycreate`)

Armed with that key we can now become a Certificate Authority:

.. code-block::

   $ openssl req -x509 -new -nodes -key trusted.key -days 3650 -out trusted-cert.pem

This prompts for some information but neither of them really matter for our purposes.

More info on `openssl req <https://www.openssl.org/docs/man1.1.1/man1/openssl-req.html>`_.

Creating a signed certificate for the Turret
--------------------------------------------

Since the Turret API uses the `DefaultClientAccessManager <https://github.com/apache/thrift/blob/master/lib/cpp/src/thrift/transport/TSSLSocket.h#L428>`_ for client validation, creating a certificate for the turret will need some more information.

From the official Thrift site regarding `Access Managers <https://thrift.apache.org/lib/cpp#accessmanager-certificate-validation>`_ we can see that our certificate will need at least one of the following fields:

* IP subjectAltName
* DNS subjectAltName
* common name

With that information in mind first we need a private key eg. ``server-key.pem`` and armed with that we can create a certificate signing request:

.. code-block:: console

   $ openssl req -new -key server-key.pem -out server.csr

Prompting you to enter similar information as before. On the *Common Name* prompt you may enter the server IP address/DNS name optionally and skip adding the subject alternative name.

Subject Alternative Name is an extension, so to add that to the certificate we will need a configuration file.

.. code-block:: none
   :caption: turret-altnames.conf

    [ san_ext ]
    subjectAltName = @alt_names

    [alt_names]
    DNS = <DNS name>
    IP  = <IP address>


Now that we have a Certificate Signing Request and the configuration file we can turn to the CA (also us) to sign the public key for the turret.

.. code-block:: console

    $ openssl x509 -req -days 365 \
    >   -CA trusted-cert.pem -CAkey trusted.key -CAcreateserial \
    >   -in server.csr -out server-cert.pem \
    >   -extensions san_ext -extfile turret-altnames.conf

And now we have all three files we need to deploy to the Turret.

More info on `openssl x509 <https://www.openssl.org/docs/man1.1.1/man1/x509.html>`_.

Creating a signed certificate for our application can be done in a similar fashion.


Using certificate in 3rd party app
==================================

See `Encryption Example`
