blob: f3155992550802ba280dbc27fcefa198a1c85622 [file] [log] [blame]
 /** @mainpage Introduction to libSRTP This document describes libSRTP, the Open Source Secure RTP library from Cisco Systems, Inc. RTP is the Real-time Transport Protocol, an IETF standard for the transport of real-time data such as telephony, audio, and video, defined by RFC1889. Secure RTP (SRTP) is an RTP profile for providing confidentiality to RTP data and authentication to the RTP header and payload. SRTP is an IETF Proposed Standard, and is defined in RFC 3711, and was developed in the IETF Audio/Video Transport (AVT) Working Group. This library supports all of the mandatory features of SRTP, but not all of the optional features. See the @ref Features section for more detailed information. This document is organized as follows. The first chapter provides background material on SRTP and overview of libSRTP. The following chapters provide a detailed reference to the libSRTP API and related functions. The reference material is created automatically (using the doxygen utility) from comments embedded in some of the C header files. The documentation is organized into modules in order to improve its clarity. These modules do not directly correspond to files. An underlying cryptographic kernel provides much of the basic functionality of libSRTP, but is mostly undocumented because it does its work behind the scenes. @section LICENSE License and Disclaimer libSRTP is distributed under the following license, which is included in the source code distribution. It is reproduced in the manual in case you got the library from another source. @latexonly \begin{quote} Copyright (c) 2001-2005 Cisco Systems, Inc. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: \begin{itemize} \item Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. \item Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. \item Neither the name of the Cisco Systems, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. \end{itemize} THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. \end{quote} @endlatexonly @section Features Supported Features This library supports all of the mandatory-to-implement features of SRTP (as defined by the most recent Internet Draft). Some of these features can be selected (or de-selected) at run time by setting an appropriate policy; this is done using the structure srtp_policy_t. Some other behaviors of the protocol can be adapted by defining an approriate event handler for the exceptional events; see the @ref SRTPevents section. Some options that are not included in the specification are supported. Most notably, the TMMH authentication function is included, though it was removed from the SRTP Internet Draft during the summer of 2002. @latexonly Some options that are described in the SRTP specification are not supported. This includes \begin{itemize} \item the Master Key Index (MKI), \item key derivation rates other than zero, \item the cipher F8, \item anti-replay lists with sizes other than 128, \item the use of the packet index to select between master keys. \end{itemize} @endlatexonly The user should be aware that it is possible to misuse this libary, and that the result may be that the security level it provides is inadequate. If you are implementing a feature using this library, you will want to read the Security Considerations section of the Internet Draft. In addition, it is important that you read and understand the terms outlined in the @ref LICENSE section. @section Installing Installing and Building libSRTP @latexonly To install libSRTP, download the latest release of the distribution from \texttt{srtp.sourceforge.net}. The format of the names of the distributions are \texttt{srtp-A.B.C.tgz}, where \texttt{A} is the version number, \texttt{B} is the major release number, \texttt{C} is the minor release number, and \texttt{tgz} is the file extension\footnote{The extension \texttt{.tgz} is identical to \texttt{tar.gz}, and indicates a compressed tar file.} You probably want to get the most recent release. Unpack the distribution and extract the source files; the directory into which the soruce files will go is named \texttt{srtp}. libSRTP uses the GNU \texttt{autoconf} and \texttt{make} utilities\footnote{BSD make will not work; if both versions of make are on your platform, you can invoke GNU make as \texttt{gmake}.}. In the \texttt{srtp} directory, run the configure script and then make: \begin{verbatim} ./configure [ options ] make \end{verbatim} The configure script accepts the following options: \begin{quote} \begin{description} \item[--help] provides a usage summary. \item[--disable-debug] compiles libSRTP without the runtime dynamic debugging system. \item[--enable-generic-aesicm] compile in changes for ismacryp \item[--enable-syslog] use syslog for error reporting. \item[--disable-stdout] diables stdout for error reporting. \item[--enable-console] use \texttt{/dev/console} for error reporting \item[--gdoi] use GDOI key management (disabled at present). \end{description} \end{quote} By default, dynamic debbuging is enabled and stdout is used for debugging. You can use the configure options to have the debugging output sent to syslog or the system console. Alternatively, you can define ERR\_REPORTING\_FILE in \texttt{include/conf.h} to be any other file that can be opened by libSRTP, and debug messages will be sent to it. This package has been tested on the following platforms: Mac OS X (powerpc-apple-darwin1.4), Cygwin (i686-pc-cygwin), Solaris (sparc-sun-solaris2.6), RedHat Linux 7.1 and 9 (i686-pc-linux), and OpenBSD (sparc-unknown-openbsd2.7). @endlatexonly @section Applications Applications @latexonly Several test drivers and a simple and portable srtp application are included in the \texttt{test/} subdirectory. \begin{center} \begin{tabular}{ll} \hline Test driver & Function tested \\ \hline kernel\_driver & crypto kernel (ciphers, auth funcs, rng) \\ srtp\_driver & srtp in-memory tests (does not use the network) \\ rdbx\_driver & rdbx (extended replay database) \\ roc\_driver & extended sequence number functions \\ replay\_driver & replay database \\ cipher\_driver & ciphers \\ auth\_driver & hash functions \\ \hline \end{tabular} \end{center} The app rtpw is a simple rtp application which reads words from /usr/dict/words and then sends them out one at a time using [s]rtp. Manual srtp keying uses the -k option; automated key management using gdoi will be added later. The usage for rtpw is \texttt{rtpw [[-d $<$debug$>$]* [-k $<$key$>$ [-a][-e]] [-s | -r] dest\_ip dest\_port][-l]} Either the -s (sender) or -r (receiver) option must be chosen. The values dest\_ip, dest\_port are the IP address and UDP port to which the dictionary will be sent, respectively. The options are: \begin{center} \begin{tabular}{ll} -s & (S)RTP sender - causes app to send words \\ -r & (S)RTP receive - causes app to receve words \\ -k $<$key$>$ & use SRTP master key $<$key$>$, where the key is a hexadecimal value (without the leading "0x") \\ -e & encrypt/decrypt (for data confidentiality) (requires use of -k option as well)\\ -a & message authentication (requires use of -k option as well) \\ -l & list the avaliable debug modules \\ -d $<$debug$>$ & turn on debugging for module $<$debug$>$ \\ \end{tabular} \end{center} In order to get a random 30-byte value for use as a key/salt pair, you can use the \texttt{rand\_gen} utility in the \texttt{test/} subdirectory. An example of an SRTP session using two rtpw programs follows: \begin{verbatim} [sh1] set k=test/rand_gen -n 30 [sh1] echo $k c1eec3717da76195bb878578790af71c4ee9f859e197a414a78d5abc7451 [sh1]$ test/rtpw -s -k $k -ea 0.0.0.0 9999 Security services: confidentiality message authentication set master key/salt to C1EEC3717DA76195BB878578790AF71C/4EE9F859E197A414A78D5ABC7451 setting SSRC to 2078917053 sending word: A sending word: a sending word: aa sending word: aal sending word: aalii sending word: aam sending word: Aani sending word: aardvark ... [sh2] set k=c1eec3717da76195bb878578790af71c4ee9f859e197a414a78d5abc7451 [sh2]$ test/rtpw -r -k \$k -ea 0.0.0.0 9999 security services: confidentiality message authentication set master key/salt to C1EEC3717DA76195BB878578790AF71C/4EE9F859E197A414A78D5ABC7451 19 octets received from SSRC 2078917053 word: A 19 octets received from SSRC 2078917053 word: a 20 octets received from SSRC 2078917053 word: aa 21 octets received from SSRC 2078917053 word: aal ... \end{verbatim} @endlatexonly @section Review Secure RTP Background In this section we review SRTP and introduce some terms that are used in libSRTP. An RTP session is defined by a pair of destination transport addresses, that is, a network address plus a pair of UDP ports for RTP and RTCP. RTCP, the RTP control protocol, is used to coordinate between the participants in an RTP session, e.g. to provide feedback from receivers to senders. An @e SRTP @e session is similarly defined; it is just an RTP session for which the SRTP profile is being used. An SRTP session consists of the traffic sent to the SRTP or SRTCP destination transport addresses. Each participant in a session is identified by a synchronization source (SSRC) identifier. Some participants may not send any SRTP traffic; they are called receivers, even though they send out SRTCP traffic, such as receiver reports. RTP allows multiple sources to send RTP and RTCP traffic during the same session. The synchronization source identifier (SSRC) is used to distinguish these sources. In libSRTP, we call the SRTP and SRTCP traffic from a particular source a @e stream. Each stream has its own SSRC, sequence number, rollover counter, and other data. A particular choice of options, cryptographic mechanisms, and keys is called a @e policy. Each stream within a session can have a distinct policy applied to it. A session policy is a collection of stream policies. A single policy can be used for all of the streams in a given session, though the case in which a single @e key is shared across multiple streams requires care. When key sharing is used, the SSRC values that identify the streams @b must be distinct. This requirement can be enforced by using the convention that each SRTP and SRTCP key is used for encryption by only a single sender. In other words, the key is shared only across streams that originate from a particular device (of course, other SRTP participants will need to use the key for decryption). libSRTP supports this enforcement by detecting the case in which a key is used for both inbound and outbound data. @section Overview libSRTP Overview libSRTP provides functions for protecting RTP and RTCP. RTP packets can be encrypted and authenticated (using the srtp_protect() function), turning them into SRTP packets. Similarly, SRTP packets can be decrypted and have their authentication verified (using the srtp_unprotect() function), turning them into RTP packets. Similar functions apply security to RTCP packets. The typedef srtp_stream_t points to a structure holding all of the state associated with an SRTP stream, including the keys and parameters for cipher and message authentication functions and the anti-replay data. A particular srtp_stream_t holds the information needed to protect a particular RTP and RTCP stream. This datatype is intentionally opaque in order to better seperate the libSRTP API from its implementation. Within an SRTP session, there can be multiple streams, each originating from a particular sender. Each source uses a distinct stream context to protect the RTP and RTCP stream that it is originating. The typedef srtp_t points to a structure holding all of the state associated with an SRTP session. There can be multiple stream contexts associated with a single srtp_t. A stream context cannot exist indepent from an srtp_t, though of course an srtp_t can be created that contains only a single stream context. A device participating in an SRTP session must have a stream context for each source in that session, so that it can process the data that it receives from each sender. In libSRTP, a session is created using the function srtp_create(). The policy to be implemented in the session is passed into this function as an srtp_policy_t structure. A single one of these structures describes the policy of a single stream. These structures can also be linked together to form an entire session policy. A linked list of srtp_policy_t structures is equivalent to a session policy. In such a policy, we refer to a single srtp_policy_t as an @e element. An srtp_policy_t strucutre contains two crypto_policy_t structures that describe the cryptograhic policies for RTP and RTCP, as well as the SRTP master key and the SSRC value. The SSRC describes what to protect (e.g. which stream), and the crypto_policy_t structures describe how to protect it. The key is contained in a policy element because it simplifies the interface to the library. In many cases, it is desirable to use the same cryptographic policies across all of the streams in a session, but to use a distinct key for each stream. A crypto_policy_t structure can be initialized by using either the crypto_policy_set_rtp_default() or crypto_policy_set_rtcp_default() functions, which set a crypto policy structure to the default policies for RTP and RTCP protection, respectively. @section Example Example Code This section provides a simple example of how to use libSRTP. The example code lacks error checking, but is functional. Here we assume that the value ssrc is already set to describe the SSRC of the stream that we are sending, and that the functions get_rtp_packet() and send_srtp_packet() are available to us. The former puts an RTP packet into the buffer and returns the number of octets written to that buffer. The latter sends the RTP packet in the buffer, given the length as its second argument. @verbatim srtp_t session; srtp_policy_t policy; uint8_t key[30]; // initialize libSRTP srtp_init(); // set policy to describe a policy for an SRTP stream crypto_policy_set_rtp_default(&policy.rtp); crypto_policy_set_rtcp_default(&policy.rtcp); policy.ssrc = ssrc; policy.key = key; policy.next = NULL; // set key to random value crypto_get_random(key, 30); // allocate and initialize the SRTP session srtp_create(&session, policy); // main loop: get rtp packets, send srtp packets while (1) { char rtp_buffer[2048]; unsigned len; len = get_rtp_packet(rtp_buffer); srtp_protect(session, rtp_buffer, &len); send_srtp_packet(rtp_buffer, len); } @endverbatim @section ISMAcryp ISMA Encryption Support The Internet Streaming Media Alliance (ISMA) specifies a way to pre-encrypt a media file prior to streaming. This method is an alternative to SRTP encryption, which is potentially useful when a particular media file will be streamed multiple times. The specification is available online at http://www.isma.tv/specreq.nsf/SpecRequest. libSRTP provides the encryption and decryption functions needed for ISMAcryp in the library @t libaesicm.a, which is included in the default Makefile target. This library is used by the MPEG4IP project; see http://mpeg4ip.sourceforge.net/. Note that ISMAcryp does not provide authentication for RTP nor RTCP, nor confidentiality for RTCP. ISMAcryp RECOMMENDS the use of SRTP message authentication for ISMAcryp streams while using ISMAcryp encryption to protect the media itself. */