Home | History | Annotate | Download | only in doc
      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