Index: srtp/doc/intro.txt |
diff --git a/srtp/doc/intro.txt b/srtp/doc/intro.txt |
deleted file mode 100644 |
index e8607d1c132f8831569cc7244b969c20f3464ee5..0000000000000000000000000000000000000000 |
--- 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 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. |
- |
- |
- */ |