Skip to end of metadata
Go to start of metadata

Download PDF Document

All Mediatrix Units
DGW 45.3.1971

1 Enable Security Features in DGW

This document describes the steps required to configure a Mediatrix unit loaded with the DGW firmware for secure SIP signalling and secure media (SRTP) operation.

This is not a complete key-exchange, TLS or general security tutorial. For more information on these topics, please see the links section.

In this scenario, the endpoints used are a Mediatrix 41XX and a Mediatrix 4402 BRI Gateway units. Both Mediatrix units must be loaded with DGW. We will use the freely available openSIPS ( ) as the SIP proxy and configure it for TLS operation.


2 TLS-Enabled Server-Proxy Installation with openSIPS

Using two Mediatrix gateways connected back-to-back using a SIP trunk would be sufficient to demonstrate the use of the new security features. However, we prefer to demonstrate the configuration of the units and test scenarios in a more real-world environment by using a separate TLS-enabled SIP proxy. For this purpose, we have chosen openSIPS as it is free and easy to configure for basic use.

For more information on setting up openSIPS, please refer to the openSIPS installation documentation at


If already completed, skip this section.

Please note that at the moment of writing this, openSIPS is configured by default to keep the TLS links up for a period of 2 minutes. We have made a small code modification that allows the links to stay up for 120 minutes. See the annex for more information on how to procede.


3 Certificates

The Mediatrix unit uses digital certificates, which are a collection of data used to verify the identity of individuals, computers, and other entities on a network.

Certificates contain:

  • the certificate's name
  • the issuer and issued to names
  • the validity period (the certificate is not valid before or after this period)
  • the use of certificates such as:
    • TlsClient: The certificate identifies a TLS client. A host authenticated by this kind of certificate can act as a client in a SIP over TLS connection when mutual authentication is required by the server.
    • TlsServer: The certificate identifies a TLS server. A host authenticated by this kind of certificate can serve files or web pages using the HTTPS protocol or can act as a server in a SIP over TLS connection.
  • whether or not the certificate is owned by a Certification Authority (CA)

Although certificates are factory-installed new ones can also be added. Since certificates have a validity period (start date and expiry date), the use of NTP (Network Time Protocol) is mandatory when using the security features.

The Mediatrix unit uses two types of certificates:

  • Host Certificates: used to certify the unit (e.g.: a web server with HTTPS requires a host certificate).
  • Others: Any other certificate including trusted CA certificates used to certify peers (e.g.: a SIP server with TLS).

To enable a TLS connection on Mediatrix units, no CA certificate needs to be installed if the respective parameters for each secure service (e.g. SIP, Conf, Cwmp, etc) has the NoValidation value. If the value is different than NoValidation, then at least one CA certificate needs to be installed. This certificate must be uploaded to the Mediatrix units. The Mediatrix unit then checks the server identity by validating the host name used to contact it against the information found in the server's certificate. If the validation fails, the Mediatrix unit refuses the secure connection. For the SIP over TLS service, we have four (4) levels of validation: HostName, trustedCertificate, DNSSRV, and NoValidation (for a complete description of the validation levels, refer to the Help of the DGW Web interface under SIP/Interop). The way that the remote peer is evaluated for secure connection differs for each level. Remember that the unit must be correctly configured with an SNTP server because the TLS server certificate is also validated in terms of time (certificate validation/expiration date, etc.).

For example in a setup for two Mediatrix gateways with no SIP proxy in the middle. At least one of the units will require a Host certificate. If only one unit has a Host certificate, the calls will be allowed in only one direction (Unit 1 calls Unit 2). For bi-directional calls, both Mediatrix units would require a Host certificate. By default it is not possible to upload a Host certificate without first clicking on Activate unsecure certificate transfer. This is because the certificate upload will be done in clear text, which means the private key will be susceptible to interception.

Certificates are used to secure the following connections:

  • SIP
  • Configuration Web pages
  • File transfers (scripts, firmwares, etc.) with HTTPS
  • Configuration using TR-069
  • Wired Ethernet Authentication with EAP (802.1x)


4 Basics of Security Exchanges

At the level at which we are working, establishing a TLS connection may seems fairly straightforward. However in practice, at a lower level, there are a lot of additional complications to consider to insure a protection against various possible attacks.

Here is an example of an overall exchange in order to build a TLS link and bring it "up"

    • The client (Mediatrix) initially connects to the server on a configured TCP port (16000 is the default source port, the destination port is the configured SIP proxy port ).
    • The client sends a “Client Hello” message with the supported TLS/SSL protocol version, cipher specifications and compression algorithms.
    • The server replies with a “Server Hello” message with the selected cipher and the server certificate.
    • The client verifies the server certificate (validations are configured via the TlsCertificateValidation variable).
    • The client generates a secret and encrypts it with the server’s public key. This encrypted secret is then sent to the server.
    • The client and the server use the secret to create the same symmetric encryption key.
    • The client and the server switch to encrypted communication by using the previously agreed cipher and the key just established
This brief exchange can be seen in the follwing Wireshark capture.

When obtaining the server certificates during the early negotiation, the following information will be checked by the client:

    • the server's signature,
    • the CA (Certification Authority) who signed the certificate,
    • validate that the server identified in the certificate is the same as the one that presented it,
    • the expiration date of the certificate.

If any of these steps fail, the TLS link will not go "up". For those familiar with HTTPS, this is essentially the same procedure but using a SIP server/proxy instead of a HTTPS server.


5 Enabling Security Features


5.1 Importing Certificates on the Mediatrix Unit

Before You Start
You must have an SNTP server for time tracking.
  1. Go to Management /Certificates .
  2. ClickActivate unsecure certificate transfer .
  3. From the Type selection list, select Other .
  4. Click Browse .


    CA certificate files usually have a .crt extension, using format X.509.

  5. Click restart required services .

5.2 Adding the OpenSIPS Gateway

  1. Go to SIP /Gateways .
  2. In the Gateway Configuration table, in the Name field, enter OpenSIPS .
  3. Click .
  4. Complete the fields as follows:
    • From the Type selection list, select Trunk .
    • From the Signaling Network selection list, select Uplink .
    • In the Port field, enter 5062.
    • In the Secure Port port field, enter 5061.
  5. Click Apply .
The OpenSIPS gateway will be available under the SIP > Servers page.

5.3 Assigning a Specific Registrar Server to the OpenSIPS Gateway

  1. Go to SIP /Servers .
  2. In the Registrar Servers table, from the Gateway Specific drop box, select Yes .
  3. In the Registrar Host field, enter the server IP address or FQDN.


    For gateway-specific settings, use the Gateway Specific sections.

  4. Click Submit

5.4 Assigning a Specific Proxy Server to the OpenSIPS Gateway

  1. Go to SIP /Servers .
  2. In the Proxy Servers table, from the Gateway Specific drop box, select Yes .
  3. In the Proxy Host field, enter the server IP address or FQDN.


    For gateway-specific settings, use the Gateway Specific sections.

  4. Click Submit

5.5 Enabling Secure Signaling (TLS)

  1. Go to SIP /Transport tab.
  2. In the Protocol Configuration table, from the TLS dropbox, select Enable .


    The Mediatrix unit does not support a mix of both TLS and non-TLS links. Once TLS is enabled, it is enabled for all configured SIP gateways

  3. Click Apply .
  4. Follow the link located at the top of the Web page to start the appropriate service.
The Ready LED will turn to a steady green. The SipEp Notification messages #303 and #310 are sent once the TLS connection is established. For example:

Syslog message: USER.INFO: SipEp: 1400-SIP Endpoint: 303-TLS connection with remote host is now ready to be used for SIP gateway default.

Syslog message: USER.INFO: SipEp: 1400-SIP Endpoint: 310-Server is now reachable for SIP gateway default.


5.6 Enabling Secure Media (SRTP)

Before You Start
Encrypted/secure signaling must be configured.
  1. Go to Media /Security .
  2. In the Security table, Mode drop box, select Secure .
  3. From the Key Management Protocol drop box, select the protocol.


    Enabling SDES instead of Mickey will make the INVITE slightly different. SDES parameters will be added to the SDP Media Attributes instead of the Session Attributes.

  4. From the Key Management Protocol drop box, select the encryption algorithm.


    The Mediatrix unit supports AES with 128 bits.


    The choice "NULL" will not encrypt the RTP. This option should only be selected for debugging purposes.

  5. Click Apply


    T.38 packerts will never be encrypted. The setting Allow Unsecure T.38 with Secure RTP will make possible to use T.38, otherwise it will be rejected.

The RTP/SAVP states that the endpoint is attempting to initiate a secure media connection.

6 Troubleshooting


6.1 Enabling TLS Debugging on Wireshark

Before You Start
To configure Wireshark for TLS packet capture, the private key associated with the server certificate are needed to decrypt TLS packets.
  1. Go to Edit /Preferences .
  2. Click + next to Protocols .
  3. Select SSL.
  4. Fill the RSA keys list field.


    The field specifies the binding between an IP address, a port, a protocol, and a RSA decryption key. Enter the IP address of the server, the SIP port, and the path to the file containing the server private key. Several such bindings may be specified by separating them with a semi-colon ";".

  5. Start the Wireshark capture.


    TLS sessions using Diffie-Hellman based ciphers (DHE, ECDH, ECDHE) cannot be decrypted by Wireshark.

  6. Restart the SipEp service on the Mediatrix unit or restart the unit.
  7. Once the unit is restarted and the "Ready" LED is lit on the Mediatrix unit, stop the packet capture.
  8. Using the "ssl" filter in the capture should show the SIP packets between the two endpoints.

6.2 REGISTER Messages Not Being Answered

TLS is enabled on one of the Mediatrix gateways and not on the second gateway.

Issue: The REGISTER requests from the second gateway are not being answered.

Reason: The proxy is expecting the SIP message to be SSL encapsulated.

Procedures to solve the issue: Restart the Wireshark capture and enable TLS on the second gateway. Restart the required services.


6.3 Server Internal Error (or Similar Messages)

Some servers/proxies will require Interop variables to be enabled.

For example, the default openSIPS installation requires adding the SIP transport field in the registration and contact headers.


6.3.1 Enabling Interop Variables

  1. Go to SIP /Transport .
  2. In the General Configuration table, set the Add SIP Transport in Registration and Add SIP Transport in Contact Header variables to Enable .
  3. ClickApply .

6.4 Mikey and SDES Mismatch

This document explains why it is highly recommended to choose only one single key management protocol.

In the following example, SDES is configured on endpoint 1 ( and Mikey on endpoint 2 (

The gateway returns a SIP 415 Unsupported Media error because it is not configured to manage SDES.

The following Syslog message should also be seen:

syslog: SdpTools [D3A2] Received the wrong key management protocol. Secure stream disabled.


7 Annexes

Mediatrix Support Portal

8 Online Help

If you are not familiar with the meaning of the fields and buttons, click Show Help , located at the upper right corner of the Web page. When activated, the fields and buttons that offer online help will change to green and if you hover over them, the description will be displayed.


9 DGW Documentation

Mediatrix units are supplied with an exhaustive set of documentation.

Mediatrix user documentation is available on the Media5 Documentation Portal at

Several types of documents were created to clearly present the information you are looking for. Our documentation includes:

  • Release notes : Generated at each GA release, this document includes the known and solved issues of the software. It also outlines the changes and the new features the release includes.
  • Configuration notes : These documents are created to facilitate the configuration of a specific use case. They address a configuration aspect we consider that most users will need to perform. However, in some cases, a configuration note is created after receiving a question from a customer. They provide standard step-by-step procedures detailing the values of the parameters to use. They provide a means of validation and present some conceptual information. The configuration notes are specifically created to guide the user through an aspect of the configuration.
  • Technical bulletins : These documents are created to facilitate the configuration of a specific technical action, such as performing a firmware upgrade.
  • Hardware installation guide : They provide the detailed procedure on how to safely and adequately install the unit. It provides information on card installation, cable connections, and how to access for the first time the Management interface.
  • User guide : The user guide explains how to customise to your needs the configuration of the unit. Although this document is task oriented, it provides conceptual information to help the user understand the purpose and impact of each task. The User Guide will provide information such as where and how TR-069 can be configured in the Management Interface, how to set firewalls, or how to use the CLI to configure parameters that are not available in the Management Interface.
  • Reference guide : This exhaustive document has been created for advanced users. It includes a description of all the parameters used by all the services of the Mediatrix units. You will find, for example, scripts to configure a specific parameter, notification messages sent by a service, or an action description used to create Rulesets. This document includes reference information such as a dictionary, and it does not include any step-by-step procedures.


10 Copyright Notice

Copyright © 2020 Media5 Corporation.

This document contains information that is proprietary to Media5 Corporation.

Media5 Corporation reserves all rights to this document as well as to the Intellectual Property of the document and the technology and know-how that it includes and represents.

This publication cannot be reproduced, neither in whole nor in part, in any form whatsoever, without written prior approval by Media5 Corporation.

Media5 Corporation reserves the right to revise this publication and make changes at any time and without the obligation to notify any person and/or entity of such revisions and/or changes.