TLS_MGM module

This module is a management module for TLS certificates and parameters. It provides an interfaces for all the modules that use the TLS protocol. It also implements TLS related functions to use in the routing script, and exports pseudo variables with certificate and TLS parameters.

1.2. Usage

This module is used to provision TLS certificates and parameters for all the modules that use TLS transport (like proto_tls or proto_wss). The module supports multiple virtual domains that can be assigned to different listeners (servers) or new connections (clients). Each TLS module that uses this management module should assign itself to one or more domains.

The module allows the definition of the TLS domains both via module parameters (script level) and via an SQL table.

A script example which details this module's usage can be found in Section 1.10, “OpenSIPS with TLS - script example”.

1.3. TLS domains

The wording 'TLS domain' means that this TLS connection will have different parameters than another TLS connection (from another TLS domain). Thus, TLS domains are not directly related to different SIP domains, although they are often used in common. Depending on the direction of the TLS handshake, a TLS domain is called 'client domain' (=outgouing TLS connection) or 'server domain' (= incoming TLS connection).

If you only run one domain, a default domain is enough. If you are running several TLS servers (that is, you have more than one listen=tls:ip:port entry in the config file), you can specify some parameters for each of them separately (not all the above).

For example, TLS domains can be used in virtual hosting scenarios with TLS. OpenSIPS offers SIP service for multiple domains, e.g. atlanta.com and biloxi.com. Altough both domains will be hosted a single SIP proxy, the SIP proxy needs 2 certificates: One for atlanta.com and one for biloxi.com. For incoming TLS connections, the SIP proxy has to present the respective certificate during the TLS handshake. As the SIP proxy does not have a received SIP message yet (this is done after the TLS handshake), the SIP proxy can not retrieve the target domain (which will be usually retrieved from the domain in the request URI). Thus, distinction for these domains must be done by using multiple sockets. The socket on which the TLS connection is received, identifies the respective domain. Thus the SIP proxy is able to present the proper certificate.

For outgoing TLS connections, the SIP proxy usually has to provide a client certificate. In this scenario, socket based distinction is not preferable as there is no dedicated outgoing socket. Thus, the certificate selection (selection of the proper TLS client domain) can be name based. If the SIP proxy establishes a new outgoing TLS connection, it checks for the TLS client domain AVP (parameter client_domain_avp). If this AVP is set (e.g. in OpenSIPS.cfg), OpenSIPS searches for a TLS client domain with the same name as the AVP value and uses the associated certificates.

TLS client domains can also be matched by socket. If no TLS client domain AVP is found, OpenSIPS searches for a TLS client domain based on the destination socket of the underlying outgoing TCP connection that must match with the defined address for a client domain.

Note: If there is already an existing TLS connection to the remote target, it will be reused wether the TLS client domain AVP matches or not.

NOTE: Make sure to also configure OpenSIPS to listen on the specified IP:port.

NOTE: Except tls_handshake_timeout and tls_send_timeout all TLS parameters can be set per TLS domain. If a parameter is not explicit set, the default value will be used.

It's usable only if TLS support was compiled.

1.4. Defining TLS domains

TLS domains can be defined in two ways:

by setting the server_domain or client_domain module parameters
by provisioning in DB

For the domains defined in the DB, the certificate, private key, list of trusted CAs and Diffie-Hellman parameters are provisioned as BLOB values whether for script defined domains you must provide path to files.

When a TLS domain can't be chosen for an outgoing or incoming TLS connection the default client or server domain is used. A default domain is automatically created (with default settings) but you can also set the certificate, private key etc. in the same way as for other domains (through the module parameters or by DB).

The default domains from the DB (provisioned with the domain name default) overwrite the standard default domains even if you have set ceratain parameters (certificate, ca_list etc.) for the default domain through the script. When defining default domains in the DB you can specificy a default client or server domain separately or a single specification to be used for both scenarios.

You can define domains both in the DB and script at the same time (even default domains).

For any TLS domain (defined through script or DB, default or virtual) if not specified otherwise, the default settings are:

method - SSLv23
verify_cert - 1
require_cert - 1
certificate - CFG_DIR/tls/cert.pem
private_key - CFG_DIR/tls/ckey.pem
crl_check_all - 0
crl_dir - none
ca_list - none
ca_dir - /etc/pki/CA/
cipher_list - the OpenSSL default ciphers
dh_params - none
ec_curve - none

1.5. Dependencies of external libraries

OpenSIPS TLS v1.0 support requires the following packages:

openssl or libssl >= 0.9.6
openssl-dev or libssl-dev

OpenSIPS TLS v1.1/1.2 support requires the following packages:

openssl or libssl >= 1.0.1e
openssl-dev or libssl-dev

1.6. Exported Functions

1.6.1. `is_peer_verified`

Returns 1 if the message is received via TLS and the peer was verified during TLS connection handshake, otherwise it returns -1

This function can be used from REQUEST_ROUTE.

Example 1.1. is_peer_verified usage

...
if (is_peer_verified()) {
        xlog("L_INFO","request from verified TLS peer\n");
} else {
        xlog("L_INFO","request not verified\n");
}
...

1.7. Exported MI Functions

1.7.1. `tls_list`

List all domains information.

1.7.2. `tls_reload`

Reloads the TLS domains information from the database. The previous DB defined domains are discarded but the script defined domains are preserved. If no new default client or server domains is loaded and previously the default was DB defined, the standard default domain is reinstated.

1.8. OpenSIPS Exported parameters

All these parameters can be used from the opensips.cfg file, to configure the behavior of OpenSIPS-TLS.

1.8.1. `listen`=interface

Not specific to TLS. Allows to specify the protocol (udp, tcp, tls), the IP address and the port where the listening server will be.

Example 1.2. Set listen variable

...
listen = tls:1.2.3.4:5061
...

1.8.2. `tls_method` ([domain]string)

Sets the TLS protocol. The domain, if set, represents the name of the TLS domain. TLS method which can be:

TLSv1_2 - means OpenSIPS will accept only TLSv1.2 connections (rfc3261 conformant).
TLSv1 - means OpenSIPS will accept only TLSv1 connections (rfc3261 conformant).
SSLv3 - means OpenSIPS will accept only SSLv3 connections
SSLv2 - means OpenSIPS will accept only SSLv2 connections (almost all old clients support this).
SSLv23 - means OpenSIPS will accept any of the above methods, but the initial SSL hello must be v2 (in the initial hello all the supported protocols are advertised enabling switching to a higher and more secure version). The initial v2 hello means it will not accept connections from SSLv3 or TLSv1 only clients.

Default value is SSLv23.

Warning

Best is to use SSLv23, for extended compatibility. Using any of the other will restrict the version to just that one version. In fact, SSLv2 is disabled in the source code; to use it, you need to edit tls/tls_init.c

If you want RFC3261 conformance and all your clients support TLSv1 (or you are planning to use encrypted "tunnels" only between different OpenSIPS proxies) use TLSv1. If you want to support older clients use SSLv23 (in fact most of the applications with SSL support use the SSLv23 method).

Example 1.3. Set tls_method variable

...
modparam("tls_mgm", "tls_method", "TLSv1")
modparam("tls_mgm", "tls_method", "[dom]TLSv1")
...

1.8.3. `certificate` ([domain](string)

Public certificate file for OpenSIPS. It will be used as server-side certificate for incoming TLS connections, and as a client-side certificate for outgoing TLS connections. The domain, if set, represents the name of the TLS domain.

Default value is "CFG_DIR/tls/cert.pem".

Example 1.4. Set certificate variable

...
modparam("tls_mgm", "certificate", "/mycerts/certs/opensips_server_cert.pem")
modparam("tls_mgm", "certificate", "[dom]/mycerts/certs/opensips_server_cert.pem")
...

1.8.4. `private_key` ([domain](string)

Private key of the above certificate. I must be kept in a safe place with tight permissions! The domain, if set, represents the name of the TLS omain.

Default value is "CFG_DIR/tls/ckey.pem".

Example 1.5. Set private_key variable

...
modparam("tls_mgm", "private_key", "/mycerts/private/prik.pem")
modparam("tls_mgm", "private_key", "[dom]/mycerts/private/prik.pem")
...

1.8.5. `ca_list` ([domain](string)

List of trusted CAs. The file contains the certificates accepted, one after the other. It MUST be a file, not a folder. The domain, if set, represents the name of the TLS domain.

Default value is "".

Example 1.6. Set ca_list variable

...
modparam("tls_mgm", "ca_list", "/mycerts/certs/ca_list.pem")
modparam("tls_mgm", "ca_list", "[dom]/mycerts/certs/ca_list.pem")
...

1.8.6. `ca_dir` ([domain](string)

Directory storing trusted CAs. The path contains the certificates accepted, each as hash which is linked to certificate file. The domain, if set, represents the name of the TLS domain.

Default value is "/etc/pki/CA/".

Example 1.7. Set ca_dir variable

...
modparam("tls_mgm", "ca_dir", "/mycerts/certs")
modparam("tls_mgm", "ca_dir", "[dom]/mycerts/certs")
...

1.8.7. `ciphers_list` ([domain](string)

You can specify the list of algorithms for authentication and encryption that you allow. The domain, if set, represents the name of the TLS domain. To obtain a list of ciphers and then choose, use the openssl application:

openssl ciphers 'ALL:eNULL:!LOW:!EXPORT'

Warning

Do not use the NULL algorithms (no encryption) ... only for testing!!!

It defaults to the OpenSSL default ciphers.

Example 1.8. Set ciphers_list variable

...
modparam("tls_mgm", "ciphers_list", "NULL")
modparam("tls_mgm", "ciphers_list", "[dom]NULL")
...

1.8.8. `dh_params` ([domain](string)

You can specify a file which contains Diffie-Hellman parameters as a PEM-file. This is needed if you would like to specify ciphers including Diffie-Hellman mode. The domain, if set, represents the name of the TLS domain.

It defaults to not set a dh param file.

Example 1.9. Set dh_params variable

...
modparam("tls_mgm", "dh_params", "/etc/pki/CA/dh1024.pem")
modparam("tls_mgm", "dh_params", "[dom]/etc/pki/CA/dh1024.pem")
...

1.8.9. `ec_curve` ([domain](string)

You can specify an elliptic curve which should be used for ciphers which demand an elliptic curve. The domain, if set, represents the name of the TLS domain.

It's usable only if TLS v1.1/1.2 support was compiled. A list of curves which can be used you can get by

				openssl ecparam -list_curves

It defaults to not set a elliptic curve.

1.8.10. `verify_cert` ([domain](string) and `require_cert` ([domain](string)

Technically, verify_cert activates SSL_VERIFY_PEER in the ssl_context. 'require_cert' does the same with SSL_VERIFY_FAIL_IF_NO_PEER_CERT, which is only possible if SSL_VERIFY_PEER is also turned on. Since version 2.1, these parameters act have been reduced to only one. They act both on client side and server side if no domain specified, elseway they act on a specific domain, depending on the first parameter.

These two parameters are used for incoming TLS connections, where OpenSIPS acts as server.

It's usable only if TLS support was compiled.

Default value for both is 1.

Example 1.10. Set verify_cert & require_cert variable

...
# turn on the strictest and strongest authentication possible
modparam("tls_mgm", "require_cert", "1")
modparam("tls_mgm", "require_cert", "[dom]1")
modparam("tls_mgm", "verify_cert", "0")
modparam("tls_mgm", "verify_cert", "[dom]1")
...

1.8.11. `tls_handshake_timeout` (integer)

Sets the timeout (in milliseconds) for the handshake sequence to complete. It may be necessary to increase this value when using a CPU intensive cipher for the connection to allow time for keys to be generated and processed.

The timeout is invoked during acceptance of a new connection (inbound) and during the wait period when a new session is being initiated (outbound).

Default value is 100.

Example 1.11. Set tls_handshake_timeout variable

...
modparam("tls_mgm", "tls_handshake_timeout", 200) # number of milliseconds
...

1.8.12. `tls_send_timeout` (integer)

Sets the timeout (in milliseconds) for the send operations to complete

The send timeout is invoked for all TLS write operations, excluding the handshake process (see: tls_handshake_timeout)

Default value is 100.

Example 1.12. Set tls_send_timeout variable

...
modparam("tls_mgm", "tls_send_timeout", 200) # number of milliseconds
...

1.8.13. `client_domain_avp` (integer)

This sets the AVP used for name based TLS client domain matching (please see Section 1.8.30, “server_domain, client_domain (string)” for more details). Setting the value to 0 disables name based TLS client domain matching.

It's usable only if TLS support was compiled.

Default value is 0.

Example 1.13. Set client_domain_avp variable

...
modparam("tls_mgm", "client_domain_avp", "tls_cli_dom")
...

1.8.14. `db_url` (string)

The database url. It cannot be NULL.

Example 1.14. Usage of db_url block

modparam("tls_mgm", "db_url", "mysql://root:admin@localhost/opensips")

1.8.15. `db_table` (string)

Sets the database table name.

Default value is "tls_mgm".

Example 1.15. Usage of db_table block

modparam("tls_mgm", "db_table", "tls_mgm")

1.8.16. `domain_col` (string)

Sets the name.for the TLS domain column.

Default value is "domain".

Example 1.16. Usage of domain_col block

modparam("tls_mgm", "domain_col", "tls_domain")

1.8.17. `address_col` (string)

Sets the address column name.

Default value is "address".

Example 1.17. Usage of address_col block

modparam("tls_mgm", "address_col", "addr")

1.8.18. `tls_method_col` (string)

Sets the method column name.

Default value is "method".

Example 1.18. Usage of tls_method_col block

modparam("tls_mgm", "tls_method_col", "method")

1.8.19. `verify_cert_col` (string)

Sets the verrify certificate column name.

Default value is "verify_cert".

Example 1.19. Usage of vertify_cert_col block

modparam("tls_mgm", "verify_cert_col", "verify_cert")

1.8.20. `require_cert_col` (string)

Sets the require certificate column name.

Default value is "require_cert".

Example 1.20. Usage of require_cert_col block

modparam("tls_mgm", "require_cert_col", "req")

1.8.21. `certificate_col` (string)

Sets the certificate column name.

Default value is "certificate".

Example 1.21. Usage of certificate_col block

modparam("tls_mgm", "certificate_col", "certificate")

1.8.22. `private_key_col` (string)

Sets the private key column name.

Default value is "private_key".

Example 1.22. Usage of private_key_col block

modparam("tls_mgm", "private_key_col", "pk")

1.8.23. `crl_check_all_col` (string)

Sets the crl_check_all column name.

Default value is "crl_check_all".

Example 1.23. Usage of crl_check_all block

modparam("tls_mgm", "crl_check_all_col", "crl_check")

1.8.24. `crl_dir_col` (string)

Sets the crl directory column name.

Default value is "crl_dir".

Example 1.24. Usage of crl_dir_col block

modparam("tls_mgm", "crl_dir_col", "crl_dir")

1.8.25. `ca_list_col` (string)

Sets the CA list column name.

Default value is "ca_list".

Example 1.25. Usage of ca_list_col block

modparam("tls_mgm", "ca_list_col", "ca_list")

1.8.26. `ca_dir_col` (string)

Sets the CA directory column name.

Default value is "ca_dir".

Example 1.26. Usage of ca_dir_col block

modparam("tls_mgm", "ca_dir_col", "ca_dir")

1.8.27. `cipher_list_col` (string)

Sets the cipher list column name.

Default value is "cipher_list".

Example 1.27. Usage of cipher_list_col block

modparam("tls_mgm", "cipher_list_col", "cipher_list")

1.8.28. `dh_params_col` (string)

Sets the Diffie-Hellmann parameters column name.

Default value is "dh_params".

Example 1.28. Usage of dh_params_col block

modparam("tls_mgm", "dh_params_col", "dh_parms")

1.8.29. `ec_curve_col` (string)

Sets the ec_curve column name.

Default value is "ec_curve".

Example 1.29. Usage of ec_curve_col block

modparam("tls_mgm", "ec_curve_col", "ec_curve")

1.8.30. `server_domain, client_domain` (string)

You can define virtual TLS domains through these parameters.

The syntax for defining a domain is "domain=IP:port" where the 'domain' is the domain name and the address part is optional for client domains.

Example 1.30. Usage of tls_client_domain and tls_server_domain block

...
listen=tls:IP_2:port2
listen=tls:IP_3:port3
...
# set the TLS client domain AVP
modparam("proto_tls", "client_domain_avp", "tls_cli_dom")
...

# 'atlanta' server domain
modparam("tls_mgm", "server_domain", "dom1=IP_2:port2")

modparam("tls_mgm", "certificate", "[dom1]/certs/atlanta.com/cert.pem")
modparam("tls_mgm", "private_key", "[dom1]/certs/atlanta.com/privkey.pem")
modparam("tls_mgm", "ca_list", "[dom1]/certs/wellknownCAs")
modparam("tls_mgm", "tls_method", "[dom1]tlsv1")
modparam("tls_mgm", "verify_cert", "[dom1]1")
modparam("tls_mgm", "require_cert", "[dom1]1")

#'biloxy' server domain

modparam("tls_mgm", "server_domain", "dom2=IP_3:port3")

modparam("tls_mgm", "certificate", "[dom2]/certs/biloxy.com/cert.pem")
modparam("tls_mgm", "private_key", "[dom2]/certs/biloxy.com/privkey.pem")
modparam("tls_mgm", "ca_list", "[dom2]/certs/wellknownCAs")
modparam("tls_mgm", "tls_method", "[dom2]tlsv1")
modparam("tls_mgm", "verify_cert", "[dom2]1")
modparam("tls_mgm", "require_cert", "[dom2]1")

# 'atlanta' client domain
modparam("tls_mgm", "client_domain", "dom3")

modparam("tls_mgm", "certificate", "[dom3]/certs/atlanta.com/cert.pem")
modparam("tls_mgm", "private_key", "[dom3]/certs/atlanta.com/privkey.pem")
modparam("tls_mgm", "ca_list", "[dom3]/certs/wellknownCAs")
modparam("tls_mgm", "tls_method", "[dom3]tlsv1")
modparam("tls_mgm", "verify_cert", "[dom3]1")
modparam("tls_mgm", "require_cert", "[dom3]1")

#'biloxy' client domain
modparam("tls_mgm", "client_domain", "dom4")

modparam("tls_mgm", "certificate", "[dom4]/certs/biloxy.com/cert.pem")
modparam("tls_mgm", "private_key", "[dom4]/certs/biloxy.com/privkey.pem")
modparam("tls_mgm", "ca_list", "[dom4]/certs/wellknownCAs")
modparam("tls_mgm", "tls_method", "[dom4]tlsv1")
modparam("tls_mgm", "verify_cert", "[dom4]1")
modparam("tls_mgm", "require_cert", "[dom4]1")


# socket based TLS server domains (for TLS based downstream from GW provider)
modparam("tls_mgm", "client_domain", "dom5=IP_5:port5")

modparam("tls_mgm", "certificate", "[dom5]/certs/atlanta.com/cert.pem")
modparam("tls_mgm", "private_key", "[dom5]/certs/atlanta.com/privkey.pem")
modparam("tls_mgm", "ca_list", "[dom5]/certs/wellknownCAs")
modparam("tls_mgm", "tls_method", "[dom5]tlsv1")
modparam("tls_mgm", "verify_cert", "[dom5]0")

# socket based TLS client domains (for TLS based upstream to GW provider)
# GW IP: 1.2.3.4, GW port: 6677
modparam("tls_mgm", "client_domain", "dom6=1.2.3.4:6677")

modparam("tls_mgm", "certificate", "[dom6]/certs/biloxy.com/cert.pem")
modparam("tls_mgm", "private_key", "[dom6]/certs/biloxy.com/privkey.pem")
modparam("tls_mgm", "ca_list", "[dom6]/certs/wellknownCAs")
modparam("tls_mgm", "tls_method", "[dom6]tlsv1")
modparam("tls_mgm", "verify_cert", "[dom6]0")

...
route{
...
    # for biloxy or atlanta domains we set the TLS client domain AVP
    if ($rd == "atlanta.com")
        $avp(tls_cli_dom) = "dom3";
    else if ($rd == "biloxy.com")
        $avp(tls_cli_dom) = "dom4";
...
    # calls to other SIP domains
    # set the proper SSL context (certificate) for local hosted domains
    t_relay(); # uses NAPTR and SRV lookups
    exit;
...
    # calls to the PSTN GW
    t_relay("tls:1.2.3.4:6677");
    exit;
...

1.9. Variables

This module exports the follong variables:

Some variables are available for both, the peer'S certificate and the local certificate. Further, some parameters can be read from the “Subject” field or the “Issuer” field.

1.9.1. $tls_version

$tls_version - the TLS/SSL version which is used on the TLS connection from which the message was received. String type.

1.9.2. $tls_description

$tls_description - the TLS/SSL description of the TLS connection from which the message was received. String type.

1.9.3. $tls_cipher_info

$tls_cipher_info - the TLS/SSL cipher which is used on the TLS connection from which the message was received. String type.

1.9.4. $tls_cipher_bits

$tls_cipher_bits - the number of cipher bits which are used on the TLS connection from which the message was received. String and Integer type.

1.9.5. $tls_[peer|my]_version

$tls_[peer|my]_version - the version of the certificate. String type.

1.9.6. $tls_[peer|my]_serial

$tls_[peer|my]_serial - the serial number of the certificate. String and Integer type.

1.9.7. $tls_[peer|my]_[subject|issuer]

$tls_[peer|my]_[subject|issuer] - ASCII dump of the fields in the issuer/subject section of the certificate. String type.

Example 1.31. Example of $tls_[peer|my]_[subject|issuer]

/C=AT/ST=Vienna/L=Vienna/O=enum.at/CN=enum.at

1.9.8. $tls_[peer|my]_[subject|issuer]_cn

$tls_[peer|my]_[subject|issuer]_cn - commonName in the issuer/subject section of the certificate. String type.

1.9.9. $tls_[peer|my]_[subject|issuer]_locality

$tls_[peer|my]_[subject|issuer]_locality - localityName in the issuer/subject section of the certificate. String type.

1.9.10. $tls_[peer|my]_[subject|issuer]_country

$tls_[peer|my]_[subject|issuer]_country - countryName in the issuer/subject section of the certificate. String type.

1.9.11. $tls_[peer|my]_[subject|issuer]_state

$tls_[peer|my]_[subject|issuer]_state - stateOrProvinceName in the issuer/subject section of the certificate. String type.

1.9.12. $tls_[peer|my]_[subject|issuer]_organization

$tls_[peer|my]_[subject|issuer]_organization - organizationName in the issuer/subject section of the certificate. String type.

1.9.13. $tls_[peer|my]_[subject|issuer]_unit

$tls_[peer|my]_[subject|issuer]_unit - organizationalUnitName in the issuer/subject section of the certificate. String type.

1.9.14. $tls_[peer|my]_san_email

$tls_[peer|my]_san_email - email address in the “subject alternative name” extension. String type.

1.9.15. $tls_[peer|my]_san_hostname

$tls_[peer|my]_san_hostname - hostname (DNS) in the “subject alternative name” extension. String type.

1.9.16. $tls_[peer|my]_san_uri

$tls_[peer|my]_san_uri - URI in the “subject alternative name” extension. String type.

1.9.17. $tls_[peer|my]_san_ip

$tls_[peer|my]_san_ip - ip address in the “subject alternative name” extension. String type.

1.9.18. $tls_peer_verified

$tls_peer_verified - Returns 1 if the peer's certificate was successful verified. Otherwise it returns 0. String and Integer type.

1.9.19. $tls_peer_revoked

$tls_peer_revoked - Returns 1 if the peer's certificate was revoked. Otherwise it returns 0. String and Integer type.

1.9.20. $tls_peer_expired

$tls_peer_expired - Returns 1 if the peer's certificate is expired. Otherwise it returns 0. String and Integer type.

1.9.21. $tls_peer_selfsigned

$tls_peer_selfsigned - Returns 1 if the peer's certificate is selfsigned. Otherwise it returns 0. String and Integer type.

1.9.22. $tls_peer_notBefore

$tls_peer_notBefore - Returns the notBefore validity date of the peer's certificate. String type.

1.9.23. $tls_peer_notAfter

$tls_peer_notAfter - Returns the notAfter validity date of the peer's certificate. String type.

1.10. OpenSIPS with TLS - script example

IMPORTANT: The TLS support is based on TCP, and for allowing OpenSIPS to use TCP, it must be started in multi-process mode. So, there is a must to have the "fork" parameter set to "yes":

NOTE: Since the TLS engine is quite memory consuming, increase the used memory by the run time parameter "-m" (see OpenSIPS -h for more details).

fork = yes

Example 1.32. Script with TLS support

  # ----------- global configuration parameters ------------------------
  log_level=3
  log_stderror=no

  check_via=no
  dns=no
  rev_dns=no
  listen=udp:your_serv_IP:5060
  listen=tls:your_serv_IP:5061
  children=4

  # ------------------ module loading ----------------------------------

  loadmodule "proto_tls.so"
  loadmodule "proto_udp.so"

  #TLS specific settings
  loadmodule "tls_mgm.so"

  modparam("tls_mgm", "certificate", "/path/opensipsX_cert.pem")
  modparam("tls_mgm", "private_key", "/path/privkey.pem")
  modparam("tls_mgm", "ca_list", "/path/calist.pem")
  modparam("tls_mgm", "ca_list", "/path/calist.pem")
  modparam("tls_mgm", "require_cert", "1")
  modparam("tls_mgm", "verify_cert", "1")

  alias=_DNS_ALIAS_


  loadmodule "sl.so"
  loadmodule "rr.so"
  loadmodule "maxfwd.so"
  loadmodule "mysql.so"
  loadmodule "usrloc.so"
  loadmodule "registrar.so"
  loadmodule "tm.so"
  loadmodule "auth.so"
  loadmodule "auth_db.so"
  loadmodule "textops.so"
  loadmodule "sipmsgops.so"
  loadmodule "signaling.so"
  loadmodule "uri_db.so"

  # ----------------- setting module-specific parameters ---------------

  # -- auth_db params --
  modparam("auth_db", "db_url", "sql_url")
  modparam("auth_db", "password_column", "password")
  modparam("auth_db", "calculate_ha1", 1)

  # -- registrar params --
  # no multiple registrations
  modparam("registrar", "append_branches", 0)

  # -------------------------  request routing logic -------------------

  # main routing logic

  route{

  # initial sanity checks
  if (!mf_process_maxfwd_header("10")) {
      send_reply("483","Too Many Hops");
      exit;
  };

  # if somene claims to belong to our domain in From,
  # challenge him (skip REGISTERs -- we will chalenge them later)
  if (from_uri==myself) {
      setflag(1);
      if ( is_method("INVITE|SUBSCRIBE|MESSAGE")
      && !(src_ip==myself) ) {
          if  (!(proxy_authorize( "domA.net", "subscriber" ))) {
              proxy_challenge("domA.net","0"/*no-qop*/);
              exit;
          };
          if (!db_check_from()) {
              xlog("FROM hdr Cheating attempt in INVITE\n");
              send_reply("403",
                  "That is ugly -- use From=id next time (OB)");
              exit;
          };
      }; # non-REGISTER from other domain
  } else if ( is_method("INVITE") && uri!=myself ) {
      send_reply("403", "No relaying");
      exit;
  };

  /* ********   do record-route and loose-route ******* */
  if (!is_method("REGISTER"))
      record_route();

  if (loose_route()) {
      append_hf("P-hint: rr-enforced\r\n");
      t_relay();
      exit;
  };

  /* ******* check for requests targeted out of our domain ******* */
  if ( uri!=myself ) {
      append_hf("P-hint: OUTBOUND\r\n");
      if ($rd=="domB.net") {
          t_relay("tls:domB.net:5061");
      } else if ($rd=="domC.net") {
          t_relay("tls:domC.net:5061");
      } else {
          t_relay();
      };
      exit;
  };

  /* ******* divert to other domain according to prefixes ******* */
  if (!is_method("REGISTER")) {
      if ( $ru=~"sip:201") {
          strip(3);
          $rd = "domB.net";
          t_relay("tls:domB.net:5061");
          exit;
      } else if ( uri=~"sip:202" ) {
          strip(3);
          $rd = "domC.net";
          t_relay("tls:domC.net:5061");
          exit;
      };
  };

  /* ************ requests for our domain ********** */
  if (is_method("REGISTER")) {
      if (!www_authorize( "domA.net", "subscriber" )) {
          # challenge if none or invalid credentials
          www_challenge( "domA.net" /* realm */,
              "0" /* no qop -- some phones can't deal with it */);
          exit;
      };
      if (!db_check_to()) {
          xlog("TO hdr Cheating attempt\n");
          send_reply("403", "That is ugly -- use To=id in REGISTERs");
          exit;
      };
      # it is an authenticated request, update Contact database now
      if (!save("location")) {
          sl_reply_error();
      };
      exit;
  };

  # native SIP destinations are handled using USRLOC DB
  if (!lookup("location")) {
      # handle user which was not found
      send_reply("404", "Not Found");
      exit;
  };

  # remove all present Alert-info headers
  remove_hf("Alert-Info");

  if (is_method("INVITE") && ($rP=="TLS" || isflagset(1))) {
      append_hf("Alert-info: 1\r\n");                     # cisco 7960
      append_hf("Alert-info: Bellcore-dr4\r\n");          # cisco ATA
      append_hf("Alert-info: http://foo.bar/x.wav\r\n");  # snom
  };

  # do forwarding
  if (!t_relay()) {
      sl_reply_error();
  };

  #end of script
  }

1.11. Debug TLS connections

If you want to debug TLS connections, put the following log statements into your OpenSIPS.cfg. This will dump all available TLS pseudo variables.

Example 1.33. Example of TLS logging

xlog("L_INFO","================= start TLS pseudo variables ===============\n");
xlog("L_INFO","$$tls_version                   = '$tls_version'\n");
xlog("L_INFO","$$tls_description               = '$tls_description'\n");
xlog("L_INFO","$$tls_cipher_info               = '$tls_cipher_info'\n");
xlog("L_INFO","$$tls_cipher_bits               = '$tls_cipher_bits'\n");
xlog("L_INFO","$$tls_peer_subject              = '$tls_peer_subject'\n");
xlog("L_INFO","$$tls_peer_issuer               = '$tls_peer_issuer'\n");
xlog("L_INFO","$$tls_my_subject                = '$tls_my_subject'\n");
xlog("L_INFO","$$tls_my_issuer                 = '$tls_my_issuer'\n");
xlog("L_INFO","$$tls_peer_version              = '$tls_peer_version'\n");
xlog("L_INFO","$$tls_my_version                = '$tls_my_version'\n");
xlog("L_INFO","$$tls_peer_serial               = '$tls_peer_serial'\n");
xlog("L_INFO","$$tls_my_serial                 = '$tls_my_serial'\n");
xlog("L_INFO","$$tls_peer_subject_cn           = '$tls_peer_subject_cn'\n");
xlog("L_INFO","$$tls_peer_issuer_cn            = '$tls_peer_issuer_cn'\n");
xlog("L_INFO","$$tls_my_subject_cn             = '$tls_my_subject_cn'\n");
xlog("L_INFO","$$tls_my_issuer_cn              = '$tls_my_issuer_cn'\n");
xlog("L_INFO","$$tls_peer_subject_locality     = '$tls_peer_subject_locality'\n");
xlog("L_INFO","$$tls_peer_issuer_locality      = '$tls_peer_issuer_locality'\n");
xlog("L_INFO","$$tls_my_subject_locality       = '$tls_my_subject_locality'\n");
xlog("L_INFO","$$tls_my_issuer_locality        = '$tls_my_issuer_locality'\n");
xlog("L_INFO","$$tls_peer_subject_country      = '$tls_peer_subject_country'\n");
xlog("L_INFO","$$tls_peer_issuer_country       = '$tls_peer_issuer_country'\n");
xlog("L_INFO","$$tls_my_subject_country        = '$tls_my_subject_country'\n");
xlog("L_INFO","$$tls_my_issuer_country         = '$tls_my_issuer_country'\n");
xlog("L_INFO","$$tls_peer_subject_state        = '$tls_peer_subject_state'\n");
xlog("L_INFO","$$tls_peer_issuer_state         = '$tls_peer_issuer_state'\n");
xlog("L_INFO","$$tls_my_subject_state          = '$tls_my_subject_state'\n");
xlog("L_INFO","$$tls_my_issuer_state           = '$tls_my_issuer_state'\n");
xlog("L_INFO","$$tls_peer_subject_organization = '$tls_peer_subject_organization'\n");
xlog("L_INFO","$$tls_peer_issuer_organization  = '$tls_peer_issuer_organization'\n");
xlog("L_INFO","$$tls_my_subject_organization   = '$tls_my_subject_organization'\n");
xlog("L_INFO","$$tls_my_issuer_organization    = '$tls_my_issuer_organization'\n");
xlog("L_INFO","$$tls_peer_subject_unit         = '$tls_peer_subject_unit'\n");
xlog("L_INFO","$$tls_peer_issuer_unit          = '$tls_peer_issuer_unit'\n");
xlog("L_INFO","$$tls_my_subject_unit           = '$tls_my_subject_unit'\n");
xlog("L_INFO","$$tls_my_issuer_unit            = '$tls_my_issuer_unit'\n");
xlog("L_INFO","$$tls_peer_san_email            = '$tls_peer_san_email'\n");
xlog("L_INFO","$$tls_my_san_email              = '$tls_my_san_email'\n");
xlog("L_INFO","$$tls_peer_san_hostname         = '$tls_peer_san_hostname'\n");
xlog("L_INFO","$$tls_my_san_hostname           = '$tls_my_san_hostname'\n");
xlog("L_INFO","$$tls_peer_san_uri              = '$tls_peer_san_uri'\n");
xlog("L_INFO","$$tls_my_san_uri                = '$tls_my_san_uri'\n");
xlog("L_INFO","$$tls_peer_san_ip               = '$tls_peer_san_ip'\n");
xlog("L_INFO","$$tls_my_san_ip                 = '$tls_my_san_ip'\n");
xlog("L_INFO","$$tls_peer_verified             = '$tls_peer_verified'\n");
xlog("L_INFO","$$tls_peer_revoked              = '$tls_peer_revoked'\n");
xlog("L_INFO","$$tls_peer_expired              = '$tls_peer_expired'\n");
xlog("L_INFO","$$tls_peer_selfsigned           = '$tls_peer_selfsigned'\n");
xlog("L_INFO","$$tls_peer_notBefore            = '$tls_peer_notBefore'\n");
xlog("L_INFO","$$tls_peer_notAfter             = '$tls_peer_notAfter'\n");
xlog("L_INFO","================= end TLS pseudo variables ===============\n");

Chapter 2. Developer Guide

2.1. API Functions

2.1.1. find_server_domain

struct tls_domain *find_server_domain(struct ip_addr *ip, unsigned short port);

Find a TLS server domain with given ip and port (local listening socket).

2.1.2. find_client_domain

struct tls_domain *find_client_domain(struct ip_addr *ip, unsigned short port);

Find TLS client domain.

2.1.3. get_handshake_timeout

int get_handshake_timeout(void);

Returns the handshanke timeout.

2.1.4. get_send_timeout

int get_send_timeout(void);

Returns the send timeout.

2.2. TLS_CONFIG

It contains configuration variables for OpenSIPS's TLS (timeouts, file paths, etc).

2.3. TLS_INIT

Initialization related functions and parameters.

2.3.1. ssl context

extern SSL_CTX *default_client_ctx;

The ssl context is a member of the TLS domain strcuture. Thus, every TLS domain, default and virtual - servers and clients, have its own SSL context.

2.3.2. pre_init_tls

int init_tls(void);

Called once to pre_initialize the tls subsystem, from the main(). Called before parsing the configuration file.

2.3.3. init_tls

int init_tls(void);

Called once to initialize the tls subsystem, from the main(). Called after parsing the configuration file.

2.3.4. destroy_tls

void destroy_tls(void);

Called once, just before cleanup.

2.3.5. tls_init

int tls_init(struct socket_info *c);

Called once for each tls socket created, from main.c

2.3.6. os_malloc, os_realloc, os_free

Wrapper functions around the shm_* functions. OpenSSL uses non-shared memory to create its objects, thus it would not work in OpenSIPS. By creating these wrappers and configuring OpenSSL to use them instead of its default memory functions, we have all OpenSSL objects in shared memory, ready to use.

2.4. TLS_DOMAIN

2.4.1. tls_domains

extern struct tls_domain *tls_default_server_domain;

The default TLS server domain.

extern struct tls_domain *tls_default_client_domain;

The default TLS client domain.

extern struct tls_domain *tls_server_domains;

List with defined server domains.

extern struct tls_domain *tls_client_domains;

List with defined client domains.

2.4.2. tls_find_server_domain

struct tls_domain *tls_find_server_domain(struct ip_addr *ip, unsigned short port);

Find a TLS server domain with given ip and port (local listening socket).

2.4.3. tls_find_client_domain

struct tls_domain *tls_find_client_domain(struct ip_addr *ip, unsigned short port);

Find TLS client domain.

2.4.4. tls_find_client_domain_addr

struct tls_domain *tls_find_client_domain_addr(struct ip_addr *ip, unsigned short port);

Find TLS client domain with given ip and port (socket of the remote destination).

2.4.5. tls_find_client_domain_name

struct tls_domain *tls_find_client_name(str name);

Find TLS client domain with given name.

2.4.6. tls_new__domain

struct tls_domain *tls_new_domain(int type);

Creates new TLS: allocate memory, set the type and initialize members

2.4.7. tls_new_server_domain

int tls_new_server_domain(struct ip_addr *ip, unsigned short port);

Creates and adds to the list of TLS server domains a new domain.

2.4.8. tls_new_client_domain

int tls_new_client_domain(struct ip_addr *ip, unsigned short port);

Creates and adds to the list of TLS client domains a new socket based domain.

2.4.9. tls_new_client_domain_name

int tls_new_client_domain_name(char *s, int len);

Creates and adds to the list of TLS client domains a new name based domain.

2.4.10. tls_free_domains

void tls_free_domains(void);

Cleans up the entire domain lists.

Chapter 3. Contributors

3.1. By Commit Statistics

Table 3.1. Top contributors by DevScore⁽¹⁾, authored commits⁽²⁾ and lines added/removed⁽³⁾

	Name	DevScore	Commits	Lines ++	Lines --
1.	Eseanu Marius Cristian (@eseanucristian)	51	11	4268	321
2.	Vlad Patrascu (@rvlad-patrascu)	46	11	1678	1130
3.	Razvan Crainea (@razvancrainea)	32	24	504	223
4.	Bogdan-Andrei Iancu (@bogdan-iancu)	20	9	268	447
5.	Ionut Ionita (@ionutrazvanionita)	17	9	383	169
6.	Liviu Chircu (@liviuchircu)	13	8	88	175
7.	Ionel Cerghit (@ionel-cerghit)	7	1	494	109
8.	Callum Guy	3	1	34	9
9.	Ovidiu Sas (@ovidiusas)	3	1	1	1
10.	Maksym Sobolyev (@sobomax)	2	1	3	0

(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)

(2) including any documentation-related commits, excluding merge commits. Regarding imported patches/code, we do our best to count the work on behalf of the proper owner, as per the "fix_authors" and "mod_renames" arrays in opensips/doc/build-contrib.sh. If you identify any patches/commits which do not get properly attributed to you, please submit a pull request which extends "fix_authors" and/or "mod_renames".

(3) ignoring whitespace edits, renamed files and auto-generated files

3.2. By Commit Activity

Table 3.2. Most recently active contributors⁽¹⁾ to this module

	Name	Commit Activity
1.	Vlad Patrascu (@rvlad-patrascu)	Apr 2017 - Sep 2018
2.	Bogdan-Andrei Iancu (@bogdan-iancu)	Mar 2016 - Jun 2018
3.	Callum Guy	Jun 2018 - Jun 2018
4.	Liviu Chircu (@liviuchircu)	Oct 2015 - Jun 2018
5.	Razvan Crainea (@razvancrainea)	Sep 2015 - Apr 2018
6.	Ovidiu Sas (@ovidiusas)	Jun 2017 - Jun 2017
7.	Ionut Ionita (@ionutrazvanionita)	Apr 2016 - Apr 2017
8.	Ionel Cerghit (@ionel-cerghit)	Aug 2016 - Aug 2016
9.	Maksym Sobolyev (@sobomax)	Mar 2016 - Mar 2016
10.	Eseanu Marius Cristian (@eseanucristian)	Sep 2015 - Sep 2015

(1) including any documentation-related commits, excluding merge commits

Chapter 4. Documentation

4.1. Contributors

Last edited by: Bogdan-Andrei Iancu (@bogdan-iancu), Callum Guy, Liviu Chircu (@liviuchircu), Razvan Crainea (@razvancrainea), Vlad Patrascu (@rvlad-patrascu), Eseanu Marius Cristian (@eseanucristian).

TLS_MGM module

Chapter 1. Admin Guide

1.1. Overview

1.2. Usage

1.3. TLS domains

1.4. Defining TLS domains

1.5. Dependencies of external libraries

1.6. Exported Functions

1.6.1. is_peer_verified

1.7. Exported MI Functions

1.7.1. tls_list

1.7.2. tls_reload

1.8. OpenSIPS Exported parameters

1.8.1. listen=interface

1.8.2. tls_method ([domain]string)

Warning

1.8.3. certificate ([domain](string)

1.8.4. private_key ([domain](string)

1.8.5. ca_list ([domain](string)

1.8.6. ca_dir ([domain](string)

1.8.7. ciphers_list ([domain](string)

Warning

1.8.8. dh_params ([domain](string)

1.8.9. ec_curve ([domain](string)

1.8.10. verify_cert ([domain](string) and require_cert ([domain](string)

1.8.11. tls_handshake_timeout (integer)

1.8.12. tls_send_timeout (integer)

1.8.13. client_domain_avp (integer)

1.8.14. db_url (string)

1.8.15. db_table (string)

1.8.16. domain_col (string)

1.8.17. address_col (string)

1.8.18. tls_method_col (string)

1.8.19. verify_cert_col (string)

1.8.20. require_cert_col (string)

1.8.21. certificate_col (string)

1.8.22. private_key_col (string)

1.8.23. crl_check_all_col (string)

1.8.24. crl_dir_col (string)

1.8.25. ca_list_col (string)

1.8.26. ca_dir_col (string)

1.8.27. cipher_list_col (string)

1.8.28. dh_params_col (string)

1.8.29. ec_curve_col (string)

1.8.30. server_domain, client_domain (string)

1.9. Variables

1.9.1. $tls_version

1.9.2. $tls_description

1.9.3. $tls_cipher_info

1.9.4. $tls_cipher_bits

1.9.5. $tls_[peer|my]_version

1.9.6. $tls_[peer|my]_serial

1.9.7. $tls_[peer|my]_[subject|issuer]

1.9.8. $tls_[peer|my]_[subject|issuer]_cn

1.9.9. $tls_[peer|my]_[subject|issuer]_locality

1.9.10. $tls_[peer|my]_[subject|issuer]_country

1.9.11. $tls_[peer|my]_[subject|issuer]_state

1.9.12. $tls_[peer|my]_[subject|issuer]_organization

1.9.13. $tls_[peer|my]_[subject|issuer]_unit

1.9.14. $tls_[peer|my]_san_email

1.9.15. $tls_[peer|my]_san_hostname

1.9.16. $tls_[peer|my]_san_uri

1.9.17. $tls_[peer|my]_san_ip

1.9.18. $tls_peer_verified

1.9.19. $tls_peer_revoked

1.9.20. $tls_peer_expired

1.9.21. $tls_peer_selfsigned

1.9.22. $tls_peer_notBefore

1.9.23. $tls_peer_notAfter

1.10. OpenSIPS with TLS - script example

1.11. Debug TLS connections

Chapter 2. Developer Guide

2.1. API Functions

2.1.1. find_server_domain

2.1.2. find_client_domain

2.1.3. get_handshake_timeout

2.1.4. get_send_timeout

2.2. TLS_CONFIG

2.3. TLS_INIT

2.3.1. ssl context

1.6.1. `is_peer_verified`

1.7.1. `tls_list`

1.7.2. `tls_reload`

1.8.1. `listen`=interface

1.8.2. `tls_method` ([domain]string)

1.8.3. `certificate` ([domain](string)

1.8.4. `private_key` ([domain](string)

1.8.5. `ca_list` ([domain](string)

1.8.6. `ca_dir` ([domain](string)

1.8.7. `ciphers_list` ([domain](string)

1.8.8. `dh_params` ([domain](string)

1.8.9. `ec_curve` ([domain](string)

1.8.10. `verify_cert` ([domain](string) and `require_cert` ([domain](string)

1.8.11. `tls_handshake_timeout` (integer)

1.8.12. `tls_send_timeout` (integer)

1.8.13. `client_domain_avp` (integer)

1.8.14. `db_url` (string)

1.8.15. `db_table` (string)

1.8.16. `domain_col` (string)

1.8.17. `address_col` (string)

1.8.18. `tls_method_col` (string)

1.8.19. `verify_cert_col` (string)

1.8.20. `require_cert_col` (string)

1.8.21. `certificate_col` (string)

1.8.22. `private_key_col` (string)

1.8.23. `crl_check_all_col` (string)

1.8.24. `crl_dir_col` (string)

1.8.25. `ca_list_col` (string)

1.8.26. `ca_dir_col` (string)

1.8.27. `cipher_list_col` (string)

1.8.28. `dh_params_col` (string)

1.8.29. `ec_curve_col` (string)

1.8.30. `server_domain, client_domain` (string)