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, 8 audio, and video, defined by RFC1889. Secure RTP (SRTP) is an RTP 9 profile for providing confidentiality to RTP data and authentication 10 to the RTP header and payload. SRTP is an IETF Proposed Standard, and 11 is defined in RFC 3711, and was developed in the IETF Audio/Video 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 113 extract the source files; the directory into which the soruce files 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 138 By default, dynamic debbuging is enabled and stdout is used for 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 184 dest\_port][-l]} 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 \\ 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 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; 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 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 394 395 */ 396
