intro.txt

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

                (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.


 */