Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Overview

Digium D6x 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, Digium phones do not validate Asteriskthe SIP server's server certificate, nor can they be loaded with a client certificate to present to Asterisk.  Future releases of phone firmware may eliminate these limitations.  As  

As of firmware 2_3_9, Digium 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

In 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 the Secure Calling Tutorial wiki  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.

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:

...

When using the DPMA to configure phones, TLS signaling is setup first in two areas: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:

 

No Format
<?xml version="1.0" ?>
<config>
    <setting id="config_server_url" value="sip:proxy@asterisk.example.com:5060" />
</config>

 

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

 

No Format
<?xml version="1.0" ?>
<config>
    <setting id="config_server_url" value="sip:proxy@asterisk.example.com:5061;transport=tls" />
</config>

 

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 porttransport, and media_encryption parameters as such:

 

No Format
<?xml version="1.0" ?>
<config>
    ...
    <accounts>
        <account index="0" status="1" register="1" account_id="101" username="101" authname="101" password="1234" passcode="1234" line_label="Bobby J" caller_id="Bobby J" dial_plan="[0-8]xx">
            <host_primary server="asterisk.example.com" port="5061" transport="tls" media_encryption="sdes" />
        </account>
    </accounts>
</config>

 

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  network option.  It is set such as:

tip
No Format
[tls-network]
type=network
alias=TLS Network
cidr=0.0.0.0/0
registration_address=server.example.com
registration_port=5061
transport=tls
file_url_prefix=http://server.example.com/digium_phones
ntp_server=0.digium.pool.ntp.org
network_vlan_discovery_mode=NONE
sip_dscp=24
rtp_dscp=46
 

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:

...

Media encryption is setup on the phone's line settings  settings using the media_encryption option option, such as:

No Format
[myline]
type=line
media_encryption=sdes
line_label=Fancy Pants
mailbox=101@default

When the phone's line has media_encryption set to sdes, the phone will be configured to perform SDES SRTP encryption.

XML Settings

When using XML to configure a Digium phone, TLS signaling and SDES SRTP are setup in the phone's <host_primary> account child, such as:

Code Block
languagexml
<host_primary server="server.example.com" port="5061" transport="tls" media_encryption="sdes" reregister="300" retry="25" num_retries="5" />

Here, the transport has been set to tls, and media_encryption has been set to sdes.

 

...

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  should provide compatibility.  If  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 Digium phones:

 

Expand
titleDigium Phone TLS Ciphers

RC4-SHA, RC4-MD5

AES128-SHA, AES256-SHA
CAMELLIA128-SHA, CAMELLIA256-SHA
SEED-SHA

 

Versions of firmware prior to 2.3.9 also supported the following, additional ciphers:

Expand
titleDigium Phone older firmware TLS Ciphers

 

DES-CBC-SHA, DES-CBC3-SHA
ECDHE-RSA-RC4-SHA, ECDHE-RSA-DES-CBC3-SHA, ECDHE-RSA-AES128-SHA, ECDHE-RSA-AES256-SHA
AECDH-RC4-SHA, AECDH-DES-CBC3-SHA, AECDH-AES128-SHA, AECDH-AES256-SHA


On the Phone

A Digium 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 0001EISSUER_NOT_FOUNDIssuer cert not found
0x0000 0002EUNTRUSTEDCert untrusted
0x0000 0004EVALIDITY_PERIODCert expired or not yet valid
0x0000 0008EINVALID_FORMATSome cert fields have invalid format
0x0000 0010EINVALID_PURPOSECert can't be used for specified purpose
0x0000 0020EISSUER_MISMATCHIssuer info in cert does not match candidate issuer
0x0000 0040ECRL_FAILURECRL cert could not be found or read
0x0000 0080EREVOKEDCert has been revoked
0x0000 0100ECHAIN_TOO_LONGCert chain length too long
0x4000 0000EIDENTITY_NOT_MATCHServer identity mismatch
0x8000 0000EUNKNOWNUnknown verification error

A typical error response might be something like 0x400000022, which would be EIDENTITY_NOT_MATCH, EISSUER_MISMATCH, EUNTRUSTED