Add current version of libSRTP from CVS.

libsrtp/doc/intro.txt

+/**
+ 
+@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 RFC 3550.  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,
+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 source 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 debugging 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 receive 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 available 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.
+
+
+ */