diff options
Diffstat (limited to 'third_party/srtp/doc/intro.txt')
| -rw-r--r-- | third_party/srtp/doc/intro.txt | 395 |
1 files changed, 395 insertions, 0 deletions
diff --git a/third_party/srtp/doc/intro.txt b/third_party/srtp/doc/intro.txt new file mode 100644 index 00000000..f3155992 --- /dev/null +++ b/third_party/srtp/doc/intro.txt @@ -0,0 +1,395 @@ +/** + +@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. + + + */ |