Version 7 (modified by bennylp, 17 years ago) (diff)


SRTP Support in PJSIP

This article describes about SRTP support in PJSIP , which was included in version 0.9 (see ticket #61).

Table of Contents:

  1. Compatibility Info
    1. Build Systems
    2. API Changes
  2. Requirements
  3. Building PJSIP with SRTP Support
    1. Availability
    2. Building
  4. Using SRTP
    1. Using SRTP in PJSUA-LIB
    2. pjsua
    3. Using SRTP Transport Directly
  5. Implementation Notes
    1. Changes in Media Transport Interface
    2. pjmedia_transport_srtp Implementation

Compatibility Info

Please note the following issues regarding compatibility with previous PJSIP code:

Build Systems

There is a new third party library in the distribution, namely libsrtp, you will need to add this library into your application's input libraries specification.

For GNU build systems:

  1. You will need to re-run ./configure, make dep and make to update build.mak and rebuild the project dependencies.
  2. If your Makefile includes build.mak (as explained in Getting Stared part 2, you just need to rebuild your application as the input libraries will be updated automatically.
  3. If you maintain your own independent Makefile, please add libsrtp-$(TARGET) from third_party/lib directory to your input libraries.

For Visual Studio 6 and 2005:

  1. New libsrtp project has been added into PJSIP workspace.
  2. If you maintain your own application workspace, you need to add libsrtp project into your application. The libsrtp project files are in third_party/build/srtp directory.

For Windows Mobile developments:

  1. New libsrtp project has been added into PJSIP workspace.
  2. If you maintain your own application workspace, you need to add libsrtp project into your application. The libsrtp project files are in third_party/build/srtp directory.
  3. Make sure you import the Embedded Visual Studio project (libsrtp.vcp) rather than the Visual Studio (libsrtp.vcproj) project!


  1. To be done.

API Changes

New callbacks have been added in media transport interface which may break your application, depending on the API level that you use. The changes will be explained in Changes in Media Transport Interface section below.

If you are working directly with PJMEDIA transport API, there may be changes required in your code.

If you are working on PJSUA-LIB API level, there should be no changes in your application.


SRTP feature in PJSIP uses the Open Source libsrtp library created by David A. McGrew of Cisco Systems, Inc. Copy of libsrtp is included in PJSIP source tree in third_party/srtp directory. There is no other software to download.

libsrtp is distributed under BSD-like license, you must satisfy the license requirements if you incorporate SRTP in your application. Please see PJSIP licensing page for more information about this and other third party libraries licensing in PJSIP.

Building PJSIP with SRTP Support


SRTP feature is currently available in:

  • Visual C++ 6 and 2005 (for Windows targets)
  • GNU based build system (for Linux, Mingw, MacOS X, and *nix based platforms)
  • Windows Mobile targets

Support for Symbian will be added soon.


libsrtp is always built by default, from third_party/build/srtp directory.

Support for SRTP is enabled by default in PJMEDIA and PJSUA-LIB. To disable this feature, declare this in your config_site.h:


Using SRTP

SRTP is implemented as media transport in PJMEDIA. In the high level PJSUA-LIB API, the use of SRTP is controlled by couple of settings as explained below.


In PJSUA-LIB, the use of SRTP is controlled by settings in both pjsua_config and pjsua_acc_config. The settings in pjsua_config specifies the default settings for all accounts, and the settings in pjsua_acc_config can be used to further set the behavior for that specific account.

In both pjsua_config and pjsua_acc_config, there are two configuration items to control:

This option controls whether secure media transport (SRTP) should be used for this account. Valid values are:
  • PJMEDIA_SRTP_DISABLED (0): SRTP is disabled, and incoming call with RTP/SAVP transport will be rejected.
  • PJMEDIA_SRTP_OPTIONAL (1): SRTP will be advertised and SRTP will be used if remote supports it, but the call may fall back to unsecure media.
  • PJMEDIA_SRTP_MANDATORY (2): secure media is mandatory, and the call can only proceed if secure media can be established.
The default value for this option is PJSUA_DEFAULT_USE_SRTP, which is zero (disabled).
This option controls whether SRTP requires secure signaling to be used. This option is only used when use_srtp option above is non-zero. Valid values are:
  • 0: SRTP does not require secure signaling
  • 1: SRTP requires secure transport such as TLS
  • 2: SRTP requires secure end-to-end transport (SIPS)
The default value for this option is PJSUA_DEFAULT_SRTP_SECURE_SIGNALING, which is 1 (require TLS transport).


New option ---use-srtp is added, with valid values are 0, 1, or 2. This corresponds to use_srtp setting above.

Sample usage:

 $ ./pjsua --use-tls --use-srtp=1

Note: we need to enable TLS since by default SRTP requires secure signaling to be used (see srtp_secure_signaling setting above). If you want to use SRTP with non-secure transport (which is not recommended unless for testing purpose only!), you can modify srtp_secure_signaling setting in pjsua application.

Using SRTP Transport Directly

The SRTP transport may also be used directly without having to involve SDP negotiations. However, you will need to have a different mechanism to exchange keys between endpoints.

To use SRTP transport directly:

  • Call pjmedia_transport_srtp_create() to create the SRTP adapter, giving it the actual media transport instance (such as UDP transport).
  • Call pjmedia_transport_srtp_start() to active SRTP session, giving it both local and remote crypto settings and keys.
  • Call pjmedia_transport_attach() to configure the remote RTP/RTCP addresses and attach your RTP and RTCP callbacks.
  • Call pjmedia_transport_send_rtp() and pjmedia_transport_send_rtcp() to send RTP/RTCP packets.
  • Once you done with your session, call pjmedia_transport_close() to destroy the SRTP adapter (and optionally the actual transport which is attached to the SRTP adapter, depending on whether close_member_tp flag is set in the options when creating the SRTP adapter).

Implementation Notes

Changes in Media Transport Interface

Since the availability of SRTP changes contents of SDP (Session Description Protocol) and the SDP negotiation, we need to add new interfaces in PJMEDIA transport API to allow media transport to modify and negotiate SDP. Incidently this would work well with ICE too (previously we treat ICE as a special kind of media transport so it is treated differently, but with this new interfaces, all media transports will behave uniformly (anyway that's what API abstraction is for!)).

New interfaces in media transport are as follows (please consult the PJMEDIA transport documentation for more info):

This callback is called by application (or PJSUA-LIB) to allow the media transport to add more information in the SDP offer, before the offer is sent to remote. Additionally, for answerer side, this callback allows the media transport to reject the offer from the remote before this offer is processed by the SDP negotiator.
This callback is called after offer and answer are negotiated, and before the media is started. For answerer side, this callback will be called before the answer is sent to remote, to allow media transport to put additional info in the SDP. The media transport also has the final chance to negotiate the offer and answer before media is really started.
This callback is called when the media is stopped, to allow the media transport to release its resources.
This has nothing to do with SRTP, but since all media transports support this feature (packet loss simulation), we add this as a new interface.

pjmedia_transport_srtp Implementation

As we know, media transport is separated from the stream object (which does the encoding/decoding of PCM frames, (de)packetization of RTP/RTCP packets, and de-jitter buffering). The connection between stream and media transport is established when the stream is created (we need to specify media transport during stream creation), and the interconnection can be depicted from the diagram below:

I think the diagram above is self-explanatory.

With SRTP, the SRTP is implemented as some kind of "adapter", which is plugged between the stream and the actual media transport that does sending/receiving RTP/RTCP packets. When SRTP is used, the interconnection between stream and transport is like the diagram below:

So to stream, the SRTP transport behaves as if it is a media transport (because it is a media transport), and to the media transport it behaves as if it is a stream. The SRTP object will forward RTP packets back and forth from stream to the actual transport and vice versa, encrypting/decrypting the RTP/RTCP packets as necessary.

The neat thing about this design is the SRTP "adapter" then can be used to encrypt any kind of media transports. We currently have UDP and ICE media transports that can benefit SRTP, and we could add SRTP to any media transports that will be added in the future.

Attachments (2)

Download all attachments as: .zip