TLS settings

Last modified by Félix Olart on 2023/10/13 15:44

Note: only flexisip-proxy is able to process TLS connections. Thus, the other Flexisip servers (flexisip-presence, flexisip-conference, etc.) must listen on a private network (or localhost) and always use a flexisip-proxy server as an outgoing proxy to communicate with the public network.

Enabling TLS

Any transport using sips as URI scheme will use TLS as transport layer. If no port is specified, 5061 will be used. Of course, several sips transports can be declared.

The host part of the transport URI should be the Common Name of the associated certificate, so that the Common Name can be used as a host in Via and Recour-Route headers.

[global]
transports=sips:sip.example.org

Private keys and certificates

Flexisip 2.2 and later

All the parameters about TLS are in [global] section and are prefixed by tls-*.

tls-certificates-file	Path to a file which contains the server X.509 certificate and the chain of certificate if required
tls-certificates-private-key	Path to the private key
tls-certificates-ca-file	Path to a file which contains a list of certificates to use in addition of system CA certificate to validate client certificates or peer server certificates.

Flexisip 2.1 and earlier (Deprecated)

By default, all declared sips transports use the key and certificate placed in /etc/flexisip/tls directory. This path can be changed by using [Global]/tls-certificates-dir parameter.

The certificate and the private key must be formatted as PEM and concatenated in /etc/flexisip/tls/agent.pem. If intermediate certificates are needed to validate the server certificate, they must be placed in /etc/flexisip/tls/cafile.pem. This file may also contains other chains of certificates which may be used for validating client certificates.

If you need to have a specific certificate for some transports, then you have to create a specific TLS directory to hold the specific agent.pem and cafile.pem files and change the TLS directory to use by using the tls-certificates-dir parameter on the transport URI.

# In this example, the certificate placed in /etc/flexisip/tls/default is used by sip.example.org and sip2.example.org
# transports, and the one placed in /etc/flexisip/tls/other-domain.com is used by sip.other-domain.com only.

[global]
transports=sips:sip.example.org sips:sip2.example.org sips:sip.other-domain.com;tls-certificates-dir=/etc/flexisip/tls/other-domain.com
tls-certificates-dir=/etc/flexisip/tls/default

Note: when a Flexisip instance is part of a cluster, it may be available by its domain name (by using SRV resolution) or by its host name. In such a situation, the certificate must both validate the domain name and the host name, or SIP clients may refuse to connect because of TLS security issues. A wildcard certificate may also be used.

TLS policy

Switch on/off certificate verification

There are two extra transport URI parameters for that:

tls-verify-outgoing=0/1	Switch on/off the verification of the remote certificate when Flexisip connects on another SIP server (enabled by default)
tls-verify-incoming=0/1	Switch on/off the verification of client certificates when there is one (disabled by default)

If the verification of one certificate fails, then the TLS connection is immediately closed and the SIP message is not delivered.

Select authorized ciphers and their priority

This is global to all sips transports and is defined by [global]/tls-ciphers.

It takes a cipher list in OpenSSL cipher list format.

TLS configuration for a specific transport

Each transport in the transport line can override the global TLS configuration by adding tls-* parameter to the transport URI.

For instance:

[global]
transports=sips:sip.example.org sips:sip.other-example.org;tls-certificate=<certificate_path>;tls-private-key=<private_key_path>

tls-certificate=<default_certificate_path>
tls-private-key=<default_private_key>

In this example, the proxy can accept TLS connections to sip.example.org and sip.example2.org. The default certificate will be used for sip.example.org and a custom certificate will be used for sip.other-example.org.