Home | History | Annotate | Download | only in srtp
      1 Secure RTP (SRTP) Reference Implementation
      2 David A. McGrew
      3 Cisco Systems, Inc.
      4 mcgrew (a] cisco.com
      5 
      6 
      7 This package provides an implementation of the Secure Real-time
      8 Transport Protocol (SRTP), the Universal Security Transform (UST), and
      9 a supporting cryptographic kernel.  These mechanisms are documented in
     10 the Internet Drafts in the doc/ subdirectory.  The SRTP API is
     11 documented in include/srtp.h, and the library is in libsrtp.a (after
     12 compilation).  An overview and reference manual is available in
     13 doc/libsrtp.pdf.  The PDF documentation is more up to date than this
     14 file.
     15 
     16 
     17 Installation:
     18 
     19 ./configure [ options ]       # GNU autoconf script 
     20 make                          # or gmake if needed; use GNU make
     21 
     22 The configure script accepts the following options:
     23 
     24    --help              provides a usage summary
     25    --disable-debug     compile without the runtime debugging system
     26    --enable-syslog     use syslog for error reporting
     27    --disable-stdout    use stdout for error reporting
     28    --enable-console    use /dev/console for error reporting
     29    --gdoi              use GDOI key management (disabled at present)
     30 
     31 By default, debbuging is enabled and stdout is used for debugging.
     32 You can use the above configure options to have the debugging output
     33 sent to syslog or the system console.  Alternatively, you can define
     34 ERR_REPORTING_FILE in include/conf.h to be any other file that can be
     35 opened by libSRTP, and debug messages will be sent to it.  
     36 
     37 This package has been tested on Mac OS X (powerpc-apple-darwin1.4),
     38 Cygwin (i686-pc-cygwin), and Sparc (sparc-sun-solaris2.6).  Previous
     39 versions have been tested on Linux and OpenBSD on both x86 and sparc
     40 platforms.
     41 
     42 A quick tour of this package:
     43 
     44 Makefile		targets: all, clean, ...
     45 README			this file
     46 CHANGES                 change log 
     47 VERSION			version number of this package
     48 LICENSE                 legal details (it's a BSD-like license)
     49 crypto/ciphers/		ciphers (null, aes_icm, ...)
     50 crypto/math/		crypto math routines
     51 crypto/hash/            crypto hashing (hmac, tmmhv2, ...)
     52 crypto/replay/		replay protection
     53 doc/			documentation: rfcs, apis, and suchlike
     54 include/		include files for all code in distribution
     55 srtp/			secure real-time transport protocol implementation
     56 tables/                 apps for generating tables (useful in porting)
     57 test/			test drivers 
     58 
     59 
     60 Applications
     61 
     62   Several test drivers and a simple and portable srtp application
     63   are included in the test/ subdirectory.
     64 
     65   test driver	function tested	
     66   -------------------------------------------------------------
     67   kernel_driver crypto kernel (ciphers, auth funcs, rng)
     68   srtp_driver	srtp in-memory tests (does not use the network)
     69   rdbx_driver	rdbx (extended replay database)
     70   roc_driver	extended sequence number functions 
     71   replay_driver	replay database (n.b. not used in libsrtp)
     72   cipher_driver	ciphers 
     73   auth_driver	hash functions 
     74 
     75   The app rtpw is a simple rtp application which reads words from
     76   /usr/dict/words and then sends them out one at a time using [s]rtp.
     77   Manual srtp keying uses the -k option; automated key management
     78   using gdoi will be added later.
     79 
     80 usage: rtpw [-d <debug>]* [-k <key> [-a][-e]] [-s | -r] dest_ip dest_port
     81 or     rtpw -l
     82 
     83   Either the -s (sender) or -r (receiver) option must be chosen.
     84 
     85   The values dest_ip, dest_port are the ip address and udp port to
     86   which the dictionary will be sent, respectively.  
     87 
     88   options:
     89 
     90   -s		(s)rtp sender - causes app to send words
     91 
     92   -r		(s)rtp receive - causes app to receve words
     93 
     94   -k <key>      use srtp master key <key>, where the
     95 		key is a hexadecimal value (without the
     96                 leading "0x")
     97 
     98   -e            encrypt/decrypt (for data confidentiality)
     99                 (requires use of -k option as well)
    100 
    101   -a            message authentication 
    102                 (requires use of -k option as well)
    103 
    104   -l            list debug modules
    105 
    106   -d <debug>    turn on debugging for module <debug>
    107 
    108 
    109 In order to get random 30-byte values for use as key/salt pairs , you
    110 can use the following bash function to format the output of
    111 /dev/random (where that device is available).
    112 
    113 function randhex() {
    114    cat /dev/random | od --read-bytes=32 --width=32 -x | awk '{ print $2 $3 $4 $5 $6 $7 $8 $9 $10 $11 $12 $13 $14 $15 $16 }'
    115 }
    116 
    117 
    118 An example of an SRTP session using two rtpw programs follows:
    119 
    120 set k=c1eec3717da76195bb878578790af71c4ee9f859e197a414a78d5abc7451
    121 
    122 [sh1]$ test/rtpw -s -k $k -ea 0.0.0.0 9999 
    123 Security services: confidentiality message authentication
    124 set master key/salt to C1EEC3717DA76195BB878578790AF71C/4EE9F859E197A414A78D5ABC7451
    125 setting SSRC to 2078917053
    126 sending word: A
    127 sending word: a
    128 sending word: aa
    129 sending word: aal
    130 ...
    131 
    132 [sh2]$ test/rtpw -r -k $k -ea 0.0.0.0 9999 
    133 security services: confidentiality message authentication
    134 set master key/salt to C1EEC3717DA76195BB878578790AF71C/4EE9F859E197A414A78D5ABC7451
    135 19 octets received from SSRC 2078917053 word: A
    136 19 octets received from SSRC 2078917053 word: a
    137 20 octets received from SSRC 2078917053 word: aa
    138 21 octets received from SSRC 2078917053 word: aal
    139 ...
    140 
    141 Implementation Notes
    142 
    143   * The srtp_protect() function assumes that the buffer holding the
    144     rtp packet has enough storage allocated that the authentication 
    145     tag can be written to the end of that packet.  If this assumption
    146     is not valid, memory corruption will ensue.  
    147 
    148   * Automated tests for the crypto functions are provided through
    149     the cipher_type_self_test() and auth_type_self_test() functions.
    150     These functions should be used to test each port of this code 
    151     to a new platform.
    152 
    153   * Replay protection is contained in the crypto engine, and
    154     tests for it are provided.
    155 
    156   * This implementation provides calls to initialize, protect, and
    157     unprotect RTP packets, and makes as few as possible assumptions
    158     about how these functions will be called.  For example, the
    159     caller is not expected to provide packets in order (though if
    160     they're called more than 65k out of sequence, synchronization
    161     will be lost).
    162     
    163   * The sequence number in the rtp packet is used as the low 16 bits
    164     of the sender's local packet index. Note that RTP will start its
    165     sequence number in a random place, and the SRTP layer just jumps
    166     forward to that number at its first invocation.  An earlier
    167     version of this library used initial sequence numbers that are
    168     less than 32,768; this trick is no longer required as the
    169     rdbx_estimate_index(...) function has been made smarter.
    170 
    171   * The replay window is 128 bits in length, and is hard-coded to this
    172     value for now.  
    173 
    174 
    175