/[resiprocate]/main/reTurn/README.txt
ViewVC logotype

Contents of /main/reTurn/README.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 9938 - (show annotations) (download)
Wed Jan 9 08:11:46 2013 UTC (6 years, 10 months ago) by dpocock
File MIME type: text/plain
File size: 13023 byte(s)
reTurn: add note about OpenSSL dependency
1 reTurn Status
2 =============
3
4 Original Author: Scott Godin
5 ( s g o d i n AT s i p s p e c t r u m DOT c o m )
6
7
8 What is reTurn?
9 ---------------
10 reTurn is a Stun/Turn server and client library implementation of the latest
11 Stun/Turn drafts: RFC5389, and draft-ietf-behave-turn-15
12
13
14 Current External Library Usage
15 ------------------------------
16 - currently uses OpenSSL, ASIO, BOOST and RUTIL
17 - OpenSSL
18 - Used for TLS support (optional)
19 - libcrypto used for calculating message authentication code (mandatory
20 part of TURN, even without TLS)
21 - Therefore, unlike other parts of resiprocate, it is mandatory
22 to have OpenSSL present for building reTurn, and you must
23 specify --with-ssl when running configure or reTurn/* won't
24 be built at all.
25 - ASIO - 1.2.0
26 - Used for server sockets and transports
27 - Tuple information used in StunMessage uses asio::ip::udp::endpoint - easily changed
28 - StunMessage, TurnAllocation and RequestHandler use asio::ip:address to manipulate IPV6,
29 and IPV4 StunAddresses - easily changed
30 - StunTuple uses asio::ip::address - easily changed
31 - BOOST - 1.34.1
32 - Using BOOST in no-lib mode is fine
33 - BOOST::bind is used in server transports
34 - BOOST::crc_optimal is used for fingerprint CRC calculations
35 - BOOST::shared_ptr, array, enable_shared_from_this is used in server transports
36 - RUTIL - Data class is used in StunMessage and StunAuth for strings and TurnData, SharedPtr is also used
37
38
39 Feature Implemented Tested Notes
40 -------------------------------------------------------------------
41 Configuration Framework partially yes Currently just uses a few command line parameters and hardcoded settings
42 RFC3489 support yes mostly
43 Multi-threaded Server no no Once Turn code is implemented consider asio threading model and provide locking
44 TLS Server Support yes yes
45 RFC5389 message parsing yes partly
46 IPV6 message parsing support yes no
47 Short Term Credentials yes yes Implementation currently only accepts one hardcoded username/password
48 Long Term Credentials mostly yes Implementation currently only accepts one hardcoded username/password
49 Finger Print Insertion and Validation yes yes Uses BOOST:crc_optimal
50 Checking for unknown attributes yes yes
51 Bandwidth Check no no
52 Turn Allocation yes yes Only UDP Relay's are implemented
53 Requested Props (Even, Pair) yes yes
54 Turn Permissions yes yes
55 Turn UDP Relay yes yes
56 Turn TCP Relay no no
57 Asyncronous Client APIs yes yes
58 Channel Binding yes yes
59 Don't Fragment Attribute no no Server will reject requests asking for DF option
60
61
62 General TODO
63 -------------
64 - reduce library use - remove BOOST and/or rutil requirement - remove ASIO for client??
65 - allow multiple interfaces to be used for relay
66 - per user allocation quota enforcement
67 - cleanup stun message class so that there are accessors for all data members
68 - from chart above
69 - Configuration Framework
70 - Multi-threaded support in Server
71 - Bandwidth check
72 - TCP Relay
73 - Short Term passwords do not make any sense in reTurnServer (outside of RFC3489 backcompat) - they need to be supported on client APIs
74
75 TURN TODO's
76 -----------
77 - CreatePermission requests can contain multiple addresses - need to modify StunMessage in order to support this
78 - Clients need to install permissions before data can be sent - need to queue outbound data until CreateChannel response is received
79 - ChannelData messages must be padded to a multiple of 4 bytes, the padding is not to be reflected in the encoded length
80 - When client receives a Data Ind - it should ensure it is from an endpoint that it believes that it has installed a permission for, otherwise drop
81 - It is recommended that the client check if a permission exists towards the peer that just send a ChannelData message, if not - discard
82 - Could add checking that ChannelData messages always begin with bits 0b01, since bits 0b10 and 0b11 are reserved
83 - Need to give clients the ability to add Don't Fragment header to Allocate request
84 - If request with Don't Fragment fails with 420 code, then it can be retried without Don't Fragment (this will likely remain the responsibilty of the reTurn client application)
85 - It is recommended that the server impose limits on both the number of allocations active at one time for a given username and on the amount of bandwidth those allocations use. - 486 (Allocation Quota Exceeded)
86 - Port allocation algorithm should be better to ensure we won't run into collisions with other applications - port allocations should be random
87 - If the client receives a 400 response to a channel-bind request, then it is recommended that the allocation be deleted, and the client start again with a new allocation
88
89 RFC53389 TODO's
90 ---------------
91 -Username must contain UTF-8 sequence of bytes, and must have been processed by SASLprep
92 -Realm qdtext or quoted-pair - It must UTF-8 encoded and MUST be less than 128 characters (which can be as long as 763 bytes), and must be processed by SASLprep
93 -Nonce qdtext or quoted-pair - MUST be less than 128 characters (which can be as long as 763 bytes)
94 -Software must be a UTF-8 sequence of less than 128 characters (which can be as long as 763 byes)
95 -The Password used in the HMAC key must be SASLprep processed
96 -remove quotes and trailing nulls from username, realm. remove trailing nulls from password before forming MD5 hash for message integrity
97 -Errorcode Reason Phrase must be a UTF-8 sequence of less than 128 characters (which can be as long as 763 byes)
98 -need handling for 300 Try Alternate response - currently applications responsibility
99 -the following values should be configurable
100 - Initial RTO (default 500ms)
101 - Rc (default 7)
102 - Rm (default 16)
103 -actual RTO should be calculated
104 -UDP retransmissions should stop if a hard ICMP error is seen
105 -DNS SRV Discovery - currently only does host record lookup (using ASIO) - _stun._udp, _stun._tcp, _stuns._tcp, _turn._udp, _turn._tcp, _turns._tcp
106
107 Client TODO
108 -----------
109 - rework synchronous sockets to use Asynchrous sockets to unify implementation better
110 - keepalive usage??
111 - add option to require message integrity? - depends on usage - ICE
112 - add ability to install a permission or binding without sending data
113
114 Client Notes
115 ------------
116 - retries should be paced at 500ms, 1000ms, 2000ms, etc. - after 442, 443, or 444 response - currently applications responsibility
117 - If a client receives a 437 allocation mismatch response to an allocate, then it should retry using a different client transport address - it should do this 3 times (this will likely remain the responsibilty of the reTurn client application)
118 - To prevent race conditions a client MUST wait 5 mins after the channel binding expires before attempting to bind the channel number to a different transport address or the transport address to a different channel number (within the same allocation?).
119
120
121 Client API
122 -----------
123 Current Asynchronous Implementation:
124 - Application must provide an asio::io_service object and is responsible for threading it out and calling run
125 - Async Turn sockets must be held in a shared pointer, in order to ensure safety of asio callbacks - this could be abstracted better
126 - When Async sockets are created a callback handler class is passed in to receive callback notifications when
127 operations are complete
128
129 API Set - Wrapping in a Turn(Async)Socket - Turn(Async)UdpSocket, Turn(Async)TcpSocket, Turn(Async)TlsSocket
130 - bound to local socket
131 * setUsernameAndPassword()
132 * requestSharedSecret() - username and password are returned
133 * createAllocation(lifetime,
134 bandwidth,
135 requestedPortProps,
136 reservationToken,
137 requestedTransportType)
138 * refreshAllocation(lifetime)
139 * destroyAllocation()
140 * getRelayTuple() - (SYNC API ONLY) used to retrieve info about the allocation
141 * getReflexiveTuple() - (SYNC API ONLY) used to retrieve info about the allocation
142 * getLifetime() - (SYNC API ONLY) used to retrieve info about the allocation
143 * getBandwidth() - (SYNC API ONLY) used to retrieve info about the allocation
144 * setActiveDestination(destinationIP, destinationPort)
145 * clearActiveDestination()
146 * bindRequest()
147 * send(bufferToSend, bufferSize);
148 * sendTo(destinationIP, destinationPort, bufferToSend, bufferSize)
149 * receive(bufferToReceiveIn, bufferSize[in/out], senderIPAddress, senderPort)
150 - last 2 args are return args - if receive is non-blocking then this data is returned in callback instead
151 * receiveFrom(bufferToReceiveIn, bufferSize[in/out], senderIPAddress, senderPort)
152 - in this case last 2 args are input and specify endpoint we want to receive from
153
154 NOTE: could also add a binding discovery API for attempting to detect NAT type using RFC3489 methods
155
156 Asynchronous Callbacks:
157
158 onConnectSuccess(unsigned int socketDesc,
159 const asio::ip::address& address,
160 unsigned short port) = 0;
161 onConnectFailure(unsigned int socketDesc, const asio::error_code& e) = 0;
162
163 onSharedSecretSuccess(unsigned int socketDesc,
164 const char* username,
165 unsigned int usernameSize,
166 const char* password,
167 unsigned int passwordSize) = 0;
168 onSharedSecretFailure(unsigned int socketDesc, const asio::error_code& e) = 0;
169
170 onBindSuccess(unsigned int socketDesc, const StunTuple& reflexiveTuple) = 0;
171 onBindFailure(unsigned int socketDesc, const asio::error_code& e) = 0;
172
173 onAllocationSuccess(unsigned int socketDesc,
174 const StunTuple& reflexiveTuple,
175 const StunTuple& relayTuple,
176 unsigned int lifetime,
177 unsigned int bandwidth,
178 UInt64& reservationToken) = 0;
179 onAllocationFailure(unsigned int socketDesc, const asio::error_code& e) = 0;
180
181 onRefreshSuccess(unsigned int socketDesc, unsigned int lifetime) = 0;
182 onRefreshFailure(unsigned int socketDesc, const asio::error_code& e) = 0;
183
184 onSetActiveDestinationSuccess(unsigned int socketDesc) = 0;
185 onSetActiveDestinationFailure(unsigned int socketDesc, const asio::error_code &e) = 0;
186 onClearActiveDestinationSuccess(unsigned int socketDesc) = 0;
187 onClearActiveDestinationFailure(unsigned int socketDesc, const asio::error_code &e) = 0;
188
189 onReceiveSuccess(unsigned int socketDesc,
190 const asio::ip::address& address,
191 unsigned short port,
192 const char* buffer,
193 unsigned int size) = 0;
194 onReceiveFailure(unsigned int socketDesc, const asio::error_code& e) = 0;
195
196 onSendSuccess(unsigned int socketDesc) = 0;
197 onSendFailure(unsigned int socketDesc, const asio::error_code& e) = 0;
198
199
200 License
201 -------
202
203
204 /* ====================================================================
205
206 Copyright (c) 2007-2008, Plantronics, Inc.
207 All rights reserved.
208
209 Redistribution and use in source and binary forms, with or without
210 modification, are permitted provided that the following conditions are
211 met:
212
213 1. Redistributions of source code must retain the above copyright
214 notice, this list of conditions and the following disclaimer.
215
216 2. Redistributions in binary form must reproduce the above copyright
217 notice, this list of conditions and the following disclaimer in the
218 documentation and/or other materials provided with the distribution.
219
220 3. Neither the name of Plantronics nor the names of its contributors
221 may be used to endorse or promote products derived from this
222 software without specific prior written permission.
223
224 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
225 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
226 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
227 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
228 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
229 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
230 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
231 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
232 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
233 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
234 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
235
236 ==================================================================== */

Properties

Name Value
svn:eol-style native
svn:mime-type text/plain

webmaster AT resiprocate DOT org
ViewVC Help
Powered by ViewVC 1.1.27