HTTPS certificate

X.509 certificates are used to authorize and secure communications with the server. They are mainly used for HTTPS, but can also be used for SIPS, CTIS, WSS, etc.

There are two categories of certificates in XiVO:

  • the default certificate, used for HTTPS in the web interface, REST APIs and WebSockets
  • the certificates created and managed via the web interface

This article is about the former. For the latter, see Telephony certificates.

Default certificate

XiVO uses HTTPS where possible. The certificates are generated at install time (or during the upgrade to 15.12+). The main certificate is placed in /usr/share/xivo-certs/server.crt.

However, this certificate is self-signed, and HTTP clients (browser or REST API client) will complain about this default certificate because it is not signed by a trusted Certification 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 /usr/share/xivo-certs/server.crt.
  • replace the self-signed certificate with your own trusted certificate.

Regenerating the default certificate

Warning

If you use your own certificate, you should NOT replace it by the default certificate.

  1. Regenerate the default certificate by this command:

    openssl req -x509 -sha256 -nodes -days 3650 -newkey rsa:2048 \
      -config "/usr/share/xivo-config/x509/openssl-x509.conf" \
      -keyout "/usr/share/xivo-certs/server.key" \
      -out "/usr/share/xivo-certs/server.crt"
    
  2. Change ownership and permissions:

    chown root:www-data "/usr/share/xivo-certs/server.key" "/usr/share/xivo-certs/server.crt"
    chmod 640 "/usr/share/xivo-certs/server.key" "/usr/share/xivo-certs/server.crt"
    
  3. Restart all XiVO services by running xivo-service restart all.

Use your own certificate

For this, follow these steps:

  1. Replace the following files with your own private key/certificate pair:

    • Private key: /usr/share/xivo-certs/server.key
    • Certificate: /usr/share/xivo-certs/server.crt
  2. Set correct ownership and permissions:

    chown root:www-data "/usr/share/xivo-certs/server.key" "/usr/share/xivo-certs/server.crt"
    chmod 640 "/usr/share/xivo-certs/server.key" "/usr/share/xivo-certs/server.crt"
    
  3. Change the hostname of XiVO for each XiVO component: the different processes of XiVO heavily use HTTPS for internal communication, and for these connection to establish successfully, all hostnames used must match the Common Name (CN) of your certificate. Basically, you must replace all occurrences of localhost (the default hostname) with your CN in the configuration of the XiVO services. For example:

    mkdir /etc/xivo/custom
    cat > /etc/xivo/custom/custom-certificate.yml << EOF
    consul:
      host: xivo.example.com
    auth:
      host: xivo.example.com
    confd:
      host: xivo.example.com
    dird:
      host: xivo.example.com
    ajam:
      host: xivo.example.com
    agentd:
      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
    
  4. Also, you must replace localhost, in the definition of your directories in the web interface under Configuration ‣ Directories, by the hostname matching the CN of your certificate.

  5. Then, when done, you must re-save, the CTI Directories definition:

    • Go to Services ‣ CTI Server ‣ Directories ‣ Definitions
    • Edit each directory to re-select the new URI
    • And save it
  6. 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.

    First you need to install the debian ca-certificates package:

    apt-get install ca-certificates
    

    If one of the CA (or intermediate CA) of your certificate is not present in the CA shipped by the ca-certificates package you will need to add it manually:

    • Create the following dir if not present:

      mkdir /usr/local/share/ca-certificates/
      
    • Copy inside this directory the certificate of the missing CA in a .crt file

    • And finally upload ca-certificates configuration:

      update-ca-certificates
      

    Then to activate the certificat verification, 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:

    cat > /etc/xivo/custom/custom-certificate.yml << EOF
    consul:
      host: xivo.example.com
      verify: True
    auth:
      host: xivo.example.com
      verify_certificate: True
    dird:
      host: xivo.example.com
      verify_certificate: True
    ...
    

    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.

  7. Ensure your CN resolves to a valid IP address with:

    • a DNS entry
    • and an entry in /etc/hosts resolving your CN to 127.0.0.1. Note that /etc/hosts will be rewritten occasionally by xivo-sysconfd. To make the change persistent, you can:
      1. modify /usr/share/xivo-sysconfd/templates/resolvconf/hosts instead (which will be rewritten when xivo-sysconfd is upgraded…)
      2. then add a script in /usr/share/xivo-upgrade/pre-start.d to re-apply the modification to /usr/share/xivo-sysconfd/templates/resolvconf/hosts after each xivo-upgrade.
  8. Your X.509 certificate must have subjectAltName defined. See the example at cacert.org or detailed documentation at ietf.org.

  9. Restart all XiVO services:

    xivo-service restart all