← Back to branch summary

~ubuntu-branches/ubuntu/wily/sflphone/wily

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.0.1/third_party/srtp/README

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (1.1.11)
  • mto: This revision was merged to the branch mainline in revision 24.
  • Revision ID: package-import@ubuntu.com-20140128182336-3xenud1kbnwmf3mz
http://bugs.debian.org/735846
http://bugs.debian.org/727164
http://bugs.debian.org/718178
http://bugs.debian.org/736583
http://bugs.debian.org/722040
http://bugs.debian.org/736746
* New upstream release 
  - Fixes "New Upstream Release" (Closes: #735846)
  - Fixes "Ringtone does not stop" (Closes: #727164)
  - Fixes "[sflphone-kde] crash on startup" (Closes: #718178)
  - Fixes "sflphone GUI crashes when call is hung up" (Closes: #736583)
* Build-Depends: ensure GnuTLS 2.6
  - libucommon-dev (>= 6.0.7-1.1), libccrtp-dev (>= 2.0.6-3)
  - Fixes "FTBFS Build-Depends libgnutls{26,28}-dev" (Closes: #722040)
* Fix "boost 1.49 is going away" unversioned Build-Depends: (Closes: #736746)
* Add Build-Depends: libsndfile-dev, nepomuk-core-dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.0.1/third_party/srtp/README
1
 
Secure RTP (SRTP) Reference Implementation
2
 
David A. McGrew
3
 
Cisco Systems, Inc.
4
 
mcgrew@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.