]> code.delx.au - proxy/blob - rfc1928.txt
Initial commit v0.1
[proxy] / rfc1928.txt
1
2
3
4
5
6
7 Network Working Group M. Leech
8 Request for Comments: 1928 Bell-Northern Research Ltd
9 Category: Standards Track M. Ganis
10 International Business Machines
11 Y. Lee
12 NEC Systems Laboratory
13 R. Kuris
14 Unify Corporation
15 D. Koblas
16 Independent Consultant
17 L. Jones
18 Hewlett-Packard Company
19 March 1996
20
21
22 SOCKS Protocol Version 5
23
24 Status of this Memo
25
26 This document specifies an Internet standards track protocol for the
27 Internet community, and requests discussion and suggestions for
28 improvements. Please refer to the current edition of the "Internet
29 Official Protocol Standards" (STD 1) for the standardization state
30 and status of this protocol. Distribution of this memo is unlimited.
31
32 Acknowledgments
33
34 This memo describes a protocol that is an evolution of the previous
35 version of the protocol, version 4 [1]. This new protocol stems from
36 active discussions and prototype implementations. The key
37 contributors are: Marcus Leech: Bell-Northern Research, David Koblas:
38 Independent Consultant, Ying-Da Lee: NEC Systems Laboratory, LaMont
39 Jones: Hewlett-Packard Company, Ron Kuris: Unify Corporation, Matt
40 Ganis: International Business Machines.
41
42 1. Introduction
43
44 The use of network firewalls, systems that effectively isolate an
45 organizations internal network structure from an exterior network,
46 such as the INTERNET is becoming increasingly popular. These
47 firewall systems typically act as application-layer gateways between
48 networks, usually offering controlled TELNET, FTP, and SMTP access.
49 With the emergence of more sophisticated application layer protocols
50 designed to facilitate global information discovery, there exists a
51 need to provide a general framework for these protocols to
52 transparently and securely traverse a firewall.
53
54
55
56
57
58 Leech, et al Standards Track [Page 1]
59 \f
60 RFC 1928 SOCKS Protocol Version 5 March 1996
61
62
63 There exists, also, a need for strong authentication of such
64 traversal in as fine-grained a manner as is practical. This
65 requirement stems from the realization that client-server
66 relationships emerge between the networks of various organizations,
67 and that such relationships need to be controlled and often strongly
68 authenticated.
69
70 The protocol described here is designed to provide a framework for
71 client-server applications in both the TCP and UDP domains to
72 conveniently and securely use the services of a network firewall.
73 The protocol is conceptually a "shim-layer" between the application
74 layer and the transport layer, and as such does not provide network-
75 layer gateway services, such as forwarding of ICMP messages.
76
77 2. Existing practice
78
79 There currently exists a protocol, SOCKS Version 4, that provides for
80 unsecured firewall traversal for TCP-based client-server
81 applications, including TELNET, FTP and the popular information-
82 discovery protocols such as HTTP, WAIS and GOPHER.
83
84 This new protocol extends the SOCKS Version 4 model to include UDP,
85 and extends the framework to include provisions for generalized
86 strong authentication schemes, and extends the addressing scheme to
87 encompass domain-name and V6 IP addresses.
88
89 The implementation of the SOCKS protocol typically involves the
90 recompilation or relinking of TCP-based client applications to use
91 the appropriate encapsulation routines in the SOCKS library.
92
93 Note:
94
95 Unless otherwise noted, the decimal numbers appearing in packet-
96 format diagrams represent the length of the corresponding field, in
97 octets. Where a given octet must take on a specific value, the
98 syntax X'hh' is used to denote the value of the single octet in that
99 field. When the word 'Variable' is used, it indicates that the
100 corresponding field has a variable length defined either by an
101 associated (one or two octet) length field, or by a data type field.
102
103 3. Procedure for TCP-based clients
104
105 When a TCP-based client wishes to establish a connection to an object
106 that is reachable only via a firewall (such determination is left up
107 to the implementation), it must open a TCP connection to the
108 appropriate SOCKS port on the SOCKS server system. The SOCKS service
109 is conventionally located on TCP port 1080. If the connection
110 request succeeds, the client enters a negotiation for the
111
112
113
114 Leech, et al Standards Track [Page 2]
115 \f
116 RFC 1928 SOCKS Protocol Version 5 March 1996
117
118
119 authentication method to be used, authenticates with the chosen
120 method, then sends a relay request. The SOCKS server evaluates the
121 request, and either establishes the appropriate connection or denies
122 it.
123
124 Unless otherwise noted, the decimal numbers appearing in packet-
125 format diagrams represent the length of the corresponding field, in
126 octets. Where a given octet must take on a specific value, the
127 syntax X'hh' is used to denote the value of the single octet in that
128 field. When the word 'Variable' is used, it indicates that the
129 corresponding field has a variable length defined either by an
130 associated (one or two octet) length field, or by a data type field.
131
132 The client connects to the server, and sends a version
133 identifier/method selection message:
134
135 +----+----------+----------+
136 |VER | NMETHODS | METHODS |
137 +----+----------+----------+
138 | 1 | 1 | 1 to 255 |
139 +----+----------+----------+
140
141 The VER field is set to X'05' for this version of the protocol. The
142 NMETHODS field contains the number of method identifier octets that
143 appear in the METHODS field.
144
145 The server selects from one of the methods given in METHODS, and
146 sends a METHOD selection message:
147
148 +----+--------+
149 |VER | METHOD |
150 +----+--------+
151 | 1 | 1 |
152 +----+--------+
153
154 If the selected METHOD is X'FF', none of the methods listed by the
155 client are acceptable, and the client MUST close the connection.
156
157 The values currently defined for METHOD are:
158
159 o X'00' NO AUTHENTICATION REQUIRED
160 o X'01' GSSAPI
161 o X'02' USERNAME/PASSWORD
162 o X'03' to X'7F' IANA ASSIGNED
163 o X'80' to X'FE' RESERVED FOR PRIVATE METHODS
164 o X'FF' NO ACCEPTABLE METHODS
165
166 The client and server then enter a method-specific sub-negotiation.
167
168
169
170 Leech, et al Standards Track [Page 3]
171 \f
172 RFC 1928 SOCKS Protocol Version 5 March 1996
173
174
175 Descriptions of the method-dependent sub-negotiations appear in
176 separate memos.
177
178 Developers of new METHOD support for this protocol should contact
179 IANA for a METHOD number. The ASSIGNED NUMBERS document should be
180 referred to for a current list of METHOD numbers and their
181 corresponding protocols.
182
183 Compliant implementations MUST support GSSAPI and SHOULD support
184 USERNAME/PASSWORD authentication methods.
185
186 4. Requests
187
188 Once the method-dependent subnegotiation has completed, the client
189 sends the request details. If the negotiated method includes
190 encapsulation for purposes of integrity checking and/or
191 confidentiality, these requests MUST be encapsulated in the method-
192 dependent encapsulation.
193
194 The SOCKS request is formed as follows:
195
196 +----+-----+-------+------+----------+----------+
197 |VER | CMD | RSV | ATYP | DST.ADDR | DST.PORT |
198 +----+-----+-------+------+----------+----------+
199 | 1 | 1 | X'00' | 1 | Variable | 2 |
200 +----+-----+-------+------+----------+----------+
201
202 Where:
203
204 o VER protocol version: X'05'
205 o CMD
206 o CONNECT X'01'
207 o BIND X'02'
208 o UDP ASSOCIATE X'03'
209 o RSV RESERVED
210 o ATYP address type of following address
211 o IP V4 address: X'01'
212 o DOMAINNAME: X'03'
213 o IP V6 address: X'04'
214 o DST.ADDR desired destination address
215 o DST.PORT desired destination port in network octet
216 order
217
218 The SOCKS server will typically evaluate the request based on source
219 and destination addresses, and return one or more reply messages, as
220 appropriate for the request type.
221
222
223
224
225
226 Leech, et al Standards Track [Page 4]
227 \f
228 RFC 1928 SOCKS Protocol Version 5 March 1996
229
230
231 5. Addressing
232
233 In an address field (DST.ADDR, BND.ADDR), the ATYP field specifies
234 the type of address contained within the field:
235
236 o X'01'
237
238 the address is a version-4 IP address, with a length of 4 octets
239
240 o X'03'
241
242 the address field contains a fully-qualified domain name. The first
243 octet of the address field contains the number of octets of name that
244 follow, there is no terminating NUL octet.
245
246 o X'04'
247
248 the address is a version-6 IP address, with a length of 16 octets.
249
250 6. Replies
251
252 The SOCKS request information is sent by the client as soon as it has
253 established a connection to the SOCKS server, and completed the
254 authentication negotiations. The server evaluates the request, and
255 returns a reply formed as follows:
256
257 +----+-----+-------+------+----------+----------+
258 |VER | REP | RSV | ATYP | BND.ADDR | BND.PORT |
259 +----+-----+-------+------+----------+----------+
260 | 1 | 1 | X'00' | 1 | Variable | 2 |
261 +----+-----+-------+------+----------+----------+
262
263 Where:
264
265 o VER protocol version: X'05'
266 o REP Reply field:
267 o X'00' succeeded
268 o X'01' general SOCKS server failure
269 o X'02' connection not allowed by ruleset
270 o X'03' Network unreachable
271 o X'04' Host unreachable
272 o X'05' Connection refused
273 o X'06' TTL expired
274 o X'07' Command not supported
275 o X'08' Address type not supported
276 o X'09' to X'FF' unassigned
277 o RSV RESERVED
278 o ATYP address type of following address
279
280
281
282 Leech, et al Standards Track [Page 5]
283 \f
284 RFC 1928 SOCKS Protocol Version 5 March 1996
285
286
287 o IP V4 address: X'01'
288 o DOMAINNAME: X'03'
289 o IP V6 address: X'04'
290 o BND.ADDR server bound address
291 o BND.PORT server bound port in network octet order
292
293 Fields marked RESERVED (RSV) must be set to X'00'.
294
295 If the chosen method includes encapsulation for purposes of
296 authentication, integrity and/or confidentiality, the replies are
297 encapsulated in the method-dependent encapsulation.
298
299 CONNECT
300
301 In the reply to a CONNECT, BND.PORT contains the port number that the
302 server assigned to connect to the target host, while BND.ADDR
303 contains the associated IP address. The supplied BND.ADDR is often
304 different from the IP address that the client uses to reach the SOCKS
305 server, since such servers are often multi-homed. It is expected
306 that the SOCKS server will use DST.ADDR and DST.PORT, and the
307 client-side source address and port in evaluating the CONNECT
308 request.
309
310 BIND
311
312 The BIND request is used in protocols which require the client to
313 accept connections from the server. FTP is a well-known example,
314 which uses the primary client-to-server connection for commands and
315 status reports, but may use a server-to-client connection for
316 transferring data on demand (e.g. LS, GET, PUT).
317
318 It is expected that the client side of an application protocol will
319 use the BIND request only to establish secondary connections after a
320 primary connection is established using CONNECT. In is expected that
321 a SOCKS server will use DST.ADDR and DST.PORT in evaluating the BIND
322 request.
323
324 Two replies are sent from the SOCKS server to the client during a
325 BIND operation. The first is sent after the server creates and binds
326 a new socket. The BND.PORT field contains the port number that the
327 SOCKS server assigned to listen for an incoming connection. The
328 BND.ADDR field contains the associated IP address. The client will
329 typically use these pieces of information to notify (via the primary
330 or control connection) the application server of the rendezvous
331 address. The second reply occurs only after the anticipated incoming
332 connection succeeds or fails.
333
334
335
336
337
338 Leech, et al Standards Track [Page 6]
339 \f
340 RFC 1928 SOCKS Protocol Version 5 March 1996
341
342
343 In the second reply, the BND.PORT and BND.ADDR fields contain the
344 address and port number of the connecting host.
345
346 UDP ASSOCIATE
347
348 The UDP ASSOCIATE request is used to establish an association within
349 the UDP relay process to handle UDP datagrams. The DST.ADDR and
350 DST.PORT fields contain the address and port that the client expects
351 to use to send UDP datagrams on for the association. The server MAY
352 use this information to limit access to the association. If the
353 client is not in possesion of the information at the time of the UDP
354 ASSOCIATE, the client MUST use a port number and address of all
355 zeros.
356
357 A UDP association terminates when the TCP connection that the UDP
358 ASSOCIATE request arrived on terminates.
359
360 In the reply to a UDP ASSOCIATE request, the BND.PORT and BND.ADDR
361 fields indicate the port number/address where the client MUST send
362 UDP request messages to be relayed.
363
364 Reply Processing
365
366 When a reply (REP value other than X'00') indicates a failure, the
367 SOCKS server MUST terminate the TCP connection shortly after sending
368 the reply. This must be no more than 10 seconds after detecting the
369 condition that caused a failure.
370
371 If the reply code (REP value of X'00') indicates a success, and the
372 request was either a BIND or a CONNECT, the client may now start
373 passing data. If the selected authentication method supports
374 encapsulation for the purposes of integrity, authentication and/or
375 confidentiality, the data are encapsulated using the method-dependent
376 encapsulation. Similarly, when data arrives at the SOCKS server for
377 the client, the server MUST encapsulate the data as appropriate for
378 the authentication method in use.
379
380 7. Procedure for UDP-based clients
381
382 A UDP-based client MUST send its datagrams to the UDP relay server at
383 the UDP port indicated by BND.PORT in the reply to the UDP ASSOCIATE
384 request. If the selected authentication method provides
385 encapsulation for the purposes of authenticity, integrity, and/or
386 confidentiality, the datagram MUST be encapsulated using the
387 appropriate encapsulation. Each UDP datagram carries a UDP request
388 header with it:
389
390
391
392
393
394 Leech, et al Standards Track [Page 7]
395 \f
396 RFC 1928 SOCKS Protocol Version 5 March 1996
397
398
399 +----+------+------+----------+----------+----------+
400 |RSV | FRAG | ATYP | DST.ADDR | DST.PORT | DATA |
401 +----+------+------+----------+----------+----------+
402 | 2 | 1 | 1 | Variable | 2 | Variable |
403 +----+------+------+----------+----------+----------+
404
405 The fields in the UDP request header are:
406
407 o RSV Reserved X'0000'
408 o FRAG Current fragment number
409 o ATYP address type of following addresses:
410 o IP V4 address: X'01'
411 o DOMAINNAME: X'03'
412 o IP V6 address: X'04'
413 o DST.ADDR desired destination address
414 o DST.PORT desired destination port
415 o DATA user data
416
417 When a UDP relay server decides to relay a UDP datagram, it does so
418 silently, without any notification to the requesting client.
419 Similarly, it will drop datagrams it cannot or will not relay. When
420 a UDP relay server receives a reply datagram from a remote host, it
421 MUST encapsulate that datagram using the above UDP request header,
422 and any authentication-method-dependent encapsulation.
423
424 The UDP relay server MUST acquire from the SOCKS server the expected
425 IP address of the client that will send datagrams to the BND.PORT
426 given in the reply to UDP ASSOCIATE. It MUST drop any datagrams
427 arriving from any source IP address other than the one recorded for
428 the particular association.
429
430 The FRAG field indicates whether or not this datagram is one of a
431 number of fragments. If implemented, the high-order bit indicates
432 end-of-fragment sequence, while a value of X'00' indicates that this
433 datagram is standalone. Values between 1 and 127 indicate the
434 fragment position within a fragment sequence. Each receiver will
435 have a REASSEMBLY QUEUE and a REASSEMBLY TIMER associated with these
436 fragments. The reassembly queue must be reinitialized and the
437 associated fragments abandoned whenever the REASSEMBLY TIMER expires,
438 or a new datagram arrives carrying a FRAG field whose value is less
439 than the highest FRAG value processed for this fragment sequence.
440 The reassembly timer MUST be no less than 5 seconds. It is
441 recommended that fragmentation be avoided by applications wherever
442 possible.
443
444 Implementation of fragmentation is optional; an implementation that
445 does not support fragmentation MUST drop any datagram whose FRAG
446 field is other than X'00'.
447
448
449
450 Leech, et al Standards Track [Page 8]
451 \f
452 RFC 1928 SOCKS Protocol Version 5 March 1996
453
454
455 The programming interface for a SOCKS-aware UDP MUST report an
456 available buffer space for UDP datagrams that is smaller than the
457 actual space provided by the operating system:
458
459 o if ATYP is X'01' - 10+method_dependent octets smaller
460 o if ATYP is X'03' - 262+method_dependent octets smaller
461 o if ATYP is X'04' - 20+method_dependent octets smaller
462
463 8. Security Considerations
464
465 This document describes a protocol for the application-layer
466 traversal of IP network firewalls. The security of such traversal is
467 highly dependent on the particular authentication and encapsulation
468 methods provided in a particular implementation, and selected during
469 negotiation between SOCKS client and SOCKS server.
470
471 Careful consideration should be given by the administrator to the
472 selection of authentication methods.
473
474 9. References
475
476 [1] Koblas, D., "SOCKS", Proceedings: 1992 Usenix Security Symposium.
477
478 Author's Address
479
480 Marcus Leech
481 Bell-Northern Research Ltd
482 P.O. Box 3511, Stn. C,
483 Ottawa, ON
484 CANADA K1Y 4H7
485
486 Phone: (613) 763-9145
487 EMail: mleech@bnr.ca
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506 Leech, et al Standards Track [Page 9]
507 \f