1.4.1. Dependencies of external libraries

OpenSIPS TLS support requires the following packages:

• openssl or libssl >= 0.9.6

• openssl-dev or libssl-dev

1.5.1. Creating CA root certificate

This part must be done only once, disregarding the number of how many interconnected OpenSIPS's we want to have.

Using "opensipsctl tls rootCA", you may create a local root CA.

The script will produce the private key (which will be used to sign client/server certificates) and the self-signed certificate authority.

1.5.2. Creating a server/client certificate

This part must be done for each OpenSIPS server interconnected into your TLS enabled network: build a certificate request and sign it with a root CA (yourself or from third party).

For this purpose you may use the "opensipsctl tls userCERT"

The output of the script will be a directory containing all needed TLS files for configuring the OpenSIPS proxy (private key, signed certificate and CA list)

1.5.3. Setting OpenSIPS to use the certificate

Append to the CA list file all the CA root certificates ( this list must contain all CA root certificates to be accepted by your server):

If you use the "opensipsctl tls userCERT", it will create an one element CA list with the CA used to sign the certificate.

To add more CAs to your list, just do:

• cat add_cacert.pem >> calist.pem

Now copy intended OpenSIPS certificate, private key and ca list file (basically the whole content of the opensipsX directory) to your intended machine in some directory (which will be further refer by path "path").

There are some OpenSIPS TLS specific parameter that must be set up in OpenSIPS configuration file to use the certificate:

• set up opensips.cfg to use the certificate :

  tls_certificate=/path/cert.pem

• set up opensips to use the private key :

  tls_private_key=/path/privkey.pem

• set up opensips to use the CA list (optional - make sens only if tls_verify is turned on)

  tls_ca_list=/path/calist.pem

1.5.4. TLS OpenSIPS authentication behavior

The "tls_verify_server", "tls_verify_client" and "tls_require_client_certificate" are OpenSIPS-names for the OpenSSL defined flags:

• SSL_VERIFY_PEER is tls_verify_client/tls_verify_server

• SSL_VERIFY_FAIL_IF_NO_PEER_CERT is tls_require_client_certificate (tls_require_client_certificate is only used if tls_verify_client=1)

If your OpenSIPS is acting as a server (incoming TLS connections), it will always send its server-side certificate to the client. If tls_verify_client is disabled (set to 0), your OpenSIPS will not request the client a client-certificate. This means that the client is not authenticated. If tls_verify_client=1, your OpenSIPS (the server) sends a client-certificate request to the client. But the client is free to not provide any. In this case, tls_require_client_certificate comes into play:

• tls_require_client_certificate=0 - the verification process will succeed if the client does not provide a certificate, or if it provides one, it verifies correctly against the server's list of trusted certification authorities.

• tls_require_client_certificate=1 - the verification process will only succeed if the client provides a certificate and this verifies correctly against the server's list of trusted CAs.

If your OpenSIPS is acting as a client (outgoing TLS connections), it will always receive a certificate from the peer. If tls_verify_server is disabled (set to 0), your OpenSIPS will not verifiy the certificate and allows TLS connections to servers which do not present a valid certificate. If tls_verify_server=1, your OpenSIPS (the client) verifies the server certificate and will close the TLS connection if the server certificate is not valid.

For more details see page man verify(1).

1.6.1. disable_tls=integer

Disables TLS (no server is created on the listen addresses, no outgoing connections can be set up). A non 0 value means disable.

It's usable only if TLS support was compiled.

Default value is 1 (TLS disabled).

...
disable_tls = 1
...
				

1.6.2. 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.

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

1.6.3. tls_port_no=number

Sets the default TLS listening port.

It's usable only if TLS support was compiled.

Default value is 5061.

...
tls_port_no = 5062
...
				

1.6.4. tls_method=value

Sets the TLS protocol method which can be:

• 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.

It's usable only if TLS support was compiled.

Default value is SSLv23.

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).

...
tls_method = TLSv1
...
				

1.6.5. tls_certificate=file

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.

See previous chapter Section 1.5.3 for more information.

It's usable only if TLS support was compiled.

Default value is "CFG_DIR/cert.pem".

...
tls_certificate="/mycerts/certs/opensips_server_cert.pem"
...
				

1.6.6. tls_private_key=file

Private key of the above certificate. I must be kept in a safe place with tight permissions!

See previous chapter Section 1.5.3 for more information.

It's usable only if TLS support was compiled.

Default value is "CFG_DIR/cert.pem".

...
tls_private_key="/mycerts/private/prik.pem"
...
				

1.6.7. tls_ca_list=file

List of trusted CAs. The file contains the certificates accepted, one after the other. It MUST be a file, not a folder.

See previous chapter Section 1.5.3 for more information.

It's usable only if TLS support was compiled.

Default value is "".

...
tls_ca_list="/mycerts/certs/ca_list.pem"
...
				

1.6.8. tls_ciphers_list=string

You can specify the list of algorithms for authentication and encryption that you allow. To obtain a list of ciphers and then choose, use the openssl application:

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

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

It's usable only if TLS support was compiled.

It defaults to the OpenSSL default ciphers.

...
tls_ciphers_list="NULL"
...
				

1.6.9. tls_verify_client=number and tls_require_client_certificate=number

Technically, tls_verify_client activates SSL_VERIFY_PEER in the ssl_context. tls_require_client_certificate does the same with SSL_VERIFY_FAIL_IF_NO_PEER_CERT, which is only possible if SSL_VERIFY_PEER is also turned on.

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

See previous chapter Section 1.5.4 for more information.

It's usable only if TLS support was compiled.

Default value for both is 1.

...
# turn on the strictest and strongest authentication possible
tls_verify_client = 1
tls_require_client_certificate = 1
...
				

1.6.10. tls_verify_server=number

Technically, tls_verify_server activates SSL_VERIFY_PEER in the ssl_context.

This parameter is used for outgoing TLS connections, where OpenSIPS acts as client.

See previous chapter Section 1.5.4 for more information.

It's usable only if TLS support was compiled.

Default value is 1.

...
# turn on the strictest and strongest authentication possible
tls_verify_server = 1
...
				

1.6.11. tls_handshake_timeout=number and tls_send_timeout=number

Timeouts ... advanced users only

It's usable only if TLS support was compiled.

Default value for both is 30.

...
tls_handshake_timeout=119    # number of seconds
tls_send_timeout=121         # number of seconds
...
				

1.6.12. tls_client_domain_avp=number

This sets the interger AVP used for name based TLS server domains (please see tls_client_domain for more details). Setting the value to 0 disables name based TLS client domains.

It's usable only if TLS support was compiled.

Default value is 0.

...
tls_client_domain_avp=400    # only integer named AVPs are supported
...
				

1.6.13. tls_server_domain, tls_client_domain section

If you only run one domain, the main one 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).

The wording 'TLS domain' means that this TLS connection will have different parameters than another TLS connection (from another TLS domain). Thus, TLS domains must 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).

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 received a 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 possible as there is no dedicated outgoing socket. Thus, the certificate selection (selection of the proper TLS client domain) will be name based. For this purpose, TLS client domains can be associated with a name (e.g. the domain can be used as name). If the SIP proxy establishes a new outgoing TLS connection, it checks for the TLS client domain AVP (parameter tls_client_domain_avp). If this AVP is set (e.g. in OpenSIPS.cfg), OpenSIPS searches for a TLS client domain with the same name and uses the certificates defined in the respective tls_client_domain section.

TLS client domains can also be socket based. If name based domains are disabled or no name based AVP is found, OpenSIPS searches for socket based TLS client domains. In this case the mapping between to the TLS client domain is done based on the destination socket of the underlying outgoing TCP connection.

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.

NOTE: The tls_verify_client and tls_require_client_certificate options can only be configured in TLS server domains, whereas the tls_verify_server option is only valid for configuring TLS client domains.

It's usable only if TLS support was compiled.

...
listen=tls:IP_2:port2
listen=tls:IP_3:port4
...
# set the TLS client domain AVP
tls_client_domain_avp = 400
...
# socket based TLS server domains (for virtual SIPS hosting)
tls_server_domain[IP_2:port2] {
    #specify parameters for a domain in particular, otherwise, 
    #it will use the default values. 
    tls_certificate = "/certs/atlanta.com/cert.pem"
    tls_private_key = "/certs/atlanta.com/privkey.pem"
    tls_ca_list     = "/certs/wellknownCAs"
    tls_method=tlsv1
}
tls_server_domain[IP_3:port3] {
    tls_certificate = "/certs/biloxy.com/cert.pem"
    tls_private_key = "/certs/biloxy.com/privkey.pem"
    tls_ca_list     = "/certs/wellknownCAs"
    tls_method=tlsv1
    tls_verify_client = 1
    tls_require_client_certificate = 1
}
# name based TLS client domains (for virtual SIPS hosting)
tls_client_domain["atlanta.com"] {
    tls_certificate = "/certs/atlanta.com/cert.pem"
    tls_private_key = "/certs/atlanta.com/privkey.pem"
    tls_ca_list     = "/certs/wellknownCAs"
    tls_method=tlsv1
    tls_verify_server = 1
}
tls_client_domain["biloxi.com"] {
    tls_certificate = "/certs/biloxy.com/cert.pem"
    tls_private_key = "/certs/biloxy.com/privkey.pem"
    tls_ca_list     = "/certs/wellknownCAs"
    tls_method=tlsv1
    tls_verify_server = 0
}
# socket based TLS server domains (for TLS based downstream from GW provider)
tls_server_domain[IP_5:port5] {
    tls_certificate = "/certs/local/cert.pem"
    tls_private_key = "/certs/local/privkey.pem"
    tls_ca_list     = "/certs/GWproviderSelfSignedCA"
    tls_method=tlsv1
    # TLS needed only for encryption, access is restricted via
    # IP access lists
    tls_verify_client = 0
}
# socket based TLS client domains (for TLS based upstream to GW provider)
# GW IP: 1.2.3.4, GW port: 6677
tls_client_domain[1.2.3.4:6677] {
    tls_certificate = "/certs/local/cert.pem"
    tls_private_key = "/certs/local/privkey.pem"
    tls_ca_list     = "/certs/GWproviderSelfSignedCA"
    tls_method=tlsv1
    # TLS needed only for encryption, access is restricted via
    # IP access lists
    tls_verify_server = 0
}
...
route{
...
    # calls to other SIP domains
    # set the proper SSL context (certificate) for local hosted domains
    avp_write("$fd","$avp(i:400)");
    t_relay(); # uses NAPTR and SRV lookups
    exit;
...
    # calls to the PSTN GW
    t_relay("tls:1.2.3.4:6677");
    exit;
...
				

2.2.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.2.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.2.3. init_tls

int init_tls(void);

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

2.2.4. destroy_tls

void destroy_tls(void);

Called once, just before cleanup.

2.2.5. tls_init

int tls_init(struct socket_info *c);

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

2.2.6. ser_malloc, ser_realloc, ser_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.3.1. SSL data per connection

Each TLS connection, incoming or outgoing, creates an SSL * object, where configuration inherited from the SSL_CTX * and particular info on that socket are stored. This SSL * structure is kept in OpenSIPS as long as the connection is alive, as part of the "struct tcp_connection *" object:

...
struct tcp_connection *c;
SSL *ssl;

/*create somehow SSL object*/
c->extra_data = (void *) ssl; 
ssl = (SSL *) c->extra_data;
...

2.3.2. tls_print_errstack

void tls_print_errstack(void);

Dumps ssl error stack.

2.3.3. tls_tcpconn_init

int tls_tcpconn_init( struct tcp_connection *c, int fd);

Called when new tcp connection is accepted

2.3.4. tls_tcpconn_clean

void tls_tcpconn_clean( struct tcp_connection *c);

Shuts down the TLS connection.

2.3.5. tls_blocking_write

size_t tls_blocking_write( struct tcp_connection *c, int fd, const char *buf, size_t len);

Writes a memory chunk in blocking mode (syncron).

2.3.6. tls_read

size_t tls_read( struct tcp_connection *c);

Reads from a TLS connection. Return the number of bytes read.

2.3.7. tls_fix_read_conn

void tls_tcpconn_clean( struct tcp_connection *c);

Shuts down the TLS connection.

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 with given ip and port (socket of the remote destination).

2.4.4. tls_find_client_domain_name

struct tls_domain *tls_find_client_name(str name);

Find TLS client domain with given name.

2.4.5. tls_new__domain

struct tls_domain *tls_new_domain(int type);

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

2.4.6. 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.7. 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.8. 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.9. tls_free_domains

void tls_free_domains(void);

Cleans up the entire domain lists.