michael@0: Secure RTP (SRTP) Reference Implementation michael@0: David A. McGrew michael@0: Cisco Systems, Inc. michael@0: mcgrew@cisco.com michael@0: michael@0: michael@0: This package provides an implementation of the Secure Real-time michael@0: Transport Protocol (SRTP), the Universal Security Transform (UST), and michael@0: a supporting cryptographic kernel. These mechanisms are documented in michael@0: the Internet Drafts in the doc/ subdirectory. The SRTP API is michael@0: documented in include/srtp.h, and the library is in libsrtp.a (after michael@0: compilation). An overview and reference manual is available in michael@0: doc/libsrtp.pdf. The PDF documentation is more up to date than this michael@0: file. michael@0: michael@0: michael@0: Installation: michael@0: michael@0: ./configure [ options ] # GNU autoconf script michael@0: make # or gmake if needed; use GNU make michael@0: michael@0: The configure script accepts the following options: michael@0: michael@0: --help provides a usage summary michael@0: --disable-debug compile without the runtime debugging system michael@0: --enable-syslog use syslog for error reporting michael@0: --disable-stdout use stdout for error reporting michael@0: --enable-console use /dev/console for error reporting michael@0: --gdoi use GDOI key management (disabled at present) michael@0: michael@0: By default, debbuging is enabled and stdout is used for debugging. michael@0: You can use the above configure options to have the debugging output michael@0: sent to syslog or the system console. Alternatively, you can define michael@0: ERR_REPORTING_FILE in include/conf.h to be any other file that can be michael@0: opened by libSRTP, and debug messages will be sent to it. michael@0: michael@0: This package has been tested on Mac OS X (powerpc-apple-darwin1.4), michael@0: Cygwin (i686-pc-cygwin), and Sparc (sparc-sun-solaris2.6). Previous michael@0: versions have been tested on Linux and OpenBSD on both x86 and sparc michael@0: platforms. michael@0: michael@0: A quick tour of this package: michael@0: michael@0: Makefile targets: all, clean, ... michael@0: README this file michael@0: CHANGES change log michael@0: VERSION version number of this package michael@0: LICENSE legal details (it's a BSD-like license) michael@0: crypto/ciphers/ ciphers (null, aes_icm, ...) michael@0: crypto/math/ crypto math routines michael@0: crypto/hash/ crypto hashing (hmac, tmmhv2, ...) michael@0: crypto/replay/ replay protection michael@0: doc/ documentation: rfcs, apis, and suchlike michael@0: include/ include files for all code in distribution michael@0: srtp/ secure real-time transport protocol implementation michael@0: tables/ apps for generating tables (useful in porting) michael@0: test/ test drivers michael@0: michael@0: michael@0: Applications michael@0: michael@0: Several test drivers and a simple and portable srtp application michael@0: are included in the test/ subdirectory. michael@0: michael@0: test driver function tested michael@0: ------------------------------------------------------------- michael@0: kernel_driver crypto kernel (ciphers, auth funcs, rng) michael@0: srtp_driver srtp in-memory tests (does not use the network) michael@0: rdbx_driver rdbx (extended replay database) michael@0: roc_driver extended sequence number functions michael@0: replay_driver replay database (n.b. not used in libsrtp) michael@0: cipher_driver ciphers michael@0: auth_driver hash functions michael@0: michael@0: The app rtpw is a simple rtp application which reads words from michael@0: /usr/dict/words and then sends them out one at a time using [s]rtp. michael@0: Manual srtp keying uses the -k option; automated key management michael@0: using gdoi will be added later. michael@0: michael@0: usage: rtpw [-d ]* [-k [-a][-e]] [-s | -r] dest_ip dest_port michael@0: or rtpw -l michael@0: michael@0: Either the -s (sender) or -r (receiver) option must be chosen. michael@0: michael@0: The values dest_ip, dest_port are the ip address and udp port to michael@0: which the dictionary will be sent, respectively. michael@0: michael@0: options: michael@0: michael@0: -s (s)rtp sender - causes app to send words michael@0: michael@0: -r (s)rtp receive - causes app to receve words michael@0: michael@0: -k use srtp master key , where the michael@0: key is a hexadecimal value (without the michael@0: leading "0x") michael@0: michael@0: -e encrypt/decrypt (for data confidentiality) michael@0: (requires use of -k option as well) michael@0: michael@0: -a message authentication michael@0: (requires use of -k option as well) michael@0: michael@0: -l list debug modules michael@0: michael@0: -d turn on debugging for module michael@0: michael@0: michael@0: In order to get random 30-byte values for use as key/salt pairs , you michael@0: can use the following bash function to format the output of michael@0: /dev/random (where that device is available). michael@0: michael@0: function randhex() { michael@0: 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 }' michael@0: } michael@0: michael@0: michael@0: An example of an SRTP session using two rtpw programs follows: michael@0: michael@0: set k=c1eec3717da76195bb878578790af71c4ee9f859e197a414a78d5abc7451 michael@0: michael@0: [sh1]$ test/rtpw -s -k $k -ea 0.0.0.0 9999 michael@0: Security services: confidentiality message authentication michael@0: set master key/salt to C1EEC3717DA76195BB878578790AF71C/4EE9F859E197A414A78D5ABC7451 michael@0: setting SSRC to 2078917053 michael@0: sending word: A michael@0: sending word: a michael@0: sending word: aa michael@0: sending word: aal michael@0: ... michael@0: michael@0: [sh2]$ test/rtpw -r -k $k -ea 0.0.0.0 9999 michael@0: security services: confidentiality message authentication michael@0: set master key/salt to C1EEC3717DA76195BB878578790AF71C/4EE9F859E197A414A78D5ABC7451 michael@0: 19 octets received from SSRC 2078917053 word: A michael@0: 19 octets received from SSRC 2078917053 word: a michael@0: 20 octets received from SSRC 2078917053 word: aa michael@0: 21 octets received from SSRC 2078917053 word: aal michael@0: ... michael@0: michael@0: Implementation Notes michael@0: michael@0: * The srtp_protect() function assumes that the buffer holding the michael@0: rtp packet has enough storage allocated that the authentication michael@0: tag can be written to the end of that packet. If this assumption michael@0: is not valid, memory corruption will ensue. michael@0: michael@0: * Automated tests for the crypto functions are provided through michael@0: the cipher_type_self_test() and auth_type_self_test() functions. michael@0: These functions should be used to test each port of this code michael@0: to a new platform. michael@0: michael@0: * Replay protection is contained in the crypto engine, and michael@0: tests for it are provided. michael@0: michael@0: * This implementation provides calls to initialize, protect, and michael@0: unprotect RTP packets, and makes as few as possible assumptions michael@0: about how these functions will be called. For example, the michael@0: caller is not expected to provide packets in order (though if michael@0: they're called more than 65k out of sequence, synchronization michael@0: will be lost). michael@0: michael@0: * The sequence number in the rtp packet is used as the low 16 bits michael@0: of the sender's local packet index. Note that RTP will start its michael@0: sequence number in a random place, and the SRTP layer just jumps michael@0: forward to that number at its first invocation. An earlier michael@0: version of this library used initial sequence numbers that are michael@0: less than 32,768; this trick is no longer required as the michael@0: rdbx_estimate_index(...) function has been made smarter. michael@0: michael@0: * The replay window is 128 bits in length, and is hard-coded to this michael@0: value for now. michael@0: michael@0: