https_certificate.rst 4.53 KB
Newer Older
1
.. _https_certificate:
2

3 4 5
*****************
HTTPS certificate
*****************
Sebastien Duthil's avatar
Sebastien Duthil committed
6

7
X.509 certificates are used to authorize and secure communications with the server. They are mainly
8
used for HTTPS, but can also be used for SIPS, CTIS, WSS, etc.
Sebastien Duthil's avatar
Sebastien Duthil committed
9 10 11

There are two categories of certificates in XiVO:

12
* the default certificate, used for HTTPS in the web interface, REST APIs and WebSockets
13
* the certificates created and managed via the web interface
Sebastien Duthil's avatar
Sebastien Duthil committed
14

15 16
This article is about the former. For the latter, see :ref:`telephony_certificates`.

17 18 19

Default certificate
===================
Sebastien Duthil's avatar
Sebastien Duthil committed
20

21
XiVO uses HTTPS where possible. The certificates are generated at install time (or
Sebastien Duthil's avatar
Sebastien Duthil committed
22 23 24
during the :ref:`upgrade to 15.12+ <upgrade-note-15.12>`). The main certificate is placed in
:file:`/usr/share/xivo-certs/server.crt`.

25
However, this certificate is self-signed, and HTTP clients (browser or REST API client) will
26
complain about this default certificate because it is not signed by a trusted Certification
27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42
Authority (CA).


The default certificate is untrusted
====================================

To make the HTTP client accept this certificate, you have two choices:

* configure your HTTP client to trust the self-signed XiVO certificate by adding a new trusted CA.
  The CA certificate (or bundle) is the file :file:`/usr/share/xivo-certs/server.crt`.
* replace the self-signed certificate with your own trusted certificate.


Use your own certificate
========================

Etienne Lessard's avatar
Etienne Lessard committed
43
For this, follow these steps:
Sebastien Duthil's avatar
Sebastien Duthil committed
44

45
1. Replace the following files with your own private key/certificate pair:
Sebastien Duthil's avatar
Sebastien Duthil committed
46 47 48 49

  * Private key: :file:`/usr/share/xivo-certs/server.key`
  * Certificate: :file:`/usr/share/xivo-certs/server.crt`

50
2. Change the hostname of XiVO for each XiVO component: the different processes of XiVO heavily use
Etienne Lessard's avatar
Etienne Lessard committed
51
   HTTPS for internal communication, and for these connection to establish successfully, all
52
   hostnames used must match the Common Name (CN) of your certificate. Basically, you must replace
Etienne Lessard's avatar
Etienne Lessard committed
53
   all occurrences of ``localhost`` (the default hostname) with your CN in the :ref:`configuration of the
54 55 56 57 58 59 60 61
   XiVO services <configuration-files>`. For example::

      mkdir /etc/xivo/custom
      cat > /etc/xivo/custom/custom-certificate.yml << EOF
      consul:
        host: xivo.example.com
      auth:
        host: xivo.example.com
Etienne Lessard's avatar
Etienne Lessard committed
62 63
      confd:
        host: xivo.example.com
64 65 66 67
      dird:
        host: xivo.example.com
      ajam:
        host: xivo.example.com
68
      agentd:
69 70 71 72 73 74 75 76 77
        host: xivo.example.com
      EOF
      for config_dir in /etc/xivo-*/conf.d/ ; do
          ln -s "/etc/xivo/custom/custom-certificate.yml" "$config_dir/010-custom-certificate.yml"
      done

   Also, you must replace ``localhost`` in the definition of your directories in the web interface
   under :menuselection:`Configuration --> Directories`.

78 79 80 81 82 83 84 85 86 87 88
3. If your certificate is not self-signed, and you obtained it from a third-party CA that is trusted
   by your system, you must enable the system-based certificate verification. By default,
   certificate verification is set to consider ``/usr/share/xivo-certs/server.crt`` as the only CA
   certificate.

   The options are the following:

   * Consul: ``verify: True``
   * Other XiVO services: ``verify_certificate: True``

   The procedure is the same as 2. with more configuration for each service. For example::
89 90 91 92

      cat > /etc/xivo/custom/custom-certificate.yml << EOF
      consul:
        host: xivo.example.com
93
        verify: True
94 95 96
      auth:
        host: xivo.example.com
        verify_certificate: True
97 98 99
      dird:
        host: xivo.example.com
        verify_certificate: True
100 101 102 103 104 105 106
      ...

   Setting ``verify_certificate`` to ``False`` will disable the certificate verification, but the
   connection will still be encrypted. This is pretty safe as long as XiVO services stay on the same
   machine, however, this is dangerous when XiVO services are separated by an untrusted network,
   such as the Internet.

107 108 109
4. Ensure your CN resolves to a valid IP address with either:

   * a DNS entry
110 111 112 113 114 115 116 117
   * an entry in :file:`/etc/hosts` resolving your CN to 127.0.0.1. Note that :file:`/etc/hosts`
     will be rewritten occasionally by xivo-sysconfd. To make the change persistent, you can:

     #. modify :file:`/usr/share/xivo-sysconfd/templates/resolvconf/hosts` instead (which will be
        rewritten when xivo-sysconfd is upgraded...)
     #. then add a script in :file:`/usr/share/xivo-upgrade/pre-start.d` to re-apply the
        modification to :file:`/usr/share/xivo-sysconfd/templates/resolvconf/hosts` after each
        ``xivo-upgrade``.
118 119

5. Restart all XiVO services::
120 121

      xivo-service restart all