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