forked from Mirrors/freeswitch
396 lines
17 KiB
Plaintext
396 lines
17 KiB
Plaintext
/**
|
|
|
|
@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.
|
|
|
|
|
|
*/
|