idnits 2.17.1 draft-ietf-aft-socks-pro-v5-03.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-19) 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 document type: Expected "INTERNET-DRAFT" in the upper left hand corner of the first page ** 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 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 9 instances of too long lines in the document, the longest one being 1 character in excess of 72. ** 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 140: '..., and the client MUST close the connec...' RFC 2119 keyword, line 144: '... o X'00' NO AUTHENTICATION REQUIRED...' RFC 2119 keyword, line 162: '... implementations MUST support NO AUTHE...' RFC 2119 keyword, line 163: '... CHAP, SHOULD support USERNAME/PASSW...' RFC 2119 keyword, line 170: '... encapsulation SHOULD define a metho...' (17 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: If the USECLIENTSPORT bit is set in the flag field of the request, the server SHOULD interact with the application server using the same port the client used in the request, and set the USECLIENTSPORT bit in the flag field of the reply to acknowledge having done so. If no port number was specified in the UDP ASSOCIATE request, this flag is meaningless and MUST not be used. -- 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 (22 June 1998) is 9433 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) == Unused Reference: 'CHAP' is defined on line 465, but no explicit reference was found in the text == Unused Reference: 'RFC 1928' is defined on line 468, but no explicit reference was found in the text == Unused Reference: 'RFC 1929' is defined on line 471, but no explicit reference was found in the text == Unused Reference: 'RFC 1961' is defined on line 474, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'CHAP' -- Possible downref: Non-RFC (?) normative reference: ref. 'SOCKS' Summary: 12 errors (**), 0 flaws (~~), 6 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 AFT Working Group Marc VanHeyningen 3 draft-ietf-aft-socks-pro-v5-03 Aventail Corp. 4 Expires in six months 22 June 1998 6 SOCKS Protocol Version 5 8 Status of this Memo 10 This document is a submission to the IETF Authenticated Firewall 11 Traversal (AFT) Working Group. Comments are solicited and should be 12 addressed to the working group mailing list (aft@socks.nec.com) or to 13 the editor. 15 This document is an Internet-Draft. Internet Drafts are working 16 documents of the Internet Engineering Task Force (IETF), its areas, 17 and its working Groups. Note that other groups may also distribute 18 working documents as Internet Drafts. 20 Internet-Drafts draft documents are valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference 23 material or to cite them other than as "work in progress." 25 To view the entire list of current Internet-Drafts, please check 26 the "1id-abstracts.txt" listing contained in the Internet-Drafts 27 Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net 28 (Northern Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au 29 (Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu 30 (US West Coast). 32 Distribution of this memo is unlimited 34 Acknowledgments 36 This memo describes a protocol that is an evolution of the previous 37 version of the protocol, version 4[SOCKS]. This new protocol stems 38 from active discussions and prototype implementations. The key 39 contributors are: 41 o Marcus Leech: Bell-Northern Research 42 o David Koblas: Independent Consultant 43 o Ying-Da Lee: NEC Systems Laboratory 44 o LaMont Jones: Hewlett-Packard Company 45 o Ron Kuris: Unify Corporation 46 o Matt Ganis: International Business Machines 47 o David Blob: NEC USA 48 o Wei Lu: NEC USA. 49 o William Perry: Aventail 50 o Dave Chouinard: Intel 52 1. Introduction 54 The use of network firewalls, systems that effectively isolate an 55 organizations internal network structure from an exterior network, 56 such as the INTERNET is becoming increasingly popular. These 57 firewall systems typically act as application-layer gateways between 58 networks, usually offering controlled TELNET, FTP, and SMTP access. 59 With the emergence of more sophisticated application layer protocols 60 designed to facilitate global information discovery, there exists a 61 need to provide a general framework for these protocols to 62 transparently and securely traverse a firewall. 64 There exists, also, a need for strong authentication of such 65 traversal in as fine-grained a manner as is practical. This 66 requirement stems from the realization that client-server 67 relationships emerge between the networks of various organizations, 68 and that such relationships need to be controlled and often strongly 69 authenticated. 71 The protocol described here is designed to provide a framework for 72 client-server applications in both the TCP and UDP domains to 73 conveniently and securely use the services of a network firewall. 74 The protocol is conceptually a "shim-layer" between the application 75 layer and the transport layer, and as such does not provide network- 76 layer gateway services, such as forwarding of ICMP messages. 78 2. Existing practice 80 There currently exists a protocol, SOCKS Version 4, that provides for 81 unsecured firewall traversal for TCP-based client-server 82 applications, including TELNET, FTP and the popular information- 83 discovery protocols such as HTTP, WAIS and GOPHER. 85 This new protocol extends the SOCKS Version 4 model to include UDP, 86 and extends the framework to include provisions for generalized 87 strong authentication schemes, and extends the addressing scheme to 88 encompass domain-name and V6 IP addresses. 90 The implementation of the SOCKS protocol typically involves the 91 recompilation or relinking of TCP-based client applications to use 92 the appropriate encapsulation routines in the SOCKS library. 94 Note: 96 Unless otherwise noted, the decimal numbers appearing in packet- 97 format diagrams represent the length of the corresponding field, in 98 octets. Where a given octet must take on a specific value, the 99 syntax X'hh' is used to denote the value of the single octet in that 100 field. When the word 'Variable' is used, it indicates that the 101 corresponding field has a variable length defined either by an 102 associated (one or two octet) length field, or by a data type field. 104 3. Procedure for TCP-based clients 106 When a TCP-based client wishes to establish a connection to an object 107 that is reachable only via a firewall (such determination is left up 108 to the implementation), it must open a TCP connection to the 109 appropriate SOCKS port on the SOCKS server system. The SOCKS service 110 is conventionally located on TCP port 1080. If the connection 111 request succeeds, the client enters a negotiation for the 112 authentication method to be used, authenticates with the chosen 113 method, then sends a relay request. The SOCKS server evaluates the 114 request, and either establishes the appropriate connection or denies 115 it. 117 The client connects to the server, and sends a version 118 identifier/method selection message: 120 +----+----------+----------+ 121 |VER | NMETHODS | METHODS | 122 +----+----------+----------+ 123 | 1 | 1 | 1 to 255 | 124 +----+----------+----------+ 126 The VER field is set to X'05' for this version of the protocol. The 127 NMETHODS field contains the number of method identifier octets that 128 appear in the METHODS field. 130 The server selects from one of the methods given in METHODS, and 131 sends a METHOD selection message: 133 +----+--------+ 134 |VER | METHOD | 135 +----+--------+ 136 | 1 | 1 | 137 +----+--------+ 139 If the selected METHOD is X'FF', none of the methods listed by the 140 client are acceptable, and the client MUST close the connection. 142 The values currently defined for METHOD are: 144 o X'00' NO AUTHENTICATION REQUIRED 145 o X'01' GSSAPI 146 o X'02' USERNAME/PASSWORD 147 o X'03' CHAP 148 o X'04' to X'7F' IANA ASSIGNED 149 o X'80' to X'FE' RESERVED FOR PRIVATE METHODS 150 o X'FF' NO ACCEPTABLE METHODS 152 The client and server then enter a method-specific sub-negotiation. 154 Descriptions of the method-dependent sub-negotiations appear in 155 separate memos. 157 Developers of new METHOD support for this protocol should contact 158 IANA for a METHOD number. The ASSIGNED NUMBERS document should be 159 referred to for a current list of METHOD numbers and their 160 corresponding protocols. 162 Compliant implementations MUST support NO AUTHENTICATION REQUIRED and 163 CHAP, SHOULD support USERNAME/PASSWORD and MAY support GSSAPI 164 authentication methods. 166 As with other TCP application data, out of band data is normally 167 proxied to the SOCKS server as out of band data; note that 168 implementations may be limited to handling a single byte of such data 169 at a time. Authentication methods which define some content 170 encapsulation SHOULD define a method-specific mechanism for proxying 171 out of band data. 173 4. Requests 175 Once the method-dependent subnegotiation has completed, the client 176 sends the request details. If the negotiated method includes 177 encapsulation for purposes of integrity checking and/or 178 confidentiality, these requests MUST be encapsulated in the method- 179 dependent encapsulation. 181 The SOCKS request is formed as follows: 183 +----+-----+------+------+----------+----------+ 184 |VER | CMD | FLAG | ATYP | DST.ADDR | DST.PORT | 185 +----+-----+------+------+----------+----------+ 186 | 1 | 1 | 1 | 1 | Variable | 2 | 187 +----+-----+------+------+----------+----------+ 189 Where: 191 o VER protocol version: X'05' 192 o CMD 193 o CONNECT X'01' 194 o BIND X'02' 195 o UDP ASSOCIATE X'03' 196 o X'04' to X'7F' IANA ASSIGNED 197 o X'80' to X'FF' RESERVED FOR PRIVATE METHODS 198 o FLAG command dependent flag (defaults to X'00') 199 o ATYP address type of following address 200 o IP V4 address: X'01' 201 o DOMAINNAME: X'03' 202 o IP V6 address: X'04' 203 o DST.ADDR desired destination address 204 o DST.PORT desired destination port in network octet 205 order 207 The SOCKS server will typically evaluate the request based on 208 source and destination addresses, and return one or more reply 209 messages, as appropriate for the request type. 211 5. Addressing 213 In an address field (DST.ADDR, BND.ADDR), the ATYP field specifies 214 the type of address contained within the field: 216 o X'01' 218 The address is a version-4 IP address, with a length of 4 octets. 220 o X'03' 222 The address field contains a fully-qualified domain name. The first 223 octet of the address field contains the number of octets of name that 224 follow, there is no terminating NUL octet. 226 o X'04' 228 The address is a version-6 IP address, with a length of 16 octets. 230 6. Replies 232 The SOCKS request information is sent by the client as soon as it has 233 established a connection to the SOCKS server, and completed the 234 authentication negotiations. The server evaluates the request, and 235 returns a reply formed as follows: 237 +----+-----+------+------+----------+----------+ 238 |VER | REP | FLAG | ATYP | BND.ADDR | BND.PORT | 239 +----+-----+------+------+----------+----------+ 240 | 1 | 1 | 1 | 1 | Variable | 2 | 241 +----+-----+------+------+----------+----------+ 243 Where: 245 o VER protocol version: X'05' 246 o REP Reply field: 247 o X'00' succeeded 248 o X'01' general SOCKS server failure 249 o X'02' connection not allowed by ruleset 250 o X'03' Network unreachable 251 o X'04' Host unreachable 252 o X'05' Connection refused 253 o X'06' TTL expired 254 o X'07' Command not supported 255 o X'08' Address type not supported 256 o X'09' Invalid address 257 o X'0A' to X'FF' unassigned 258 o FLAG command dependent flag 259 o ATYP address type of following address 260 o IP V4 address: X'01' 261 o DOMAINNAME: X'03' 262 o IP V6 address: X'04' 263 o BND.ADDR server bound address 264 o BND.PORT server bound port in network octet order 266 If the chosen method includes encapsulation for purposes of 267 authentication, integrity and/or confidentiality, the replies are 268 encapsulated in the method-dependent encapsulation. 270 Reply Processing 272 When a reply indicates a failure (REP value other than X'00',) the 273 SOCKS server MUST terminate the TCP connection shortly after sending 274 the reply. This must be no more than 10 seconds after detecting the 275 condition that caused a failure. 277 If the reply code indicates a success, the client may now start 278 passing data. If the selected authentication method supports 279 encapsulation for the purposes of integrity, authentication and/or 280 confidentiality, the data are encapsulated using the method-dependent 281 encapsulation. Similarly, when data arrives at the SOCKS server for 282 the client, the server MUST encapsulate the data as appropriate for 283 the authentication method in use. 285 7. TCP Procedure 287 CONNECT 289 In the reply to a CONNECT, BND.PORT contains the port number that the 290 server assigned to connect to the target host, and BND.ADDR contains 291 the associated IP address. The supplied BND.ADDR is often different 292 from the IP address that the client uses to reach the SOCKS server, 293 since such servers are often multi-homed. It is expected that the 294 SOCKS server will use DST.ADDR and DST.PORT, and the client-side 295 source address and port in evaluating the CONNECT request. 297 BIND 299 The BIND request is used in protocols which require the client to 300 accept connections from the server. FTP is a well-known example, 301 which uses the primary client-to-server connection for commands and 302 status reports, but may use a server-to-client connection for 303 transferring data on demand (e.g. LS, GET, PUT). 305 It is expected that the client side of an application protocol will 306 use the BIND request only to establish secondary connections after a 307 primary connection is established using CONNECT. DST.ADDR must be 308 the address of the primary connection's destination. DST.PORT should 309 be the requested port (or 0 for a random, unused port). It is 310 expected that a SOCKS server will use DST.ADDR and DST.PORT in 311 evaluating the BIND request. 313 Two replies are sent from the SOCKS server to the client during a 314 BIND operation. The first is sent after the server creates and binds 315 a new socket. The BND.PORT field contains the port number that the 316 SOCKS server assigned to listen for an incoming connection. The 317 BND.ADDR field contains the associated IP address. The client will 318 typically use these pieces of information to notify (via the primary 319 or control connection) the application server of the rendezvous 320 address. The second reply occurs only after the anticipated incoming 321 connection succeeds or fails. 323 In the second reply, the BND.PORT and BND.ADDR fields contain the 324 address and port number of the connecting host. 326 8. UDP procedure 328 UDP ASSOCIATE requests 330 The UDP ASSOCIATE request is used to establish an association within 331 the UDP relay process to handle UDP datagrams. The DST.ADDR and 332 DST.PORT fields contain the address and port that the client expects 333 to use to send UDP datagrams on for the association. The server MAY 334 use this information to limit access to the association. If the 335 client is not in possesion of the information at the time of the UDP 336 ASSOCIATE, the client MUST use address type X'01' with a port number 337 and address of all zeros. 339 A UDP association terminates when the TCP connection that the UDP 340 ASSOCIATE request arrived on terminates. 342 Flag bits in the request and reply are defined as follows: 344 INTERFACE REQUEST X'01' 345 USECLIENTSPORT X'04' 347 If the USECLIENTSPORT bit is set in the flag field of the request, the 348 server SHOULD interact with the application server using the same port 349 the client used in the request, and set the USECLIENTSPORT bit in the 350 flag field of the reply to acknowledge having done so. If no port 351 number was specified in the UDP ASSOCIATE request, this flag is 352 meaningless and MUST not be used. 354 If the INTERFACE REQUEST bit is set in the flag field of the request, 355 the server may indicate its support for this extension by setting this 356 bit in the reply. If both client and server support this feature, the 357 client SHOULD send INTERFACE DATA subcommands, described below, during 358 the UDP association. 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 UDP 362 request messages to be relayed. 364 UDP Control Channel 366 A UDP association terminates when the TCP connection that the UDP 367 ASSOCIATE request arrived on terminates. If the flag negotiation 368 indicated mutual support for it, the client SHOULD send INTERFACE DATA 369 subcommands to learn the external address information for the UDP 370 assocaiation with respect to a particular destination. The server, in 371 turn, MAY use this information to limit access to the association to 372 those destination addresses for which it has received INTERFACE DATA 373 queries; multiple INTERFACE DATA commands are permitted, and have a 374 cumulative effect. 376 Such requests are formatted as follows: 378 +----+-----+------+------+----------+------+ 379 |RSV | SUB | FLAG | ATYP | ADDR | PORT | 380 +----+-----+------+------+----------+------+ 381 | 1 | 1 | 1 | 1 | Variable | 2 | 382 +----+-----+------+------+----------+------+ 384 The fields in the CONTROL CHANNEL packet are: 386 o RSV Reserved X'00' 387 o SUB Subcommand 388 o INTERFACE DATA: X'01' 389 o FLAG A subcommand dependent flag (normally X'00') 390 o ATYP address type of following addresses: 391 o IP V4 address: X'01' 392 o DOMAINNAME: X'03' 393 o IP V6 address: X'04' 394 o ADDR destination address information 395 o PORT destination port information 397 Replies to INTERFACE DATA commands are structured the same way as 398 ordinary SOCKS replies, as per section 6. 400 UDP packet structure 402 A UDP-based client MUST send its datagrams to the UDP relay server at 403 the UDP port indicated by BND.PORT in the reply to the UDP ASSOCIATE 404 request. If the selected authentication method provides 405 encapsulation for the purposes of authenticity, integrity, and/or 406 confidentiality, the datagram MUST be encapsulated using the 407 appropriate encapsulation. Each UDP datagram carries a UDP request 408 header with it: 410 +------+------+------+----------+----------+----------+ 411 | FLAG | FRAG | ATYP | DST.ADDR | DST.PORT | DATA | 412 +------+------+------+----------+----------+----------+ 413 | 2 | 1 | 1 | Variable | 2 | Variable | 414 +------+------+------+----------+----------+----------+ 416 The fields in the UDP request header are: 418 o FLAG Reserved X'0000' 419 o FRAG Current fragment number 420 o ATYP address type of following addresses: 421 o IP V4 address: X'01' 422 o DOMAINNAME: X'03' 423 o IP V6 address: X'04' 424 o DST.ADDR desired destination address 425 o DST.PORT desired destination port 426 o DATA user data 428 FRAG is currently unused, and reserved for future work to deal with 429 fragmentation; it must be set to X'00'. 431 When a UDP relay server decides to relay a UDP datagram, it does so 432 silently, without any notification to the requesting client. 433 Similarly, it will drop datagrams it cannot or will not relay. When 434 a UDP relay server receives a reply datagram from a remote host, it 435 MUST encapsulate that datagram using the above UDP request header, 436 and any authentication-method-dependent encapsulation. 438 The UDP relay server MUST acquire from the SOCKS server the expected 439 IP address of the client that will send datagrams to the BND.PORT 440 given in the reply to UDP ASSOCIATE. It MUST drop any datagrams 441 arriving from any source IP address other than the one recorded for 442 the particular association. 444 The programming interface for a SOCKS-aware UDP MUST report an 445 available buffer space for UDP datagrams that is smaller than the 446 actual space provided by the operating system: 448 o if ATYP is X'01' - 10+method_dependent octets smaller 449 o if ATYP is X'03' - 262+method_dependent octets smaller 450 o if ATYP is X'04' - 20+method_dependent octets smaller 452 9. Security Considerations 454 This document describes a protocol for the application-layer 455 traversal of IP network firewalls. The security of such traversal is 456 highly dependent on the particular authentication and encapsulation 457 methods provided in a particular implementation, and selected during 458 negotiation between SOCKS client and SOCKS server. 460 Careful consideration should be given by the administrator to the 461 selection of authentication methods. 463 10. References 465 [CHAP] VanHeyningen, M., "Challenge-Handshake Authentication 466 Protocol for SOCKS V5," work in progress. 468 [RFC 1928] Leech, M., Ganis, M., Lee, Y., Kuris, R. Koblas, D., & 469 Jones, L., "SOCKS Protocol V5," April 1996. 471 [RFC 1929] Leech, M., "Username/Password Authentication for SOCKS V5," 472 March 1996. 474 [RFC 1961] McMahon, P., "GSS-API Authentication Method for SOCKS 475 Version 5," June 1996. 477 [SOCKS] Koblas, D., "SOCKS", Proceedings: 1992 Usenix Security 478 Symposium. 480 Author's Address 482 Marc VanHeyningen 483 Aventail Corporation 484 808 Howell Streeet; Suite 200 485 Seattle, WA 98101 487 Phone: +1 (206) 215-1111 488 Email: marcvh@aventail.com