Cullen Jennings | 235513a | 2005-09-21 22:51:36 +0000 | [diff] [blame] | 1 | /** |
| 2 | |
| 3 | @mainpage Introduction to libSRTP |
| 4 | |
| 5 | This document describes libSRTP, the Open Source Secure RTP library |
| 6 | from Cisco Systems, Inc. RTP is the Real-time Transport Protocol, an |
| 7 | IETF standard for the transport of real-time data such as telephony, |
Jonathan Lennox | d942596 | 2010-06-01 18:26:12 +0000 | [diff] [blame] | 8 | audio, and video, defined by RFC 3550. Secure RTP (SRTP) is an RTP |
Cullen Jennings | 235513a | 2005-09-21 22:51:36 +0000 | [diff] [blame] | 9 | profile for providing confidentiality to RTP data and authentication |
Jonathan Lennox | d942596 | 2010-06-01 18:26:12 +0000 | [diff] [blame] | 10 | to the RTP header and payload. SRTP is an IETF Proposed Standard, |
| 11 | defined in RFC 3711, and was developed in the IETF Audio/Video |
Cullen Jennings | 235513a | 2005-09-21 22:51:36 +0000 | [diff] [blame] | 12 | Transport (AVT) Working Group. This library supports all of the |
| 13 | mandatory features of SRTP, but not all of the optional features. See |
| 14 | the @ref Features section for more detailed information. |
| 15 | |
| 16 | This document is organized as follows. The first chapter provides |
| 17 | background material on SRTP and overview of libSRTP. The following |
| 18 | chapters provide a detailed reference to the libSRTP API and related |
| 19 | functions. The reference material is created automatically (using the |
| 20 | doxygen utility) from comments embedded in some of the C header |
| 21 | files. The documentation is organized into modules in order to improve |
| 22 | its clarity. These modules do not directly correspond to files. An |
| 23 | underlying cryptographic kernel provides much of the basic |
| 24 | functionality of libSRTP, but is mostly undocumented because it does |
| 25 | its work behind the scenes. |
| 26 | |
| 27 | @section LICENSE License and Disclaimer |
| 28 | |
| 29 | libSRTP is distributed under the following license, which is included |
| 30 | in the source code distribution. It is reproduced in the manual in |
| 31 | case you got the library from another source. |
| 32 | |
| 33 | @latexonly |
| 34 | \begin{quote} |
| 35 | Copyright (c) 2001-2005 Cisco Systems, Inc. All rights reserved. |
| 36 | |
| 37 | Redistribution and use in source and binary forms, with or without |
| 38 | modification, are permitted provided that the following conditions |
| 39 | are met: |
| 40 | \begin{itemize} |
| 41 | \item Redistributions of source code must retain the above copyright |
| 42 | notice, this list of conditions and the following disclaimer. |
| 43 | \item Redistributions in binary form must reproduce the above |
| 44 | copyright notice, this list of conditions and the following |
| 45 | disclaimer in the documentation and/or other materials provided |
| 46 | with the distribution. |
| 47 | \item Neither the name of the Cisco Systems, Inc. nor the names of its |
| 48 | contributors may be used to endorse or promote products derived |
| 49 | from this software without specific prior written permission. |
| 50 | \end{itemize} |
| 51 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
| 52 | "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
| 53 | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS |
| 54 | FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE |
| 55 | COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, |
| 56 | INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES |
| 57 | (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR |
| 58 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| 59 | HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, |
| 60 | STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
| 61 | ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED |
| 62 | OF THE POSSIBILITY OF SUCH DAMAGE. |
| 63 | \end{quote} |
| 64 | @endlatexonly |
| 65 | |
| 66 | @section Features Supported Features |
| 67 | |
| 68 | This library supports all of the mandatory-to-implement features of |
| 69 | SRTP (as defined by the most recent Internet Draft). Some of these |
| 70 | features can be selected (or de-selected) at run time by setting an |
| 71 | appropriate policy; this is done using the structure srtp_policy_t. |
| 72 | Some other behaviors of the protocol can be adapted by defining an |
| 73 | approriate event handler for the exceptional events; see the @ref |
| 74 | SRTPevents section. |
| 75 | |
| 76 | Some options that are not included in the specification are supported. |
| 77 | Most notably, the TMMH authentication function is included, though it |
| 78 | was removed from the SRTP Internet Draft during the summer of 2002. |
| 79 | |
| 80 | |
| 81 | @latexonly |
| 82 | Some options that are described in the SRTP specification are not |
| 83 | supported. This includes |
| 84 | \begin{itemize} |
| 85 | \item the Master Key Index (MKI), |
| 86 | \item key derivation rates other than zero, |
| 87 | \item the cipher F8, |
| 88 | \item anti-replay lists with sizes other than 128, |
| 89 | \item the use of the packet index to select between master keys. |
| 90 | \end{itemize} |
| 91 | @endlatexonly |
| 92 | |
| 93 | The user should be aware that it is possible to misuse this libary, |
| 94 | and that the result may be that the security level it provides is |
| 95 | inadequate. If you are implementing a feature using this library, you |
| 96 | will want to read the Security Considerations section of the Internet |
| 97 | Draft. In addition, it is important that you read and understand the |
| 98 | terms outlined in the @ref LICENSE section. |
| 99 | |
| 100 | |
| 101 | @section Installing Installing and Building libSRTP |
| 102 | |
| 103 | @latexonly |
| 104 | |
| 105 | To install libSRTP, download the latest release of the distribution |
| 106 | from \texttt{srtp.sourceforge.net}. The format of the names of the |
| 107 | distributions are \texttt{srtp-A.B.C.tgz}, where \texttt{A} is the |
| 108 | version number, \texttt{B} is the major release number, \texttt{C} is |
| 109 | the minor release number, and \texttt{tgz} is the file |
| 110 | extension\footnote{The extension \texttt{.tgz} is identical to |
| 111 | \texttt{tar.gz}, and indicates a compressed tar file.} You probably |
| 112 | want to get the most recent release. Unpack the distribution and |
Jonathan Lennox | d942596 | 2010-06-01 18:26:12 +0000 | [diff] [blame] | 113 | extract the source files; the directory into which the source files |
Cullen Jennings | 235513a | 2005-09-21 22:51:36 +0000 | [diff] [blame] | 114 | will go is named \texttt{srtp}. |
| 115 | |
| 116 | libSRTP uses the GNU \texttt{autoconf} and \texttt{make} |
| 117 | utilities\footnote{BSD make will not work; if both versions of make |
| 118 | are on your platform, you can invoke GNU make as \texttt{gmake}.}. In |
| 119 | the \texttt{srtp} directory, run the configure script and then make: |
| 120 | \begin{verbatim} |
| 121 | ./configure [ options ] |
| 122 | make |
| 123 | \end{verbatim} |
| 124 | The configure script accepts the following options: |
| 125 | \begin{quote} |
| 126 | \begin{description} |
| 127 | \item[--help] provides a usage summary. |
| 128 | \item[--disable-debug] compiles libSRTP without the runtime |
| 129 | dynamic debugging system. |
| 130 | \item[--enable-generic-aesicm] compile in changes for ismacryp |
| 131 | \item[--enable-syslog] use syslog for error reporting. |
| 132 | \item[--disable-stdout] diables stdout for error reporting. |
| 133 | \item[--enable-console] use \texttt{/dev/console} for error reporting |
| 134 | \item[--gdoi] use GDOI key management (disabled at present). |
| 135 | \end{description} |
| 136 | \end{quote} |
| 137 | |
Jonathan Lennox | d942596 | 2010-06-01 18:26:12 +0000 | [diff] [blame] | 138 | By default, dynamic debugging is enabled and stdout is used for |
Cullen Jennings | 235513a | 2005-09-21 22:51:36 +0000 | [diff] [blame] | 139 | debugging. You can use the configure options to have the debugging |
| 140 | output sent to syslog or the system console. Alternatively, you can |
| 141 | define ERR\_REPORTING\_FILE in \texttt{include/conf.h} to be any other |
| 142 | file that can be opened by libSRTP, and debug messages will be sent to |
| 143 | it. |
| 144 | |
| 145 | This package has been tested on the following platforms: Mac OS X |
| 146 | (powerpc-apple-darwin1.4), Cygwin (i686-pc-cygwin), Solaris |
| 147 | (sparc-sun-solaris2.6), RedHat Linux 7.1 and 9 (i686-pc-linux), and |
| 148 | OpenBSD (sparc-unknown-openbsd2.7). |
| 149 | |
| 150 | |
| 151 | @endlatexonly |
| 152 | |
| 153 | @section Applications Applications |
| 154 | |
| 155 | @latexonly |
| 156 | |
| 157 | Several test drivers and a simple and portable srtp application are |
| 158 | included in the \texttt{test/} subdirectory. |
| 159 | |
| 160 | \begin{center} |
| 161 | \begin{tabular}{ll} |
| 162 | \hline |
| 163 | Test driver & Function tested \\ |
| 164 | \hline |
| 165 | kernel\_driver & crypto kernel (ciphers, auth funcs, rng) \\ |
| 166 | srtp\_driver & srtp in-memory tests (does not use the network) \\ |
| 167 | rdbx\_driver & rdbx (extended replay database) \\ |
| 168 | roc\_driver & extended sequence number functions \\ |
| 169 | replay\_driver & replay database \\ |
| 170 | cipher\_driver & ciphers \\ |
| 171 | auth\_driver & hash functions \\ |
| 172 | \hline |
| 173 | \end{tabular} |
| 174 | \end{center} |
| 175 | |
| 176 | The app rtpw is a simple rtp application which reads words from |
| 177 | /usr/dict/words and then sends them out one at a time using [s]rtp. |
| 178 | Manual srtp keying uses the -k option; automated key management |
| 179 | using gdoi will be added later. |
| 180 | |
| 181 | The usage for rtpw is |
| 182 | |
| 183 | \texttt{rtpw [[-d $<$debug$>$]* [-k $<$key$>$ [-a][-e]] [-s | -r] dest\_ip |
Jonathan Lennox | d942596 | 2010-06-01 18:26:12 +0000 | [diff] [blame] | 184 | dest\_port] | [-l]} |
Cullen Jennings | 235513a | 2005-09-21 22:51:36 +0000 | [diff] [blame] | 185 | |
| 186 | Either the -s (sender) or -r (receiver) option must be chosen. The |
| 187 | values dest\_ip, dest\_port are the IP address and UDP port to which |
| 188 | the dictionary will be sent, respectively. The options are: |
| 189 | \begin{center} |
| 190 | \begin{tabular}{ll} |
| 191 | -s & (S)RTP sender - causes app to send words \\ |
Jonathan Lennox | d942596 | 2010-06-01 18:26:12 +0000 | [diff] [blame] | 192 | -r & (S)RTP receive - causes app to receive words \\ |
Cullen Jennings | 235513a | 2005-09-21 22:51:36 +0000 | [diff] [blame] | 193 | -k $<$key$>$ & use SRTP master key $<$key$>$, where the |
| 194 | key is a hexadecimal value (without the |
| 195 | leading "0x") \\ |
| 196 | -e & encrypt/decrypt (for data confidentiality) |
| 197 | (requires use of -k option as well)\\ |
| 198 | -a & message authentication |
| 199 | (requires use of -k option as well) \\ |
Jonathan Lennox | d942596 | 2010-06-01 18:26:12 +0000 | [diff] [blame] | 200 | -l & list the available debug modules \\ |
Cullen Jennings | 235513a | 2005-09-21 22:51:36 +0000 | [diff] [blame] | 201 | -d $<$debug$>$ & turn on debugging for module $<$debug$>$ \\ |
| 202 | \end{tabular} |
| 203 | \end{center} |
| 204 | |
| 205 | In order to get a random 30-byte value for use as a key/salt pair, you |
| 206 | can use the \texttt{rand\_gen} utility in the \texttt{test/} |
| 207 | subdirectory. |
| 208 | |
| 209 | An example of an SRTP session using two rtpw programs follows: |
| 210 | |
| 211 | \begin{verbatim} |
| 212 | [sh1] set k=`test/rand_gen -n 30` |
| 213 | [sh1] echo $k |
| 214 | c1eec3717da76195bb878578790af71c4ee9f859e197a414a78d5abc7451 |
| 215 | [sh1]$ test/rtpw -s -k $k -ea 0.0.0.0 9999 |
| 216 | Security services: confidentiality message authentication |
| 217 | set master key/salt to C1EEC3717DA76195BB878578790AF71C/4EE9F859E197A414A78D5ABC7451 |
| 218 | setting SSRC to 2078917053 |
| 219 | sending word: A |
| 220 | sending word: a |
| 221 | sending word: aa |
| 222 | sending word: aal |
| 223 | sending word: aalii |
| 224 | sending word: aam |
| 225 | sending word: Aani |
| 226 | sending word: aardvark |
| 227 | ... |
| 228 | |
| 229 | [sh2] set k=c1eec3717da76195bb878578790af71c4ee9f859e197a414a78d5abc7451 |
| 230 | [sh2]$ test/rtpw -r -k $k -ea 0.0.0.0 9999 |
| 231 | security services: confidentiality message authentication |
| 232 | set master key/salt to C1EEC3717DA76195BB878578790AF71C/4EE9F859E197A414A78D5ABC7451 |
| 233 | 19 octets received from SSRC 2078917053 word: A |
| 234 | 19 octets received from SSRC 2078917053 word: a |
| 235 | 20 octets received from SSRC 2078917053 word: aa |
| 236 | 21 octets received from SSRC 2078917053 word: aal |
| 237 | ... |
| 238 | \end{verbatim} |
| 239 | |
| 240 | |
| 241 | @endlatexonly |
| 242 | |
| 243 | |
| 244 | @section Review Secure RTP Background |
| 245 | |
| 246 | In this section we review SRTP and introduce some terms that are used |
| 247 | in libSRTP. An RTP session is defined by a pair of destination |
| 248 | transport addresses, that is, a network address plus a pair of UDP |
| 249 | ports for RTP and RTCP. RTCP, the RTP control protocol, is used to |
| 250 | coordinate between the participants in an RTP session, e.g. to provide |
| 251 | feedback from receivers to senders. An @e SRTP @e session is |
| 252 | similarly defined; it is just an RTP session for which the SRTP |
| 253 | profile is being used. An SRTP session consists of the traffic sent |
| 254 | to the SRTP or SRTCP destination transport addresses. Each |
| 255 | participant in a session is identified by a synchronization source |
| 256 | (SSRC) identifier. Some participants may not send any SRTP traffic; |
| 257 | they are called receivers, even though they send out SRTCP traffic, |
| 258 | such as receiver reports. |
| 259 | |
| 260 | RTP allows multiple sources to send RTP and RTCP traffic during the |
| 261 | same session. The synchronization source identifier (SSRC) is used to |
| 262 | distinguish these sources. In libSRTP, we call the SRTP and SRTCP |
| 263 | traffic from a particular source a @e stream. Each stream has its own |
| 264 | SSRC, sequence number, rollover counter, and other data. A particular |
| 265 | choice of options, cryptographic mechanisms, and keys is called a @e |
| 266 | policy. Each stream within a session can have a distinct policy |
| 267 | applied to it. A session policy is a collection of stream policies. |
| 268 | |
| 269 | A single policy can be used for all of the streams in a given session, |
| 270 | though the case in which a single @e key is shared across multiple |
| 271 | streams requires care. When key sharing is used, the SSRC values that |
| 272 | identify the streams @b must be distinct. This requirement can be |
| 273 | enforced by using the convention that each SRTP and SRTCP key is used |
| 274 | for encryption by only a single sender. In other words, the key is |
| 275 | shared only across streams that originate from a particular device (of |
| 276 | course, other SRTP participants will need to use the key for |
| 277 | decryption). libSRTP supports this enforcement by detecting the case |
| 278 | in which a key is used for both inbound and outbound data. |
| 279 | |
| 280 | |
| 281 | @section Overview libSRTP Overview |
| 282 | |
| 283 | libSRTP provides functions for protecting RTP and RTCP. RTP packets |
| 284 | can be encrypted and authenticated (using the srtp_protect() |
| 285 | function), turning them into SRTP packets. Similarly, SRTP packets |
| 286 | can be decrypted and have their authentication verified (using the |
| 287 | srtp_unprotect() function), turning them into RTP packets. Similar |
| 288 | functions apply security to RTCP packets. |
| 289 | |
| 290 | The typedef srtp_stream_t points to a structure holding all of the |
| 291 | state associated with an SRTP stream, including the keys and |
| 292 | parameters for cipher and message authentication functions and the |
| 293 | anti-replay data. A particular srtp_stream_t holds the information |
| 294 | needed to protect a particular RTP and RTCP stream. This datatype |
| 295 | is intentionally opaque in order to better seperate the libSRTP |
| 296 | API from its implementation. |
| 297 | |
| 298 | Within an SRTP session, there can be multiple streams, each |
| 299 | originating from a particular sender. Each source uses a distinct |
| 300 | stream context to protect the RTP and RTCP stream that it is |
| 301 | originating. The typedef srtp_t points to a structure holding all of |
| 302 | the state associated with an SRTP session. There can be multiple |
| 303 | stream contexts associated with a single srtp_t. A stream context |
| 304 | cannot exist indepent from an srtp_t, though of course an srtp_t can |
| 305 | be created that contains only a single stream context. A device |
| 306 | participating in an SRTP session must have a stream context for each |
| 307 | source in that session, so that it can process the data that it |
| 308 | receives from each sender. |
| 309 | |
| 310 | |
| 311 | In libSRTP, a session is created using the function srtp_create(). |
| 312 | The policy to be implemented in the session is passed into this |
| 313 | function as an srtp_policy_t structure. A single one of these |
| 314 | structures describes the policy of a single stream. These structures |
| 315 | can also be linked together to form an entire session policy. A linked |
| 316 | list of srtp_policy_t structures is equivalent to a session policy. |
| 317 | In such a policy, we refer to a single srtp_policy_t as an @e element. |
| 318 | |
| 319 | An srtp_policy_t strucutre contains two crypto_policy_t structures |
| 320 | that describe the cryptograhic policies for RTP and RTCP, as well as |
| 321 | the SRTP master key and the SSRC value. The SSRC describes what to |
| 322 | protect (e.g. which stream), and the crypto_policy_t structures |
| 323 | describe how to protect it. The key is contained in a policy element |
| 324 | because it simplifies the interface to the library. In many cases, it |
| 325 | is desirable to use the same cryptographic policies across all of the |
| 326 | streams in a session, but to use a distinct key for each stream. A |
| 327 | crypto_policy_t structure can be initialized by using either the |
| 328 | crypto_policy_set_rtp_default() or crypto_policy_set_rtcp_default() |
| 329 | functions, which set a crypto policy structure to the default policies |
| 330 | for RTP and RTCP protection, respectively. |
| 331 | |
| 332 | @section Example Example Code |
| 333 | |
| 334 | This section provides a simple example of how to use libSRTP. The |
| 335 | example code lacks error checking, but is functional. Here we assume |
| 336 | that the value ssrc is already set to describe the SSRC of the stream |
| 337 | that we are sending, and that the functions get_rtp_packet() and |
| 338 | send_srtp_packet() are available to us. The former puts an RTP packet |
| 339 | into the buffer and returns the number of octets written to that |
| 340 | buffer. The latter sends the RTP packet in the buffer, given the |
| 341 | length as its second argument. |
| 342 | |
| 343 | @verbatim |
| 344 | srtp_t session; |
| 345 | srtp_policy_t policy; |
Marcus Sundberg | 410faaa | 2005-09-29 12:36:43 +0000 | [diff] [blame] | 346 | uint8_t key[30]; |
Cullen Jennings | 235513a | 2005-09-21 22:51:36 +0000 | [diff] [blame] | 347 | |
David McGrew | f712337 | 2005-09-30 17:30:26 +0000 | [diff] [blame] | 348 | // initialize libSRTP |
Cullen Jennings | 235513a | 2005-09-21 22:51:36 +0000 | [diff] [blame] | 349 | srtp_init(); |
| 350 | |
David McGrew | f712337 | 2005-09-30 17:30:26 +0000 | [diff] [blame] | 351 | // set policy to describe a policy for an SRTP stream |
Cullen Jennings | 235513a | 2005-09-21 22:51:36 +0000 | [diff] [blame] | 352 | crypto_policy_set_rtp_default(&policy.rtp); |
| 353 | crypto_policy_set_rtcp_default(&policy.rtcp); |
| 354 | policy.ssrc = ssrc; |
| 355 | policy.key = key; |
| 356 | policy.next = NULL; |
| 357 | |
David McGrew | f712337 | 2005-09-30 17:30:26 +0000 | [diff] [blame] | 358 | // set key to random value |
Cullen Jennings | 235513a | 2005-09-21 22:51:36 +0000 | [diff] [blame] | 359 | crypto_get_random(key, 30); |
| 360 | |
David McGrew | f712337 | 2005-09-30 17:30:26 +0000 | [diff] [blame] | 361 | // allocate and initialize the SRTP session |
Jonathan Lennox | d942596 | 2010-06-01 18:26:12 +0000 | [diff] [blame] | 362 | srtp_create(&session, &policy); |
Cullen Jennings | 235513a | 2005-09-21 22:51:36 +0000 | [diff] [blame] | 363 | |
David McGrew | f712337 | 2005-09-30 17:30:26 +0000 | [diff] [blame] | 364 | // main loop: get rtp packets, send srtp packets |
Cullen Jennings | 235513a | 2005-09-21 22:51:36 +0000 | [diff] [blame] | 365 | while (1) { |
| 366 | char rtp_buffer[2048]; |
| 367 | unsigned len; |
| 368 | |
| 369 | len = get_rtp_packet(rtp_buffer); |
| 370 | srtp_protect(session, rtp_buffer, &len); |
| 371 | send_srtp_packet(rtp_buffer, len); |
| 372 | } |
| 373 | @endverbatim |
| 374 | |
David McGrew | fec49dd | 2005-09-23 19:34:11 +0000 | [diff] [blame] | 375 | @section ISMAcryp ISMA Encryption Support |
| 376 | |
| 377 | The Internet Streaming Media Alliance (ISMA) specifies a way |
| 378 | to pre-encrypt a media file prior to streaming. This method |
| 379 | is an alternative to SRTP encryption, which is potentially |
| 380 | useful when a particular media file will be streamed |
| 381 | multiple times. The specification is available online |
| 382 | at http://www.isma.tv/specreq.nsf/SpecRequest. |
| 383 | |
| 384 | libSRTP provides the encryption and decryption functions needed for ISMAcryp |
| 385 | in the library @t libaesicm.a, which is included in the default |
| 386 | Makefile target. This library is used by the MPEG4IP project; see |
| 387 | http://mpeg4ip.sourceforge.net/. |
| 388 | |
| 389 | Note that ISMAcryp does not provide authentication for |
| 390 | RTP nor RTCP, nor confidentiality for RTCP. |
| 391 | ISMAcryp RECOMMENDS the use of SRTP message authentication for ISMAcryp |
| 392 | streams while using ISMAcryp encryption to protect the media itself. |
| 393 | |
Cullen Jennings | 235513a | 2005-09-21 22:51:36 +0000 | [diff] [blame] | 394 | |
| 395 | */ |