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
