OLD | NEW |
| (Empty) |
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 RFC 3550. 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, | |
11 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 source 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 debugging 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 receive 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 available 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/4EE9F859E197A414A78D5ABC
7451 | |
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/4EE9F859E197A414A78D5ABC
7451 | |
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 */ | |
OLD | NEW |