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