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