idnits 2.17.1 draft-ietf-aft-socks-pro-v5-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-26) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 76 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Abstract section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 4 instances of too long lines in the document, the longest one being 5 characters in excess of 72. ** There are 2 instances of lines with control characters in the document. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 146: '..., and the client MUST close the connec...' RFC 2119 keyword, line 150: '... o X'00' NO AUTHENTICATION REQUIRED...' RFC 2119 keyword, line 167: '... implementations MUST support GSSAPI a...' RFC 2119 keyword, line 175: '..., these requests MUST be encapsulated ...' RFC 2119 keyword, line 309: '...n for the association. The server MAY...' (14 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (March 1997) is 9904 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. '1' Summary: 12 errors (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 AFT Working Group M. Leech 3 INTERNET DRAFT 4 Expire in six months M. Ganis 5 International Business Machines 6 Y. Lee 7 NEC Systems Laboratory 8 R. Kuris 9 Unify Corporation 10 D. Koblas 11 Independent Consultant 12 L. Jones 13 Hewlett-Packard Company 14 D. Blob 15 NEC USA 16 W. Lu 17 NEC USA 18 March 1997 20 SOCKS Protocol Version 5 21 23 Status of this Memo 25 This document is a submission to the IETF Authenticated Firewall Traversal 26 (AFT) Working Group. Comments are solicited and should be addressed 27 to the working group mailing list (aft@unify.com) or to the editor. 29 This document is an Internet-Draft. Internet Drafts are working 30 documents of the Internet Engineering Task Force (IETF), its areas, 31 and its working Groups. Note that other groups may also distribute 32 working documents as Internet Drafts. 34 Internet-Drafts draft documents are valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 To learn the current status of any Internet-Draft, please check the 40 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 41 Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), 42 munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or 43 ftp.isi.edu (US West Coast). 45 Distribution of this memo is unlimited 47 Acknowledgments 49 This memo describes a protocol that is an evolution of the previous 50 version of the protocol, version 4 [1]. This new protocol stems from 51 active discussions and prototype implementations. The key 52 contributors are: Marcus Leech: Bell-Northern Research, David Koblas: 53 Independent Consultant, Ying-Da Lee: NEC Systems Laboratory, LaMont 54 Jones: Hewlett-Packard Company, Ron Kuris: Unify Corporation, Matt 55 Ganis: International Business Machines, David Blob: NEC USA, Wei Lu: 56 NEC USA. 58 1. Introduction 60 The use of network firewalls, systems that effectively isolate an 61 organizations internal network structure from an exterior network, 62 such as the INTERNET is becoming increasingly popular. These 63 firewall systems typically act as application-layer gateways between 64 networks, usually offering controlled TELNET, FTP, and SMTP access. 65 With the emergence of more sophisticated application layer protocols 66 designed to facilitate global information discovery, there exists a 67 need to provide a general framework for these protocols to 68 transparently and securely traverse a firewall. 70 There exists, also, a need for strong authentication of such 71 traversal in as fine-grained a manner as is practical. This 72 requirement stems from the realization that client-server 73 relationships emerge between the networks of various organizations, 74 and that such relationships need to be controlled and often strongly 75 authenticated. 77 The protocol described here is designed to provide a framework for 78 client-server applications in both the TCP and UDP domains to 79 conveniently and securely use the services of a network firewall. 80 The protocol is conceptually a "shim-layer" between the application 81 layer and the transport layer, and as such does not provide network- 82 layer gateway services, such as forwarding of ICMP messages. 84 2. Existing practice 86 There currently exists a protocol, SOCKS Version 4, that provides for 87 unsecured firewall traversal for TCP-based client-server 88 applications, including TELNET, FTP and the popular information- 89 discovery protocols such as HTTP, WAIS and GOPHER. 91 This new protocol extends the SOCKS Version 4 model to include UDP, 92 and extends the framework to include provisions for generalized 93 strong authentication schemes, and extends the addressing scheme to 94 encompass domain-name and V6 IP addresses. 96 The implementation of the SOCKS protocol typically involves the 97 recompilation or relinking of TCP-based client applications to use 98 the appropriate encapsulation routines in the SOCKS library. 100 Note: 102 Unless otherwise noted, the decimal numbers appearing in packet- 103 format diagrams represent the length of the corresponding field, in 104 octets. Where a given octet must take on a specific value, the 105 syntax X'hh' is used to denote the value of the single octet in that 106 field. When the word 'Variable' is used, it indicates that the 107 corresponding field has a variable length defined either by an 108 associated (one or two octet) length field, or by a data type field. 110 3. Procedure for TCP-based clients 112 When a TCP-based client wishes to establish a connection to an object 113 that is reachable only via a firewall (such determination is left up 114 to the implementation), it must open a TCP connection to the 115 appropriate SOCKS port on the SOCKS server system. The SOCKS service 116 is conventionally located on TCP port 1080. If the connection 117 request succeeds, the client enters a negotiation for the 118 authentication method to be used, authenticates with the chosen 119 method, then sends a relay request. The SOCKS server evaluates the 120 request, and either establishes the appropriate connection or denies 121 it. 123 The client connects to the server, and sends a version 124 identifier/method selection message: 126 +----+----------+----------+ 127 |VER | NMETHODS | METHODS | 128 +----+----------+----------+ 129 | 1 | 1 | 1 to 255 | 130 +----+----------+----------+ 132 The VER field is set to X'05' for this version of the protocol. The 133 NMETHODS field contains the number of method identifier octets that 134 appear in the METHODS field. 136 The server selects from one of the methods given in METHODS, and 137 sends a METHOD selection message: 139 +----+--------+ 140 |VER | METHOD | 141 +----+--------+ 142 | 1 | 1 | 143 +----+--------+ 145 If the selected METHOD is X'FF', none of the methods listed by the 146 client are acceptable, and the client MUST close the connection. 148 The values currently defined for METHOD are: 150 o X'00' NO AUTHENTICATION REQUIRED 151 o X'01' GSSAPI 152 o X'02' USERNAME/PASSWORD 153 o X'03' to X'7F' IANA ASSIGNED 154 o X'80' to X'FE' RESERVED FOR PRIVATE METHODS 155 o X'FF' NO ACCEPTABLE METHODS 157 The client and server then enter a method-specific sub-negotiation. 159 Descriptions of the method-dependent sub-negotiations appear in 160 separate memos. 162 Developers of new METHOD support for this protocol should contact 163 IANA for a METHOD number. The ASSIGNED NUMBERS document should be 164 referred to for a current list of METHOD numbers and their 165 corresponding protocols. 167 Compliant implementations MUST support GSSAPI and SHOULD support 168 USERNAME/PASSWORD authentication methods. 170 4. Requests 172 Once the method-dependent subnegotiation has completed, the client 173 sends the request details. If the negotiated method includes 174 encapsulation for purposes of integrity checking and/or 175 confidentiality, these requests MUST be encapsulated in the method- 176 dependent encapsulation. 178 The SOCKS request is formed as follows: 180 +----+-----+------+------+----------+----------+ 181 |VER | CMD | FLAG | ATYP | DST.ADDR | DST.PORT | 182 +----+-----+------+------+----------+----------+ 183 | 1 | 1 | 1 | 1 | Variable | 2 | 184 +----+-----+------+------+----------+----------+ 186 Where: 188 o VER protocol version: X'05' 189 o CMD 190 o CONNECT X'01' 191 o BIND X'02' 192 o UDP ASSOCIATE X'03' 193 o FLAG command dependent flag 194 o ATYP address type of following address 195 o IP V4 address: X'01' 196 o DOMAINNAME: X'03' 197 o IP V6 address: X'04' 198 o DST.ADDR desired destination address 199 o DST.PORT desired destination port in network octet 200 order 202 The SOCKS server will typically evaluate the request based on source 203 and destination addresses, and return one or more reply messages, as 204 appropriate for the request type. 206 5. Addressing 208 In an address field (DST.ADDR, BND.ADDR), the ATYP field specifies 209 the type of address contained within the field: 211 o X'01' 213 the address is a version-4 IP address, with a length of 4 octets 215 o X'03' 217 the address field contains a fully-qualified domain name. The first 218 octet of the address field contains the number of octets of name that 219 follow, there is no terminating NUL octet. 221 o X'04' 223 the address is a version-6 IP address, with a length of 16 octets. 225 6. Replies 227 The SOCKS request information is sent by the client as soon as it has 228 established a connection to the SOCKS server, and completed the 229 authentication negotiations. The server evaluates the request, and 230 returns a reply formed as follows: 232 +----+-----+------+------+----------+----------+ 233 |VER | REP | FLAG | ATYP | BND.ADDR | BND.PORT | 234 +----+-----+------+------+----------+----------+ 235 | 1 | 1 | 1 | 1 | Variable | 2 | 236 +----+-----+------+------+----------+----------+ 238 Where: 240 o VER protocol version: X'05' 241 o REP Reply field: 242 o X'00' succeeded 243 o X'01' general SOCKS server failure 244 o X'02' connection not allowed by ruleset 245 o X'03' Network unreachable 246 o X'04' Host unreachable 247 o X'05' Connection refused 248 o X'06' TTL expired 249 o X'07' Command not supported 250 o X'08' Address type not supported 251 o X'09' to X'FF' unassigned 252 o FLAG command dependent flag 253 o ATYP address type of following address 254 o IP V4 address: X'01' 255 o DOMAINNAME: X'03' 256 o IP V6 address: X'04' 257 o BND.ADDR server bound address 258 o BND.PORT server bound port in network octet order 260 Fields marked RESERVED (RSV) must be set to X'00'. 262 If the chosen method includes encapsulation for purposes of 263 authentication, integrity and/or confidentiality, the replies are 264 encapsulated in the method-dependent encapsulation. 266 CONNECT 268 In the reply to a CONNECT, BND.PORT contains the port number that the 269 server assigned to connect to the target host, while BND.ADDR 270 contains the associated IP address. The supplied BND.ADDR is often 271 different from the IP address that the client uses to reach the SOCKS 272 server, since such servers are often multi-homed. It is expected 273 that the SOCKS server will use DST.ADDR and DST.PORT, and the 274 client-side source address and port in evaluating the CONNECT 275 request. 277 BIND 279 The BIND request is used in protocols which require the client to 280 accept connections from the server. FTP is a well-known example, 281 which uses the primary client-to-server connection for commands and 282 status reports, but may use a server-to-client connection for 283 transferring data on demand (e.g. LS, GET, PUT). 285 It is expected that the client side of an application protocol will 286 use the BIND request only to establish secondary connections after a 287 primary connection is established using CONNECT. In is expected that 288 a SOCKS server will use DST.ADDR and DST.PORT in evaluating the BIND 289 request. 291 Two replies are sent from the SOCKS server to the client during a 292 BIND operation. The first is sent after the server creates and binds 293 a new socket. The BND.PORT field contains the port number that the 294 SOCKS server assigned to listen for an incoming connection. The 295 BND.ADDR field contains the associated IP address. The client will 296 typically use these pieces of information to notify (via the primary 297 or control connection) the application server of the rendezvous 298 address. The second reply occurs only after the anticipated incoming 299 connection succeeds or fails. 301 In the second reply, the BND.PORT and BND.ADDR fields contain the 302 address and port number of the connecting host. 304 UDP ASSOCIATE 306 The UDP ASSOCIATE request is used to establish an association within 307 the UDP relay process to handle UDP datagrams. The DST.ADDR and 308 DST.PORT fields contain the address and port that the client expects 309 to use to send UDP datagrams on for the association. The server MAY 310 use this information to limit access to the association. If the 311 client is not in possesion of the information at the time of the UDP 312 ASSOCIATE, the client MUST use address type X'01' with a port number 313 and address of all zeros. 315 A UDP association terminates when the TCP connection that the UDP 316 ASSOCIATE request arrived on terminates. 318 In the reply to a UDP ASSOCIATE request, the BND.PORT and BND.ADDR 319 fields indicate the port number/address where the client MUST send 320 UDP request messages to be relayed (unless the UDP relaying is done 321 in the TCP channel as specified by the TCP RELAY flag). 323 Reply Processing 325 When a reply (REP value other than X'00') indicates a failure, the 326 SOCKS server MUST terminate the TCP connection shortly after sending 327 the reply. This must be no more than 10 seconds after detecting the 328 condition that caused a failure. 330 If the reply code (REP value of X'00') indicates a success, and the 331 request was either a BIND or a CONNECT, the client may now start 332 passing data. If the selected authentication method supports 333 encapsulation for the purposes of integrity, authentication and/or 334 confidentiality, the data are encapsulated using the method-dependent 335 encapsulation. Similarly, when data arrives at the SOCKS server for 336 the client, the server MUST encapsulate the data as appropriate for 337 the authentication method in use. 339 UDP Control Channel 341 Following UDP association, the tcp channel remains unused until 342 termination unless the client and server use it in accordance with a 343 FLAG setting. After the initial negotiation, the client and the server 344 MUST use this format to send any data on the control channel: 346 +----+-----+------+------+----------+------+------+----------+ 347 |RSV | SUB | FLAG | ATYP | ADDR | PORT | SIZE | DATA | 348 +----+-----+------+------+----------+------+------+----------+ 349 | 1 | 1 | 1 | 1 | Variable | 2 | 4 | Variable | 350 +----+-----+------+------+----------+------+------+----------+ 352 The fields in the CONTROL CHANNEL packet are: 354 o RSV Reserved X'00' 355 o SUB Subcommand 356 o INTERFACE DATA: X'01' 357 o SENDTO: X'03' 358 o FLAG A subcommand dependent flag 359 o ATYP address type of following addresses: 360 o IP V4 address: X'01' 361 o DOMAINNAME: X'03' 362 o IP V6 address: X'04' 363 o ADDR any address information 364 o PORT any port information 365 o SIZE the size (in octets) of data in network order 366 o DATA user data 368 Flags 370 UDP ASSOCIATE request flags enable optional features in UDP ASSOCIATE. 371 All flags are optional and XOR the flags to combine them. Clients 372 that demand a feature be set must terminate the connection when they 373 receive a response that does not confirm the feature setting. 375 Valid flags for use with UDP ASSOCIATE are: 377 o INTERFACE REQUEST: X'01' 378 o TCP RELAY: X'02' 379 o USE PORT: X'04' 381 Interface Requests 383 When the INTERFACE REQUEST flag is set in the UDP ASSOCIATE request 384 and also in the reply, the client may use the CONTROL CHANNEL to send 385 interface requests and the server uses the CONTROL CHANNEL to receive 386 interface requests. Clients use interface requests to determine the 387 interface address and port that the server uses to send data to a 388 destination. 390 In an interface request, the client sets SUB to INTERFACE DATA X'01', 391 sets FLAGS to X'00', and leaves DATA empty. The interface request 392 should specify the destination address using ATYPE, ADDR, and PORT. 394 When the server receives an INTERFACE REQUEST, the server checks to 395 determine if a bound UDP socket exists to send a datagram to the 396 destination. If a UDP socket does not exist, the server creates and 397 binds a UDP socket. 399 The server's reply to the client on the CONTOL CHANNEL sets SUB to 400 INTERFACE DATA X'01', sets FLAGS to X'00', and leaves DATA empty. The 401 server determines the remaining fields in the packet by the existence 402 of a bound UDP socket. When a bound socket does not exist and the 403 server fails to create or bind a socket to send data to the 404 destination, it sets ATYPE to X'01, and sets ADDR and PORT to zeroes. 405 When a bound UDP socket exists or the server successfully creates and 406 binds a UDP socket, the server sets the PORT field to the port number 407 that the SOCKS server assigned to the socket, and sets the ADDR field 408 to the associated IP address. The client will typically use this 409 information to notify the application server of the rendezvous address 410 (through the primary or control connection). 412 Whenever possible, the server should bind to the same port on all 413 outgoing UDP sockets so that the client may effectively consider 414 itself bound to a given port. 416 TCP relay server 418 The client can request that the server not set up a UDP relay server, 419 and that all communication between the client and the SOCKS server 420 occur on the TCP CONTROL CHANNEL. To do so, the client uses CONTROL 421 CHANNEL packets with the SUB command set to SENDTO, X'03'. 423 Fragmentation is not necessary and so not supported with TCP relay 424 sendtos. 426 As with the UDP relay, a TCP relay server relays a UDP datagram 427 silently. Similarly, it disregards packets with datagrams it cannot 428 or will not relay. 430 Use Port 432 When the USE PORT flag is set in the UDP associate request, the 433 server MUST bind all UDP sockets associated with this session to the 434 same port as the client. When the relay is TCP based and there is 435 no client UDP socket, the server should use the port the client 436 specified in the initial request. When the client omits a port, the 437 server can choose any port. When the SOCKS server can not bind to 438 the client requested port, it should terminate the connection by 439 closing the TCP connection. 441 7. Procedure for UDP-based clients 443 A UDP-based client MUST send its datagrams to the UDP relay server at 444 the UDP port indicated by BND.PORT in the reply to the UDP ASSOCIATE 445 request. If the selected authentication method provides 446 encapsulation for the purposes of authenticity, integrity, and/or 447 confidentiality, the datagram MUST be encapsulated using the 448 appropriate encapsulation. Each UDP datagram carries a UDP request 449 header with it: 451 +----+------+------+----------+----------+----------+ 452 |RSV | FRAG | ATYP | DST.ADDR | DST.PORT | DATA | 453 +----+------+------+----------+----------+----------+ 454 | 2 | 1 | 1 | Variable | 2 | Variable | 455 +----+------+------+----------+----------+----------+ 457 The fields in the UDP request header are: 459 o RSV Reserved X'0000' 460 o FRAG Current fragment number 461 o ATYP address type of following addresses: 462 o IP V4 address: X'01' 463 o DOMAINNAME: X'03' 464 o IP V6 address: X'04' 465 o DST.ADDR desired destination address 466 o DST.PORT desired destination port 467 o DATA user data 469 When a UDP relay server decides to relay a UDP datagram, it does so 470 silently, without any notification to the requesting client. 471 Similarly, it will drop datagrams it cannot or will not relay. When 472 a UDP relay server receives a reply datagram from a remote host, it 473 MUST encapsulate that datagram using the above UDP request header, 474 and any authentication-method-dependent encapsulation. 476 The UDP relay server MUST acquire from the SOCKS server the expected 477 IP address of the client that will send datagrams to the BND.PORT 478 given in the reply to UDP ASSOCIATE. It MUST drop any datagrams 479 arriving from any source IP address other than the one recorded for 480 the particular association. 482 The FRAG field indicates whether or not this datagram is one of a 483 number of fragments. If implemented, the high-order bit indicates 484 end-of-fragment sequence, while a value of X'00' indicates that this 485 datagram is standalone. Values between 1 and 127 indicate the 486 fragment position within a fragment sequence. Each receiver will 487 have a REASSEMBLY QUEUE and a REASSEMBLY TIMER associated with these 488 fragments. The reassembly queue must be reinitialized and the 489 associated fragments abandoned whenever the REASSEMBLY TIMER expires, 490 or a new datagram arrives carrying a FRAG field whose value is less 491 than the highest FRAG value processed for this fragment sequence. 492 The reassembly timer MUST be no less than 5 seconds. It is 493 recommended that fragmentation be avoided by applications wherever 494 possible. 496 Implementation of fragmentation is optional; an implementation that 497 does not support fragmentation MUST drop any datagram whose FRAG 498 field is other than X'00'. 500 The programming interface for a SOCKS-aware UDP MUST report an 501 available buffer space for UDP datagrams that is smaller than the 502 actual space provided by the operating system: 504 o if ATYP is X'01' - 10+method_dependent octets smaller 505 o if ATYP is X'03' - 262+method_dependent octets smaller 506 o if ATYP is X'04' - 20+method_dependent octets smaller 508 8. Security Considerations 510 This document describes a protocol for the application-layer 511 traversal of IP network firewalls. The security of such traversal is 512 highly dependent on the particular authentication and encapsulation 513 methods provided in a particular implementation, and selected during 514 negotiation between SOCKS client and SOCKS server. 516 Careful consideration should be given by the administrator to the 517 selection of authentication methods. 519 9. References 521 [1] Koblas, D., "SOCKS", Proceedings: 1992 Usenix Security Symposium. 523 Author's Address 525 Marcus Leech 526 Bell-Northern Research Ltd 527 P.O. Box 3511, Stn. C, 528 Ottawa, ON 529 CANADA K1Y 4H7 531 Phone: (613) 763-9145 532 EMail: mleech@bnr.ca 534 --