README.md 21.4 KB
Newer Older
1 2 3
[![Build Status](https://travis-ci.org/cisco/libsrtp.svg?branch=master)](https://travis-ci.org/cisco/libsrtp)
[![Coverity Scan Build Status](https://scan.coverity.com/projects/14274/badge.svg)](https://scan.coverity.com/projects/cisco-libsrtp)

4 5
<a name="introduction-to-libsrtp"></a>
# Introduction to libSRTP
6

7 8 9 10
This package provides an implementation of the Secure Real-time
Transport Protocol (SRTP), the Universal Security Transform (UST), and
a supporting cryptographic kernel. The SRTP API is documented in include/srtp.h,
and the library is in libsrtp2.a (after compilation).
11

Cullen Jennings's avatar
Cullen Jennings committed
12
This document describes libSRTP, the Open Source Secure RTP library
13
from Cisco Systems, Inc. RTP is the Real-time Transport Protocol, an
Cullen Jennings's avatar
Cullen Jennings committed
14
IETF standard for the transport of real-time data such as telephony,
15 16 17 18 19 20
audio, and video, defined by [RFC 3550](https://www.ietf.org/rfc/rfc3550.txt).
Secure RTP (SRTP) is an RTP profile for providing confidentiality to RTP data
and authentication to the RTP header and payload. SRTP is an IETF Standard,
defined in [RFC 3711](https://www.ietf.org/rfc/rfc3711.txt), and was developed
in the IETF Audio/Video Transport (AVT) Working Group. This library supports
all of the mandatory features of SRTP, but not all of the optional features. See
Geir Istad's avatar
Geir Istad committed
21
the [Supported Features](#supported-features) section for more detailed information.
22

23
This document is also used to generate the documentation files in the /doc/
24 25 26 27 28 29 30
folder where a more detailed reference to the libSRTP API and related functions
can be created (requires installing doxygen.). The reference material is created
automatically from comments embedded in some of the C header files. The
documentation is organized into modules in order to improve its clarity. These
modules do not directly correspond to files. An underlying cryptographic kernel
provides much of the basic functionality of libSRTP but is mostly undocumented
because it does its work behind the scenes.
31

32 33 34 35 36 37 38 39 40 41 42
--------------------------------------------------------------------------------

<a name="contact"></a>
# Contact Us

- [libsrtp@lists.packetizer.com](mailto:libsrtp@lists.packetizer.com) general mailing list for news / announcements / discussions. This is an open list, see
[https://lists.packetizer.com/mailman/listinfo/libsrtp](https://lists.packetizer.com/mailman/listinfo/libsrtp) for singing up.

- [libsrtp-security@lists.packetizer.com](mailto:libsrtp-security@lists.packetizer.com) for disclosing security issues to the libsrtp maintenance team. This is a closed list but anyone can send to it.


43 44
--------------------------------------------------------------------------------

45 46 47 48
<a name="contents"></a>
## Contents

- [Introduction to libSRTP](#introduction-to-libsrtp)
49 50
  - [Contact Us](#contact)
  - [Contents](#contents)
51
- [License and Disclaimer](#license-and-disclaimer)
52
- [libSRTP Overview](#libsrtp-overview)
53
  - [Secure RTP Background](#secure-rtp-background)
54 55
  - [Supported Features](#supported-features)
  - [Implementation Notes](#implementation-notes)
56
- [Installing and Building libSRTP](#installing-and-building-libsrtp)
57
  - [Changing Build Configuration](#changing-build-configuration)
58 59 60 61 62 63 64 65 66
- [Applications](#applications)
  - [Example Code](#example-code)
- [Credits](#credits)
- [References](#references)

--------------------------------------------------------------------------------

<a name="license-and-disclaimer"></a>
# License and Disclaimer
Cullen Jennings's avatar
Cullen Jennings committed
67 68

libSRTP is distributed under the following license, which is included
69
in the source code distribution. It is reproduced in the manual in
Cullen Jennings's avatar
Cullen Jennings committed
70
case you got the library from another source.
71

Geir Istad's avatar
Geir Istad committed
72
> Copyright (c) 2001-2017 Cisco Systems, Inc.  All rights reserved.
73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98
>
> Redistribution and use in source and binary forms, with or without
> modification, are permitted provided that the following conditions
> are met:
>
> - Redistributions of source code must retain the above copyright
>   notice, this list of conditions and the following disclaimer.
> - Redistributions in binary form must reproduce the above copyright
>   notice, this list of conditions and the following disclaimer in
>   the documentation and/or other materials provided with the distribution.
> - Neither the name of the Cisco Systems, Inc. nor the names of its
>   contributors may be used to endorse or promote products derived
>   from this software without specific prior written permission.
>
> THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
> "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
> LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
> FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
> COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
> INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
> (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
> SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
> HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
> STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
> ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
> OF THE POSSIBILITY OF SUCH DAMAGE.
99 100

--------------------------------------------------------------------------------
Cullen Jennings's avatar
Cullen Jennings committed
101

102 103
<a name="libsrtp-overview"></a>
# libSRTP Overview
Cullen Jennings's avatar
Cullen Jennings committed
104

105
libSRTP provides functions for protecting RTP and RTCP.  RTP packets
106
can be encrypted and authenticated (using the `srtp_protect()`
107 108
function), turning them into SRTP packets. Similarly, SRTP packets
can be decrypted and have their authentication verified (using the
109
`srtp_unprotect()` function), turning them into RTP packets. Similar
110
functions apply security to RTCP packets.
Cullen Jennings's avatar
Cullen Jennings committed
111

112 113 114 115 116 117 118
The typedef `srtp_stream_t` points to a structure holding all of the
state associated with an SRTP stream, including the keys and
parameters for cipher and message authentication functions and the
anti-replay data. A particular `srtp_stream_t` holds the information
needed to protect a particular RTP and RTCP stream. This datatype
is intentionally opaque in order to better seperate the libSRTP
API from its implementation.
Cullen Jennings's avatar
Cullen Jennings committed
119

120 121 122 123 124 125 126 127 128 129 130
Within an SRTP session, there can be multiple streams, each
originating from a particular sender. Each source uses a distinct
stream context to protect the RTP and RTCP stream that it is
originating. The typedef `srtp_t` points to a structure holding all of
the state associated with an SRTP session. There can be multiple
stream contexts associated with a single `srtp_t`. A stream context
cannot exist indepent from an `srtp_t`, though of course an `srtp_t` can
be created that contains only a single stream context. A device
participating in an SRTP session must have a stream context for each
source in that session, so that it can process the data that it
receives from each sender.
131

132 133 134 135 136 137
In libSRTP, a session is created using the function `srtp_create()`.
The policy to be implemented in the session is passed into this
function as an `srtp_policy_t` structure. A single one of these
structures describes the policy of a single stream. These structures
can also be linked together to form an entire session policy. A linked
list of `srtp_policy_t` structures is equivalent to a session policy.
138
In such a policy, we refer to a single `srtp_policy_t` as an *element*.
139

140 141 142 143 144 145 146 147 148 149 150 151
An `srtp_policy_t` strucutre contains two `crypto_policy_t` structures
that describe the cryptograhic policies for RTP and RTCP, as well as
the SRTP master key and the SSRC value. The SSRC describes what to
protect (e.g. which stream), and the `crypto_policy_t` structures
describe how to protect it. The key is contained in a policy element
because it simplifies the interface to the library. In many cases, it
is desirable to use the same cryptographic policies across all of the
streams in a session, but to use a distinct key for each stream. A
`crypto_policy_t` structure can be initialized by using either the
`crypto_policy_set_rtp_default()` or `crypto_policy_set_rtcp_default()`
functions, which set a crypto policy structure to the default policies
for RTP and RTCP protection, respectively.
Cullen Jennings's avatar
Cullen Jennings committed
152

153
--------------------------------------------------------------------------------
Cullen Jennings's avatar
Cullen Jennings committed
154

155 156
<a name="secure-rtp-background"></a>
## Secure RTP Background
157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193

In this section we review SRTP and introduce some terms that are used
in libSRTP. An RTP session is defined by a pair of destination
transport addresses, that is, a network address plus a pair of UDP
ports for RTP and RTCP. RTCP, the RTP control protocol, is used to
coordinate between the participants in an RTP session, e.g. to provide
feedback from receivers to senders. An *SRTP session* is
similarly defined; it is just an RTP session for which the SRTP
profile is being used. An SRTP session consists of the traffic sent
to the SRTP or SRTCP destination transport addresses. Each
participant in a session is identified by a synchronization source
(SSRC) identifier. Some participants may not send any SRTP traffic;
they are called receivers, even though they send out SRTCP traffic,
such as receiver reports.

RTP allows multiple sources to send RTP and RTCP traffic during the
same session. The synchronization source identifier (SSRC) is used to
distinguish these sources. In libSRTP, we call the SRTP and SRTCP
traffic from a particular source a *stream*. Each stream has its own
SSRC, sequence number, rollover counter, and other data. A particular
choice of options, cryptographic mechanisms, and keys is called a
*policy*. Each stream within a session can have a distinct policy
applied to it. A session policy is a collection of stream policies.

A single policy can be used for all of the streams in a given session,
though the case in which a single *key* is shared across multiple
streams requires care. When key sharing is used, the SSRC values that
identify the streams **must** be distinct. This requirement can be
enforced by using the convention that each SRTP and SRTCP key is used
for encryption by only a single sender. In other words, the key is
shared only across streams that originate from a particular device (of
course, other SRTP participants will need to use the key for
decryption). libSRTP supports this enforcement by detecting the case
in which a key is used for both inbound and outbound data.

--------------------------------------------------------------------------------

194 195
<a name="supported-features"></a>
## Supported Features
196

197
This library supports all of the mandatory-to-implement features of
198
SRTP (as defined in [RFC 3711](https://www.ietf.org/rfc/rfc3711.txt)). Some of these
199 200 201 202 203
features can be selected (or de-selected) at run time by setting an
appropriate policy; this is done using the structure `srtp_policy_t`.
Some other behaviors of the protocol can be adapted by defining an
approriate event handler for the exceptional events; see the SRTPevents
section in the generated documentation.
204

205 206
Some options that are described in the SRTP specification are not
supported. This includes
207

208 209 210
- key derivation rates other than zero,
- the cipher F8,
- the use of the packet index to select between master keys.
Cullen Jennings's avatar
Cullen Jennings committed
211

212 213 214
The user should be aware that it is possible to misuse this libary,
and that the result may be that the security level it provides is
inadequate. If you are implementing a feature using this library, you
215 216
will want to read the Security Considerations section of [RFC 3711](https://www.ietf.org/rfc/rfc3711.txt).
In addition, it is important that you read and understand the
217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251
terms outlined in the [License and Disclaimer](#license-and-disclaimer) section.

--------------------------------------------------------------------------------

<a name="implementation-notes"></a>
## Implementation Notes

  * The `srtp_protect()` function assumes that the buffer holding the
    rtp packet has enough storage allocated that the authentication
    tag can be written to the end of that packet. If this assumption
    is not valid, memory corruption will ensue.

  * Automated tests for the crypto functions are provided through
    the `cipher_type_self_test()` and `auth_type_self_test()` functions.
    These functions should be used to test each port of this code
    to a new platform.

  * Replay protection is contained in the crypto engine, and
    tests for it are provided.

  * This implementation provides calls to initialize, protect, and
    unprotect RTP packets, and makes as few as possible assumptions
    about how these functions will be called. For example, the
    caller is not expected to provide packets in order (though if
    they're called more than 65k out of sequence, synchronization
    will be lost).

  * The sequence number in the rtp packet is used as the low 16 bits
    of the sender's local packet index. Note that RTP will start its
    sequence number in a random place, and the SRTP layer just jumps
    forward to that number at its first invocation. An earlier
    version of this library used initial sequence numbers that are
    less than 32,768; this trick is no longer required as the
    `rdbx_estimate_index(...)` function has been made smarter.

252
  * The replay window for (S)RTCP is hardcoded to 128 bits in length.
253 254 255

--------------------------------------------------------------------------------

256 257
<a name="installing-and-building-libsrtp"></a>
# Installing and Building libSRTP
258

Cullen Jennings's avatar
Cullen Jennings committed
259
To install libSRTP, download the latest release of the distribution
260 261
from [https://github.com/cisco/libsrtp/releases](https://github.com/cisco/libsrtp/releases).
You probably want to get the most recent release. Unpack the distribution and
262
extract the source files; the directory into which the source files
263 264
will go is named `libsrtp-A-B-C` where `A` is the version number, `B` is the
major release number and `C` is the minor release number.
265

266 267 268
libSRTP uses the GNU `autoconf` and `make` utilities (BSD make will not work; if
both versions of make are on your platform, you can invoke GNU make as
`gmake`.). In the `libsrtp` directory, run the configure script and then
269
make:
270

271 272 273
~~~.txt
./configure [ options ]
make
274 275
~~~

Cullen Jennings's avatar
Cullen Jennings committed
276
The configure script accepts the following options:
277

278 279 280 281 282 283 284 285 286
Option                         | Description
-------------------------------|--------------------
\-\-help                   \-h | Display help
\-\-enable-debug-logging       | Enable debug logging in all modules
\-\-enable-log-stdout          | Enable logging to stdout
\-\-enable-openssl             | Enable OpenSSL crypto engine
\-\-enable-openssl-kdf         | Enable OpenSSL KDF algorithm
\-\-with-log-file              | Use file for logging
\-\-with-openssl-dir           | Location of OpenSSL installation
287

Paul E. Jones's avatar
Paul E. Jones committed
288
By default there is no log output, logging can be enabled to be output to stdout
289
or a given file using the configure options.
Cullen Jennings's avatar
Cullen Jennings committed
290 291 292 293 294 295

This package has been tested on the following platforms: Mac OS X
(powerpc-apple-darwin1.4), Cygwin (i686-pc-cygwin), Solaris
(sparc-sun-solaris2.6), RedHat Linux 7.1 and 9 (i686-pc-linux), and
OpenBSD (sparc-unknown-openbsd2.7).

296
--------------------------------------------------------------------------------
Cullen Jennings's avatar
Cullen Jennings committed
297

298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317
<a name="changing-build-configuration"></a>
## Changing Build Configuration

To build the `./configure` script mentioned above, libSRTP relies on the
[automake](https://www.gnu.org/software/automake/) toolchain.  Since
`./configure` is built from `configure.in` by automake, if you make changes in
how `./configure` works (e.g., to add a new library dependency), you will need
to rebuild `./configure` and commit the updated version.  In addition to
automake itself, you will need to have the `pkgconfig` tools installed as well.

For example, on macOS:

```
brew install automake pkgconfig
# Edit configure.in
autoremake -ivf
```

--------------------------------------------------------------------------------

318 319
<a name="applications"></a>
# Applications
320

Cullen Jennings's avatar
Cullen Jennings committed
321
Several test drivers and a simple and portable srtp application are
322
included in the `test/` subdirectory.
Cullen Jennings's avatar
Cullen Jennings committed
323

324 325 326 327 328 329 330 331 332
Test driver     | Function tested
---------       | -------
kernel_driver   | crypto kernel (ciphers, auth funcs, rng)
srtp_driver	    | srtp in-memory tests (does not use the network)
rdbx_driver	    | rdbx (extended replay database)
roc_driver	    | extended sequence number functions
replay_driver	  | replay database
cipher_driver	  | ciphers
auth_driver	    | hash functions
Cullen Jennings's avatar
Cullen Jennings committed
333

334
The app `rtpw` is a simple rtp application which reads words from
335
`/usr/dict/words` and then sends them out one at a time using [s]rtp.
Cullen Jennings's avatar
Cullen Jennings committed
336 337 338
Manual srtp keying uses the -k option; automated key management
using gdoi will be added later.

339
usage:
340
~~~.txt
341
rtpw [[-d <debug>]* [-k|b <key> [-a][-e <key size>][-g]] [-s | -r] dest_ip dest_port] | [-l]
342
~~~
Cullen Jennings's avatar
Cullen Jennings committed
343 344

Either the -s (sender) or -r (receiver) option must be chosen.  The
345
values `dest_ip`, `dest_port` are the IP address and UDP port to which
346 347 348 349 350 351 352 353 354 355 356 357 358 359 360
the dictionary will be sent, respectively.

The options are:

Option         | Description
---------      | -------
  -s           | (S)RTP sender - causes app to send words
  -r           | (S)RTP receive - causes app to receive words
  -k <key>     | use SRTP master key <key>, where the key is a hexadecimal (without the leading "0x")
  -b <key>     | same as -k but with base64 encoded key
  -e <keysize> | encrypt/decrypt (for data confidentiality) (requires use of -k option as well) (use 128, 192, or 256 for keysize)
  -g           | use AES-GCM mode (must be used with -e)
  -a           | message authentication (requires use of -k option as well)
  -l           | list the available debug modules
  -d <debug>   | turn on debugging for module <debug>
361 362 363

In order to get random 30-byte values for use as key/salt pairs , you
can use the following bash function to format the output of
364
`/dev/random` (where that device is available).
365

366
~~~.txt
367 368 369
function randhex() {
   cat /dev/random | od --read-bytes=32 --width=32 -x | awk '{ print $2 $3 $4 $5 $6 $7 $8 $9 $10 $11 $12 $13 $14 $15 $16 }'
}
370
~~~
371 372 373

An example of an SRTP session using two rtpw programs follows:

374
~~~.txt
375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394
set k=c1eec3717da76195bb878578790af71c4ee9f859e197a414a78d5abc7451

[sh1]$ test/rtpw -s -k $k -e 128 -a 0.0.0.0 9999
Security services: confidentiality message authentication
set master key/salt to C1EEC3717DA76195BB878578790AF71C/4EE9F859E197A414A78D5ABC7451
setting SSRC to 2078917053
sending word: A
sending word: a
sending word: aa
sending word: aal
...

[sh2]$ test/rtpw -r -k $k -e 128 -a 0.0.0.0 9999
security services: confidentiality message authentication
set master key/salt to C1EEC3717DA76195BB878578790AF71C/4EE9F859E197A414A78D5ABC7451
19 octets received from SSRC 2078917053 word: A
19 octets received from SSRC 2078917053 word: a
20 octets received from SSRC 2078917053 word: aa
21 octets received from SSRC 2078917053 word: aal
...
395
~~~
396 397 398

--------------------------------------------------------------------------------

399 400
<a name="example-code"></a>
## Example Code
Cullen Jennings's avatar
Cullen Jennings committed
401

402 403
This section provides a simple example of how to use libSRTP. The
example code lacks error checking, but is functional. Here we assume
Cullen Jennings's avatar
Cullen Jennings committed
404
that the value ssrc is already set to describe the SSRC of the stream
405 406
that we are sending, and that the functions `get_rtp_packet()` and
`send_srtp_packet()` are available to us. The former puts an RTP packet
Cullen Jennings's avatar
Cullen Jennings committed
407
into the buffer and returns the number of octets written to that
408
buffer. The latter sends the RTP packet in the buffer, given the
Cullen Jennings's avatar
Cullen Jennings committed
409 410
length as its second argument.

411
~~~.c
412 413
srtp_t session;
srtp_policy_t policy;
414 415 416 417 418 419

// Set key to predetermined value
uint8_t key[30] = {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
                   0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F,
                   0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
                   0x18, 0x19, 0x1A, 0x1B, 0x1C, 0x1D};
420 421 422 423

// initialize libSRTP
srtp_init();

escrichov's avatar
escrichov committed
424 425 426
// default policy values
memset(&policy, 0x0, sizeof(srtp_policy_t));

427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445
// set policy to describe a policy for an SRTP stream
crypto_policy_set_rtp_default(&policy.rtp);
crypto_policy_set_rtcp_default(&policy.rtcp);
policy.ssrc = ssrc;
policy.key  = key;
policy.next = NULL;

// allocate and initialize the SRTP session
srtp_create(&session, &policy);

// main loop: get rtp packets, send srtp packets
while (1) {
  char rtp_buffer[2048];
  unsigned len;

  len = get_rtp_packet(rtp_buffer);
  srtp_protect(session, rtp_buffer, &len);
  send_srtp_packet(rtp_buffer, len);
}
446
~~~
Cullen Jennings's avatar
Cullen Jennings committed
447

448 449
--------------------------------------------------------------------------------

450 451
<a name="credits"></a>
# Credits
452 453 454 455 456 457 458 459

The original implementation and documentation of libSRTP was written
by David McGrew of Cisco Systems, Inc. in order to promote the use,
understanding, and interoperability of Secure RTP. Michael Jerris
contributed support for building under MSVC. Andris Pavenis
contributed many important fixes. Brian West contributed changes to
enable dynamic linking. Yves Shumann reported documentation bugs.
Randell Jesup contributed a working SRTCP implementation and other
460
fixes. Steve Underwood contributed x86_64 portability changes. We also give
461 462 463 464 465 466 467 468
thanks to Fredrik Thulin, Brian Weis, Mark Baugher, Jeff Chan, Bill
Simon, Douglas Smith, Bill May, Richard Preistley, Joe Tardo and
others for contributions, comments, and corrections.

This reference material, when applicable, in this documenation was generated
using the doxygen utility for automatic documentation of source code.

Copyright 2001-2005 by David A. McGrew, Cisco Systems, Inc.
469 470 471

--------------------------------------------------------------------------------

472 473
<a name="references"></a>
# References
474 475 476 477 478 479 480

SRTP and ICM References
September, 2005

Secure RTP is defined in [RFC 3711](https://www.ietf.org/rfc/rfc3711.txt).
The counter mode definition is in Section 4.1.1.

481
SHA-1 is defined in [FIPS PUB 180-4](http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf).
482

483
HMAC is defined in [RFC 2104](https://www.ietf.org/rfc/rfc2104.txt)
484
and HMAC-SHA1 test vectors are available
485 486 487
in [RFC 2202](https://www.ietf.org/rfc/rfc2202.txt).

AES-GCM usage in SRTP is defined in [RFC 7714](https://www.ietf.org/html/rfc7714)