intro.txt

mediastreamer2是开源的网络传输媒体流的库

/**
 
@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