Sangoma Phones and Secure Calling
Overview
Sangoma D-Series phones, beginning with D6x phone firmware 2_2_0_4_5a54ff2 and D80 firmware 1_12_0, support SDES SRTP encrypted media and TLS-encrypted signaling. This page provides a brief overview of the capabilities and the setup procedure.
Limitations
As of firmware 2_2_0_4_5a54ff2, Sangoma phones do not validate the SIP server's certificate, nor can they be loaded with a client certificate to present to Asterisk. Future releases of phone firmware may eliminate these limitations.
As of firmware 2_3_9, Sangoma phones no longer support anonymous or null ciphers.
As of firmwares 2_9_0 and 1_12_0, D-Series phones now validate the SIP Server's certificate by default.
Getting Started - Certificates
n order to setup a TLS transport, Asterisk requires the use of certificates. A good description of the process of generating a self-signed certificate authority, along with the requisite server certificate is available on the Secure Calling Tutorial wiki page.
Best practice, however, is to use a publicly-signed certificate. D-Series phones include a current (as of the time of the firmware build date) copy of the publicly-signed root CA list. Thus, they will be able to properly validate any server using a publicly-signed certificate. If the server does not use a publicly-signed certificate, then a copy of the privately-signed root CA must be loaded onto the phone before it will be able to make a SIP TLS connection to the SIP server.
SIP RFC 5922 section 7.2 forbids the use of wildcard certificates for TLS signaling. For many deployments of servers, this can present a problem. Where these servers are often deployed with wildcard certificates for HTTPs traffic, implementors may assume they can do the same thing for SIP. Per the RFC, one cannot. In order to provide assistance for wildcard implementations, D-Series phone firmwares, beginning with 2_9_2 and 1_12_1 provide a setting, tls_allow_wildcard_certs, disabled by default, that will permit the telephone to accept a wildcard certificate as valid for SIP TLS signaling.
Asterisk TLS Transport
Once certificates have been generated and installed for Asterisk's use, a TLS signaling transport must be set up for use by PJSIP. The transport should look similar to:
[transport-tls]
type=transport
protocol=tls
bind=0.0.0.0:5061
cert_file=/etc/asterisk/keys/asterisk.crt
priv_key_file=/etc/asterisk/keys/asterisk.key
method=sslv23
Here, we've declared a new transport type, that will be using the tls protocol, bound to all local IPv4 addresses (0.0.0.0) on the default port for TLS (5061). We've also provided Asterisk with the asterisk.crt cert_file and the asterisk.key private key file. And, importantly, we've declared that the TLS method we want to use is sslv23. This method actually enables SSL 3.0, TLS 1.0, TLS 1.1 and TLS 1.2 communication methods.
Restart Asterisk, and, from the Asterisk CLI, perform:
pjsip show transports
If you see:
asterisk*CLI> pjsip show transports
Transport: <TransportId........> <Type> <cos> <tos> <BindAddress....................>
==========================================================================================
Transport: transport-tls tls 0 0 0.0.0.0:5061
asterisk*CLI>
The TLS transport has been created successfully.
If it is not seen, then your system may not be compiled with SSL support or you may have introduced a typographic error into the configuration.
Adding, removing or changing PJSIP transports within Asterisk requires a restart. Adding a new transport and performing an Asterisk reload is not effective.
TLS Endpoint Considerations
Endpoints setup in Asterisk to use connection-based protocols such as TCP or TLS should be configured with the contact_rewrite enabled. It is disabled by default. Additionally, endpoints using TCP or TLS cannot have an explicit transport attached to the endpoint. Therefore, and endpoint configured for TLS should include:
Asterisk SDES SRTP Encryption
Media encryption for a PJSIP endpoint in Asterisk is set using the media_encryption option, e.g.:
By default, the media_encryption option is null, disabled. Once it is enabled for an endpoint, it can be made effective by performing a reload from the Asterisk CLI. To check if an endpoint is configured for SDES SRTP media encryption, you can perform pjsip show endpoint <endpoint identifier> from the Asterisk CLI. Look for the media_encryption display line:
Sangoma Phone Settings
DPMA
Use of TCP or TLS signaling with DPMA and Sangoma phones requires Asterisk 13.11.0 or greater.
When using the DPMA to configure phones, TLS signaling is setup first in the mDNS broadcast.
mDNS Broadcast
To setup DPMA's mDNS broadcast to use advertise TLS, a new configuration option has been added for the [general] section, mdns_transport, and can be used such as:
With this set, DPMA will broadcast that a phone should connect to it using TLS signaling on port 5061.
Phone Settings
In order for the phone to retrieve its configuration from DPMA properly, and for the phone to be configured to register to Asterisk using TLS, and for the phone to be configured to encrypt RTP media, the following phone configuration elements and options should be considered:
config_server_url
host_primary port
host_primary transport
host_primary media_encryption
First, as we know from our discussion in Advanced DPMA Configuration, the config_server_url option tells the telephone where to go to retrieve its configuration and communicate with DPMA. Normally, for a UDP-based connection, this option might be configured as such:
In order to specify that we want to communicate with the server using TLS, we need to point to the TLS port that the SIP server presents, e.g. 5061, and append ";transport=tls" to the value, e.g.:
Next, we need to direct the telephone to register and communicate with the server using TLS. We'll also go ahead and tell it to encrypt the media. This is accomplished in the host_primary definition of the account using the port, transport, and media_encryption parameters as such:
Phone Settings for old-style DPMA key-value pairs:
In order for the phone to retrieve its configuration from DPMA singing the older-style DPMA key-value pairs, and for the phone to be configured to register to Asterisk using TLS, the phone's DPMA network must be configured for TLS. This is accomplished with the new transport network option. It is set such as:
A phone can be configured for TLS also by specifying transport=tls on the phone's primary line configuration. The transport option, when defined for a phone's primary line, will override the network section transport settings. Be careful, though, as using one network for UDP and TLS can prove difficult, given that they typically operate on different ports.
When using the DPMA to configure phones, SDES SRTP media encryption is setup in one area:
phone line
Media encryption is setup on the phone's line settings using the media_encryption option, such as:
When the phone's line has media_encryption set to sdes, the phone will be configured to perform SDES SRTP encryption.
Media Crypto Suite
D-Series phones support only AES_CM_128_HMAC_SHA1_80.
D-Series phones do not support AES_CM_128_HMAC_SHA1_32 nor F8_128_HMAC_SHA1_80.
D-Series phones do not perform optimistic SRTP encryption. When SDES SRTP encryption is enabled on the phone, the phone will INVITE using RTP/SAVP. Incoming INVITES not using RTP/SAVP will be rejected.
Signaling Ciphers
Setting PJSIP's TLS method to sslv23 should provide compatibility. D-Series phones support TLS v1.0, TLS v1.1, and TLS v1.2. SSLv2 and SSLv3 are not supported.
If a specific cipher is desired, the following may be used with Sangoma phones:
Digium Phone TLS Ciphers
Versions of firmware prior to 2.3.9 also supported the following, additional ciphers:
Digium Phone older firmware TLS Ciphers
On the Phone
A Sangoma phone indicates to the user when TLS signaling and/or SDES SRTP are enabled for a call with a shield indicator on the line, denoting TLS, and a shield indicator for the call disposition, denoting SRTP, as such:
Troubleshooting
If the phone fails to connect to the server, it may show an error message indicating the specific TLS error. In the event that it does, the following table provides the definitions of the errors:
Error Bitmask | Error | Error Definition |
---|---|---|
0x0000 0001 | EISSUER_NOT_FOUND | Issuer cert not found |
0x0000 0002 | EUNTRUSTED | Cert untrusted |
0x0000 0004 | EVALIDITY_PERIOD | Cert expired or not yet valid |
0x0000 0008 | EINVALID_FORMAT | Some cert fields have invalid format |
0x0000 0010 | EINVALID_PURPOSE | Cert can't be used for specified purpose |
0x0000 0020 | EISSUER_MISMATCH | Issuer info in cert does not match candidate issuer |
0x0000 0040 | ECRL_FAILURE | CRL cert could not be found or read |
0x0000 0080 | EREVOKED | Cert has been revoked |
0x0000 0100 | ECHAIN_TOO_LONG | Cert chain length too long |
0x4000 0000 | EIDENTITY_NOT_MATCH | Server identity mismatch |
0x8000 0000 | EUNKNOWN | Unknown verification error |
A typical error response might be something like 0x400000022, which would be EIDENTITY_NOT_MATCH, EISSUER_MISMATCH, EUNTRUSTED