1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/srtp/src/README Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,174 @@
1.4 +Secure RTP (SRTP) Reference Implementation
1.5 +David A. McGrew
1.6 +Cisco Systems, Inc.
1.7 +mcgrew@cisco.com
1.8 +
1.9 +
1.10 +This package provides an implementation of the Secure Real-time
1.11 +Transport Protocol (SRTP), the Universal Security Transform (UST), and
1.12 +a supporting cryptographic kernel. These mechanisms are documented in
1.13 +the Internet Drafts in the doc/ subdirectory. The SRTP API is
1.14 +documented in include/srtp.h, and the library is in libsrtp.a (after
1.15 +compilation). An overview and reference manual is available in
1.16 +doc/libsrtp.pdf. The PDF documentation is more up to date than this
1.17 +file.
1.18 +
1.19 +
1.20 +Installation:
1.21 +
1.22 +./configure [ options ] # GNU autoconf script
1.23 +make # or gmake if needed; use GNU make
1.24 +
1.25 +The configure script accepts the following options:
1.26 +
1.27 + --help provides a usage summary
1.28 + --disable-debug compile without the runtime debugging system
1.29 + --enable-syslog use syslog for error reporting
1.30 + --disable-stdout use stdout for error reporting
1.31 + --enable-console use /dev/console for error reporting
1.32 + --gdoi use GDOI key management (disabled at present)
1.33 +
1.34 +By default, debbuging is enabled and stdout is used for debugging.
1.35 +You can use the above configure options to have the debugging output
1.36 +sent to syslog or the system console. Alternatively, you can define
1.37 +ERR_REPORTING_FILE in include/conf.h to be any other file that can be
1.38 +opened by libSRTP, and debug messages will be sent to it.
1.39 +
1.40 +This package has been tested on Mac OS X (powerpc-apple-darwin1.4),
1.41 +Cygwin (i686-pc-cygwin), and Sparc (sparc-sun-solaris2.6). Previous
1.42 +versions have been tested on Linux and OpenBSD on both x86 and sparc
1.43 +platforms.
1.44 +
1.45 +A quick tour of this package:
1.46 +
1.47 +Makefile targets: all, clean, ...
1.48 +README this file
1.49 +CHANGES change log
1.50 +VERSION version number of this package
1.51 +LICENSE legal details (it's a BSD-like license)
1.52 +crypto/ciphers/ ciphers (null, aes_icm, ...)
1.53 +crypto/math/ crypto math routines
1.54 +crypto/hash/ crypto hashing (hmac, tmmhv2, ...)
1.55 +crypto/replay/ replay protection
1.56 +doc/ documentation: rfcs, apis, and suchlike
1.57 +include/ include files for all code in distribution
1.58 +srtp/ secure real-time transport protocol implementation
1.59 +tables/ apps for generating tables (useful in porting)
1.60 +test/ test drivers
1.61 +
1.62 +
1.63 +Applications
1.64 +
1.65 + Several test drivers and a simple and portable srtp application
1.66 + are included in the test/ subdirectory.
1.67 +
1.68 + test driver function tested
1.69 + -------------------------------------------------------------
1.70 + kernel_driver crypto kernel (ciphers, auth funcs, rng)
1.71 + srtp_driver srtp in-memory tests (does not use the network)
1.72 + rdbx_driver rdbx (extended replay database)
1.73 + roc_driver extended sequence number functions
1.74 + replay_driver replay database (n.b. not used in libsrtp)
1.75 + cipher_driver ciphers
1.76 + auth_driver hash functions
1.77 +
1.78 + The app rtpw is a simple rtp application which reads words from
1.79 + /usr/dict/words and then sends them out one at a time using [s]rtp.
1.80 + Manual srtp keying uses the -k option; automated key management
1.81 + using gdoi will be added later.
1.82 +
1.83 +usage: rtpw [-d <debug>]* [-k <key> [-a][-e]] [-s | -r] dest_ip dest_port
1.84 +or rtpw -l
1.85 +
1.86 + Either the -s (sender) or -r (receiver) option must be chosen.
1.87 +
1.88 + The values dest_ip, dest_port are the ip address and udp port to
1.89 + which the dictionary will be sent, respectively.
1.90 +
1.91 + options:
1.92 +
1.93 + -s (s)rtp sender - causes app to send words
1.94 +
1.95 + -r (s)rtp receive - causes app to receve words
1.96 +
1.97 + -k <key> use srtp master key <key>, where the
1.98 + key is a hexadecimal value (without the
1.99 + leading "0x")
1.100 +
1.101 + -e encrypt/decrypt (for data confidentiality)
1.102 + (requires use of -k option as well)
1.103 +
1.104 + -a message authentication
1.105 + (requires use of -k option as well)
1.106 +
1.107 + -l list debug modules
1.108 +
1.109 + -d <debug> turn on debugging for module <debug>
1.110 +
1.111 +
1.112 +In order to get random 30-byte values for use as key/salt pairs , you
1.113 +can use the following bash function to format the output of
1.114 +/dev/random (where that device is available).
1.115 +
1.116 +function randhex() {
1.117 + 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 }'
1.118 +}
1.119 +
1.120 +
1.121 +An example of an SRTP session using two rtpw programs follows:
1.122 +
1.123 +set k=c1eec3717da76195bb878578790af71c4ee9f859e197a414a78d5abc7451
1.124 +
1.125 +[sh1]$ test/rtpw -s -k $k -ea 0.0.0.0 9999
1.126 +Security services: confidentiality message authentication
1.127 +set master key/salt to C1EEC3717DA76195BB878578790AF71C/4EE9F859E197A414A78D5ABC7451
1.128 +setting SSRC to 2078917053
1.129 +sending word: A
1.130 +sending word: a
1.131 +sending word: aa
1.132 +sending word: aal
1.133 +...
1.134 +
1.135 +[sh2]$ test/rtpw -r -k $k -ea 0.0.0.0 9999
1.136 +security services: confidentiality message authentication
1.137 +set master key/salt to C1EEC3717DA76195BB878578790AF71C/4EE9F859E197A414A78D5ABC7451
1.138 +19 octets received from SSRC 2078917053 word: A
1.139 +19 octets received from SSRC 2078917053 word: a
1.140 +20 octets received from SSRC 2078917053 word: aa
1.141 +21 octets received from SSRC 2078917053 word: aal
1.142 +...
1.143 +
1.144 +Implementation Notes
1.145 +
1.146 + * The srtp_protect() function assumes that the buffer holding the
1.147 + rtp packet has enough storage allocated that the authentication
1.148 + tag can be written to the end of that packet. If this assumption
1.149 + is not valid, memory corruption will ensue.
1.150 +
1.151 + * Automated tests for the crypto functions are provided through
1.152 + the cipher_type_self_test() and auth_type_self_test() functions.
1.153 + These functions should be used to test each port of this code
1.154 + to a new platform.
1.155 +
1.156 + * Replay protection is contained in the crypto engine, and
1.157 + tests for it are provided.
1.158 +
1.159 + * This implementation provides calls to initialize, protect, and
1.160 + unprotect RTP packets, and makes as few as possible assumptions
1.161 + about how these functions will be called. For example, the
1.162 + caller is not expected to provide packets in order (though if
1.163 + they're called more than 65k out of sequence, synchronization
1.164 + will be lost).
1.165 +
1.166 + * The sequence number in the rtp packet is used as the low 16 bits
1.167 + of the sender's local packet index. Note that RTP will start its
1.168 + sequence number in a random place, and the SRTP layer just jumps
1.169 + forward to that number at its first invocation. An earlier
1.170 + version of this library used initial sequence numbers that are
1.171 + less than 32,768; this trick is no longer required as the
1.172 + rdbx_estimate_index(...) function has been made smarter.
1.173 +
1.174 + * The replay window is 128 bits in length, and is hard-coded to this
1.175 + value for now.
1.176 +
1.177 +
