.. _https:

Enable Data Encryption
===============================

.. rubric:: In this chapter:

.. contents::
   :local:

To ensure data security, we recommend enabling SSL encryption. FindFace Multi version 2.3 supports deployment with HTTPS during :ref:`Standalone Automated Deployment <installer>`. We strongly recommend enabling HTTPS when deploying FindFace Multi. If manual HTTPS installation is required, follow these steps:

#. On the host system, create the nginx configuration directory with the subdirectory that will be used to store all the SSL data:

   .. code::

      sudo mkdir -p /opt/findface-multi/configs/ssl/

#. Create the SSL key and certificate files. When using a self-signed certificate, execute the following command, replacing ``external_address`` with the server’s external IP address:

   .. code::

      sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -addext "subjectAltName = DNS:localhost, DNS:findface-multi-ui, IP:external_address" -keyout /opt/findface-multi/configs/ssl/domain.key -out /opt/findface-multi/configs/ssl/domain.crt

   You will be asked a few questions about your server in order to embed the information correctly in the certificate. Fill out the prompts appropriately. The most important line is the one that requests the ``Common Name``. You need to enter the domain name or public IP address that you want to be associated with your server. Both of the files you created (``domain.key`` and ``domain.crt``) will be placed in the ``/opt/findface-multi/configs/ssl/`` directory.

#. Add the certificate path to **volumes** for the ``findface-video-worker`` service. In the service container, add the root certificate store update command to **entrypoint**.

    #. Open the ``/opt/findface-multi/docker-compose.yaml`` file:

       .. code::

          sudo vi /opt/findface-multi/docker-compose.yaml

    #. Locate the ``findface-video-worker`` section and adjust it to make sure it looks as follows.

       .. rubric:: CPU

       .. code:: yaml

          findface-video-worker:
            entrypoint: ["sh", "-c", "update-ca-certificates && exec /tini -- /findface-video-worker-cpu --config=/etc/findface-video-worker.yaml"]
            depends_on: [findface-video-manager, findface-ntls, mongodb]
            image: docker.int.ntl/ntech/universe/video-worker-cpu:ffserver-12.241211.2
            logging: {driver: journald}
            networks: [product-network]
            restart: always
            volumes: ['./configs/findface-video-worker/findface-video-worker.yaml:/etc/findface-video-worker.yaml:ro',
              './models:/usr/share/findface-data/models:ro', './cache/findface-video-worker/models:/var/cache/findface/models_cache',
              './cache/findface-video-worker/recorder:/var/cache/findface/video-worker-recorder',
              '/opt/findface-multi/configs/ssl/domain.crt:/usr/local/share/ca-certificates/domain.crt']

       .. rubric:: GPU

       .. code:: yaml

          findface-video-worker:
            entrypoint: ["sh", "-c", "update-ca-certificates && exec /tini -- /findface-video-worker-gpu --config=/etc/findface-video-worker.yaml"]
            depends_on: [findface-video-manager, findface-ntls, mongodb]
            environment: [CUDA_VISIBLE_DEVICES=0]
            image: docker.int.ntl/ntech/universe/video-worker-gpu:ffserver-12.241211.2
            logging: {driver: journald}
            networks: [product-network]
            restart: always
            runtime: nvidia
            volumes: ['./configs/findface-video-worker/findface-video-worker.yaml:/etc/findface-video-worker.yaml:ro',
              './models:/usr/share/findface-data/models:ro', './cache/findface-video-worker/models:/var/cache/findface/models_cache',
              './cache/findface-video-worker/recorder:/var/cache/findface/video-worker-recorder',
              '/opt/findface-multi/configs/ssl/domain.crt:/usr/local/share/ca-certificates/domain.crt']

#. Configure nginx to use SSL. Open the nginx configuration file ``/opt/findface-multi/configs/findface-multi-ui/nginx-site.conf``. Apply the following modifications to the file:

    #. Comment out the following lines in the existing ``server {...}`` section

       .. code::

          # listen 80 default_server;
          # listen [::]:80 default_server;

       and add the following lines:

       .. code::

         listen 443 ssl;
         listen [::]:443 ssl;

    #. Uncomment out the following lines in the existing ``server {...}`` section:

       .. code::

          ssl_certificate /etc/ssl/domain.crt;
          ssl_certificate_key /etc/ssl/domain.key;

          ssl_protocols TLSv1.2 TLSv1.1 TLSv1;

          http2 on;

       The example of the configuration file ``/opt/findface-multi/configs/findface-multi-ui/nginx-site.conf`` with correctly configured SSL settings you can find :download:`here <_scripts/nginx-site_ssl.conf>`.

#. In the ``/opt/findface-multi/docker-compose.yaml`` file, mount the SSL-encryption data directory ``/opt/findface-multi/configs/ssl/`` into the ``findface-multi-findface-multi-ui-1`` container:

    #. Open the ``/opt/findface-multi/docker-compose.yaml`` file:

       .. code::

          sudo vi /opt/findface-multi/docker-compose.yaml

    #. Locate the ``findface-multi-ui`` section and adjust it to make sure it looks like this:

       * Add ``'443:443'`` to the ``ports`` section,
       * Add ``'/opt/findface-multi/configs/ssl:/etc/ssl'`` to the ``volumes`` section.

       .. code:: yaml

          findface-multi-ui:
            depends_on: [findface-multi-legacy]
            image: docker.int.ntl/ntech/multi/multi/ui:ffmulti-2.3.0
            logging: {driver: journald}
            networks: [product-network]
            ports: ['80:80','443:443']
            restart: always
            volumes: ['./configs/findface-multi-ui/nginx-site.conf:/etc/nginx/conf.d/default.conf:ro',
              './data/findface-multi-legacy/uploads:/var/lib/findface-security/uploads',
              '/opt/findface-multi/configs/ssl:/etc/ssl']

    #. Adjust the service configurations:

       * For the ``backend_api`` and ``service_alarmer`` services, replace the ``http://`` prefix with ``https://`` in the ``DSN_IMAGE_EXTERNAL_ADDRESS`` environment variable.
       * For the ``backend_api``, ``service_notifier_ws`` and ``service_notifier_tg`` services, replace the ``http://`` prefix with ``https://`` in the ``DSN_FF_AUTH`` environment variable.
       * For the ``backend_api``, ``service_notifier_ws`` and ``service_notifier_tg`` services, add **volumes** as shown below.
       * For the ``backend_api``, ``service_notifier_ws`` and ``service_notifier_tg`` services, change the start command to ``[sh, -c, update-ca-certificates && python -m backend_api]``, ``[sh, -c, update-ca-certificates && python -m service_notifier.ws]`` and ``[sh, -c, update-ca-certificates && python -m service_notifier.tg]`` respectively.

       .. code:: yaml

          backend_api:
            command: [sh, -c, update-ca-certificates && python -m backend_api]
            depends_on:
              timescaledb: {condition: service_healthy}
            environment: {DSN_FF_AUTH: 'https://findface-multi-ui/', DSN_FF_VIDEO_MANAGER: 'http://findface-video-manager:18810/',
              DSN_FF_VIDEO_STORAGE: 'http://findface-video-storage:18611/', DSN_IMAGE_EXTERNAL_ADDRESS: 'https://<ip_address>',
              DSN_PG: 'postgresql+asyncpg://ntech:<...>@timescaledb:5433/annex',
              SERVER_HOST: 0.0.0.0, SERVER_PORT: '2222'}
            image: docker.int.ntl/presale/annex:2.0.2
            logging: {driver: journald}
            networks: [product-network]
            restart: always
            volumes: &id007 ['/opt/findface-multi/configs/ssl/domain.crt:/usr/local/share/ca-certificates/domain.crt']
          service_alarmer:
            command: [python, -m, service_alarmer]
            depends_on:
              rabbitmq: {condition: service_healthy}
              timescaledb: {condition: service_healthy}
            environment: {DROP_ALL: 'False', DSN_AMQP: 'amqp://ntech:<...>@rabbitmq:5672/',
              DSN_FF_UPLOAD: 'http://findface-upload:3333/', DSN_IMAGE_EXTERNAL_ADDRESS: 'https://<ip_address>',
              DSN_PG: 'postgresql+asyncpg://ntech:<...>@timescaledb:5433/annex'}
            image: docker.int.ntl/presale/annex:2.0.2
            logging: {driver: journald}
            networks: [product-network]
            restart: always
          service_notifier_ws:
            command: [sh, -c, update-ca-certificates && python -m service_notifier.ws]
            depends_on:
              rabbitmq: {condition: service_healthy}
            environment: {CHECK_ACCESS: 'True', DSN_AMQP: 'amqp://ntech:<....>@rabbitmq:5672/',
              DSN_FF_AUTH: 'https://findface-multi-ui/', SERVER_HOST: 0.0.0.0, SERVER_PORT: 3311,
              USER_AUTOFILL: 'True'}
            image: docker.int.ntl/presale/annex:2.0.2
            logging: {driver: journald}
            networks: [product-network]
            ports: ['3311:3311']
            restart: always
            volumes: *id007
          service_notifier_tg:
            command: [sh, -c, update-ca-certificates && python -m service_notifier.tg]
            depends_on:
              rabbitmq: {condition: service_healthy}
            environment: {ALLOWED_SERVICES: null, ALLOWED_STREAMS: null, BOT_TOKEN: '', DSN_AMQP: 'amqp://ntech:<...>@rabbitmq:5672/',
              DSN_FF_AUTH: 'https://findface-multi-ui/', DSN_REDIS: 'redis://@redis:6379/1',
              USER_AUTOFILL: 'True'}
            image: docker.int.ntl/presale/annex:2.0.2
            logging: {driver: journald}
            networks: [product-network]
            volumes: *id007


#. Edit the ``/opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.py`` configuration file.

    #. In the ``ROUTER_URL`` parameter, substitute the ``http://`` prefix with ``https://``.

       .. code::

          sudo vi /opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.py

          ...
          'ROUTER_URL': 'https://findface-multi-ui',
          ...

    #.  If you use a CA-certificate, specify in the ``ROUTER_URL`` parameter the domain for which the certificate was created:

        .. code::

          'ROUTER_URL': 'https://my-example-domain.com'

    #. In the ``EXTERNAL_ADDRESS`` parameter, replace the ``http://`` prefix with ``https://``.

       .. code::

          ...
          EXTERNAL_ADDRESS = 'https://<ip_address_server_ffmulti>'
          ...

    #. In the ``ANNEX_URL`` parameter, replace the ``http://`` prefix with ``https://``.

       .. code::

          ...
          'ANNEX_URL': 'https://findface-multi-ui/service_alarmer/alarms/'
          ...


#. In the system where you use a browser to interact with FindFace Multi navigate to the ``hosts`` file. Add IP address of the server that hosts FindFace Multi instead of the ``ip_address_server_ffmulti``. Replace ``my-example-domain.com`` with your domain address – the same way you did it in the previous steps.

    #. For Linux OS do the following:

       .. code::

         sudo vi /etc/hosts

         ...
         ip_address_server_ffmulti my-example-domain.com

    #. If you use Windows OS, run ``C:\Windows\System32\drivers\etc\hosts`` as an administrator. Add the following line to the ``hosts`` file:

       .. code::

         ip_address_server_ffmulti my-example-domain.com

#. In the ``/opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.py`` configuration file, uncomment the following lines:

   .. code::

      USE_X_FORWARDED_HOST = True
      SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')


#. Restart all FindFace Multi containers.

   .. code::

      cd /opt/findface-multi/

      sudo docker-compose down
      sudo docker-compose up -d


#. When using a self-signed certificate, you must specify the ``findface-multi-ui`` and the server’s IP addresses in the ``subjectAltName`` field to ensure correct SSL verification (see step #2). If the ``subjectAltName`` field is not specified in the self-signed certificate, you must disable SSL certificate verification for cameras and uploaded video archives.

    #. Navigate to the :guilabel:`Video Sources` → :guilabel:`Cameras` or :guilabel:`Uploads`.
    #. Click to the camera or uploaded video archive.
    #. On the :guilabel:`Advanced` tab, uncheck :guilabel:`Verify the SSL certificate`.

       |camera_verify_SSL_en|

       .. |camera_verify_SSL_en| image:: /_static/camera_verify_SSL_en.png
          :scale: 70%

       .. |camera_verify_SSL_ru| image:: /_static/camera_verify_SSL_ru.png
          :scale: 70%

#. To use WebSocket Secure with :ref:`Alarm Monitor <alarm_monitor_settings>`, ensure that you include ``wss://`` before the connection server address (e.g. ``wss://ip_address/annex/``).


How to Enable Recommended Security Settings
-----------------------------------------------------

If necessary, enable the recommended nginx security settings.

#. To enhance traffic protection, create a ``dhparam`` file using the following command:

   .. code::

        sudo openssl dhparam -out /opt/findface-multi/configs/ssl/dhparam.pem 4096

#. Open the nginx configuration file ``/opt/findface-multi/configs/findface-multi-ui/nginx-site.conf``. Apply the following modifications to the file:

    #. Add the path to the ``dhparam`` file and the string with the header ``Strict-Transport-Security`` to the existing section ``server {...}``:

       .. code::

         ssl_dhparam /etc/ssl/dhparam.pem;
         add_header Strict-Transport-Security "max-age=31536000; includeSubdomains; preload";

    #. Replace ``server_name _;`` with ``server_name my-example-domain.com;``.

    #. Replace ``set $cors_origin "*";`` with ``set $cors_origin "my-example-domain.com";``.

    #. Replace ``ssl_protocols TLSv1.2 TLSv1.1 TLSv1;`` with ``ssl_protocols TLSv1.2 TLSv1.3;``.

    #. Copy the generic nginx configuration file ``nginx.conf`` from the ``findface-multi-findface-multi-ui-1`` container to the ``/etc/nginx/`` directory:

       .. code::

         sudo docker cp findface-multi-findface-multi-ui-1:/etc/nginx/nginx.conf /etc/nginx/nginx.conf

    #. In the ``/etc/nginx/nginx.conf`` configuration file, find the ``SSL Settings`` section and append the following lines:

       .. code::

	 ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305;
	 ssl_session_cache builtin:1000 shared:SSL:10m;

	 ssl_session_tickets off;
	 ssl_session_timeout 1d;
	 ssl_session_cache shared:SSL:10m;
	 ssl_stapling on;
	 ssl_stapling_verify on;

#. In the ``/opt/findface-multi/docker-compose.yaml`` file, mount the configuration file ``/etc/nginx/nginx.conf`` of the host system into the ``findface-multi-findface-multi-ui-1`` container:

    #. Open the ``/opt/findface-multi/docker-compose.yaml`` file:

       .. code::

	       sudo vi /opt/findface-multi/docker-compose.yaml

    #. Locate the ``findface-multi-ui`` section and adjust it to make sure it looks like this:

       .. code:: yaml

      	 findface-multi-ui:
      	   depends_on: [findface-multi-legacy]
      	   image: docker.int.ntl/ntech/multi/multi/ui:ffmulti-2.3.0
            logging: {driver: journald}
            networks: [product-network]
            ports: ['80:80', '443:443']
      	   restart: always
      	   volumes: ['./configs/findface-multi-ui/nginx-site.conf:/etc/nginx/conf.d/default.conf:ro',
      	     './data/findface-multi-legacy/uploads:/var/lib/findface-security/uploads',
      	     '/opt/findface-multi/configs/ssl:/etc/ssl',
      	     '/etc/nginx/nginx.conf:/etc/nginx/nginx.conf:ro']

#. For automatic HTTP-to-HTTPS redirection, add in the configuration file ``/opt/findface-multi/configs/findface-multi-ui/nginx-site.conf`` the new ``server {...}`` section that contains the URL replacement rule. In the ``rewrite ^(.*) https://…`` line, replace ``ip_address_server_ffmulti`` with IP address of the server where FindFace Multi is installed.

       .. code::

          sudo vi /opt/findface-multi/configs/findface-multi-ui/nginx-site.conf

          ...
          server {
                  listen 80;
                  server_name my-example-domain.com www.my-example-domain.com;
                  rewrite ^(.*) https://ip_address_server_ffmulti$1 permanent;
                  access_log off;
          }

#. Restart all FindFace Multi containers.

   .. code::

      cd /opt/findface-multi/

      sudo docker-compose down
      sudo docker-compose up -d

How to Replace a Self-Signed Certificate With a Verified One After Installation
------------------------------------------------------------------------------------------

#. When using a verified certificate for SSL configuration in FindFace Multi, ensure that you copy the certificate and key to the ``/opt/findface-multi/configs/ssl`` directory on the host.

#. If the file names of the certificate and key differ from ``domain.key`` and ``domain.crt``, you must:

    * **Rename** the existing files to match the default names (``domain.key`` and ``domain.crt``) (preferred),
    * Otherwise, edit the ``/opt/findface-multi/configs/findface-multi-ui/nginx-site.conf`` and ``/opt/findface-multi/docker-compose.yaml`` configuration files to use your current file names.

#. After replacing the certificate and key files and changing the settings files, restart the FindFace Multi containers.

   .. code::

      cd /opt/findface-multi/

      sudo docker-compose down
      sudo docker-compose up -d


.. note::

        To avoid errors when using cameras and uploaded video archives, either of the following conditions must be met:

        * The domain name in the certificate’s CN (Common Name) is accessible from the ``findface-video-worker`` container and is specified in the ``ROUTER_URL`` value in the ``/opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.py`` configuration file.
        * :guilabel:`Verify the SSL certificate` setting is disabled in the camera and video archive settings.