1Secure RTP (SRTP) Reference Implementation
2David A. McGrew
3Cisco Systems, Inc.
4mcgrew@cisco.com
5
6
7This package provides an implementation of the Secure Real-time
8Transport Protocol (SRTP), the Universal Security Transform (UST), and
9a supporting cryptographic kernel.  These mechanisms are documented in
10the Internet Drafts in the doc/ subdirectory.  The SRTP API is
11documented in include/srtp.h, and the library is in libsrtp.a (after
12compilation).  An overview and reference manual is available in
13doc/libsrtp.pdf.  The PDF documentation is more up to date than this
14file.
15
16
17Installation:
18
19./configure [ options ]       # GNU autoconf script 
20make                          # or gmake if needed; use GNU make
21
22The 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
31By default, debbuging is enabled and stdout is used for debugging.
32You can use the above configure options to have the debugging output
33sent to syslog or the system console.  Alternatively, you can define
34ERR_REPORTING_FILE in include/conf.h to be any other file that can be
35opened by libSRTP, and debug messages will be sent to it.  
36
37This package has been tested on Mac OS X (powerpc-apple-darwin1.4),
38Cygwin (i686-pc-cygwin), and Sparc (sparc-sun-solaris2.6).  Previous
39versions have been tested on Linux and OpenBSD on both x86 and sparc
40platforms.
41
42A quick tour of this package:
43
44Makefile		targets: all, clean, ...
45README			this file
46CHANGES                 change log 
47VERSION			version number of this package
48LICENSE                 legal details (it's a BSD-like license)
49crypto/ciphers/		ciphers (null, aes_icm, ...)
50crypto/math/		crypto math routines
51crypto/hash/            crypto hashing (hmac, tmmhv2, ...)
52crypto/replay/		replay protection
53doc/			documentation: rfcs, apis, and suchlike
54include/		include files for all code in distribution
55srtp/			secure real-time transport protocol implementation
56tables/                 apps for generating tables (useful in porting)
57test/			test drivers 
58
59
60Applications
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
80usage: rtpw [-d <debug>]* [-k <key> [-a][-e]] [-s | -r] dest_ip dest_port
81or     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
109In order to get random 30-byte values for use as key/salt pairs , you
110can use the following bash function to format the output of
111/dev/random (where that device is available).
112
113function 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
118An example of an SRTP session using two rtpw programs follows:
119
120set k=c1eec3717da76195bb878578790af71c4ee9f859e197a414a78d5abc7451
121
122[sh1]$ test/rtpw -s -k $k -ea 0.0.0.0 9999 
123Security services: confidentiality message authentication
124set master key/salt to C1EEC3717DA76195BB878578790AF71C/4EE9F859E197A414A78D5ABC7451
125setting SSRC to 2078917053
126sending word: A
127sending word: a
128sending word: aa
129sending word: aal
130...
131
132[sh2]$ test/rtpw -r -k $k -ea 0.0.0.0 9999 
133security services: confidentiality message authentication
134set master key/salt to C1EEC3717DA76195BB878578790AF71C/4EE9F859E197A414A78D5ABC7451
13519 octets received from SSRC 2078917053 word: A
13619 octets received from SSRC 2078917053 word: a
13720 octets received from SSRC 2078917053 word: aa
13821 octets received from SSRC 2078917053 word: aal
139...
140
141Implementation 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