idnits 2.17.1 draft-ietf-aft-socks-pro-v5-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. 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 == 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 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 2 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 132: '..., and the client MUST close the connec...' RFC 2119 keyword, line 136: '... o X'00' NO AUTHENTICATION REQUIRED...' RFC 2119 keyword, line 147: '...pport for this protocol SHOULD contact...' RFC 2119 keyword, line 152: '... implementations MUST support NO AUTHE...' RFC 2119 keyword, line 153: '... GSSAPI, and SHOULD support USERNAME...' (20 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 (June 27, 2000) is 8698 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: 'GSSAPI' is defined on line 474, but no explicit reference was found in the text == Unused Reference: 'RFC 1928' is defined on line 477, but no explicit reference was found in the text == Unused Reference: 'RFC 1929' is defined on line 480, but no explicit reference was found in the text == Unused Reference: 'RFC 1961' is defined on line 483, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'GSSAPI' ** Obsolete normative reference: RFC 2478 (Obsoleted by RFC 4178) -- Possible downref: Non-RFC (?) normative reference: ref. 'SOCKS' Summary: 7 errors (**), 0 flaws (~~), 6 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 AFT Working Group Marc VanHeyningen 2 draft-ietf-aft-socks-pro-v5-05.txt Aventail Corp. 3 Expires six months from --> June 27, 2000 5 SOCKS Protocol Version 5 7 Status of this Memo 9 This document is an Internet-Draft and is in full conformance with 10 all provisions of Section 10 of RFC2026. 12 Internet-Drafts are working documents of the Internet Engineering 13 Task Force (IETF), its areas, and its working groups. Note that 14 other groups may also distribute working documents as Internet- 15 Drafts. 17 Internet-Drafts are draft documents valid for a maximum of six 18 months and may be updated, replaced, or obsoleted by other 19 documents at any time. It is inappropriate to use Internet- 20 Drafts as reference material or to cite them other than as "work 21 in progress." 23 The list of current Internet-Drafts can be accessed at 24 http://www.ietf.org/ietf/1id-abstracts.txt 26 The list of Internet-Draft Shadow Directories can be accessed at 27 http://www.ietf.org/shadow.html. 29 This document is a submission to the IETF Authenticated Firewall 30 Traversal (AFT) Working Group. Comments are solicited and should 31 be addressed to the working group mailing list (aft@socks.nec.com) 32 or to the editor. 34 Abstract 36 This document is an update to RFC 1928, the SOCKS version 5 37 protocol. SOCKS is a generic proxying protocol for traversing 38 firewalls and other trust boundaries; version 5 of the protocol 39 adds new features such as authentication and UDP support. Changes 40 from the RFC in this draft include formatting cleanups, 41 authentication clarification, and fixing UDP-related problems 42 found during implementation. 44 1. Introduction 46 The use of network firewalls, systems that effectively isolate an 47 organizations internal network structure from an exterior network, 48 such as the INTERNET is becoming increasingly popular. These 49 firewall systems typically act as application-layer gateways between 50 networks, usually offering controlled TELNET, FTP, and SMTP access. 51 With the emergence of more sophisticated application layer protocols 52 designed to facilitate global information discovery, there exists a 53 need to provide a general framework for these protocols to 54 transparently and securely traverse a firewall. 56 There exists, also, a need for strong authentication of such 57 traversal in as fine-grained a manner as is practical. This 58 requirement stems from the realization that client-server 59 relationships emerge between the networks of various organizations, 60 and that such relationships need to be controlled and often strongly 61 authenticated. 63 The protocol described here is designed to provide a framework for 64 client-server applications in both the TCP and UDP domains to 65 conveniently and securely use the services of a network firewall. 66 The protocol is conceptually a "shim-layer" between the application 67 layer and the transport layer, and as such does not provide network- 68 layer gateway services, such as forwarding of ICMP messages. 70 2. SOCKS history 72 There currently exists a protocol, SOCKS Version 4, that provides for 73 unsecured firewall traversal for TCP-based client-server 74 applications, including TELNET, FTP and the popular information- 75 discovery protocols such as HTTP, WAIS and GOPHER. 77 This new protocol extends the SOCKS Version 4 model to include UDP, 78 and extends the framework to include provisions for generalized 79 strong authentication schemes, and extends the addressing scheme to 80 encompass domain-name and V6 IP addresses. 82 The implementation of the SOCKS protocol typically involves the 83 recompilation or relinking of TCP-based client applications to use 84 the appropriate encapsulation routines in the SOCKS library. 86 3. Connection and authentication negotiation 88 When a TCP-based client wishes to establish a connection to an object 89 that is reachable only via a firewall (such determination is left up 90 to the implementation), it must open a TCP connection to the 91 appropriate SOCKS port on the SOCKS server system. The SOCKS service 92 is conventionally located on TCP port 1080. If the connection 93 request succeeds, the client enters a negotiation for the 94 authentication method to be used, authenticates with the chosen 95 method, then sends a relay request. The SOCKS server evaluates the 96 request, and either establishes the appropriate connection or denies 97 it. 99 Note: 100 Unless otherwise noted, the decimal numbers appearing in packet- 101 format diagrams represent the length of the corresponding field, 102 in octets. Where a given octet must take on a specific value, the 103 syntax X'hh' is used to denote the value of the single octet in 104 that field. When the word 'Variable' is used, it indicates that 105 the corresponding field has a variable length defined either by an 106 associated (one or two octet) length field, or by a data type 107 field. 109 The client connects to the server, and sends a version 110 identifier/method selection message: 112 +----+----------+----------+ 113 |VER | NMETHODS | METHODS | 114 +----+----------+----------+ 115 | 1 | 1 | 1 to 255 | 116 +----+----------+----------+ 118 The VER field is set to X'05' for this version of the protocol. The 119 NMETHODS field contains the number of method identifier octets that 120 appear in the METHODS field. 122 The server selects from one of the methods given in METHODS, and 123 sends a METHOD selection message: 125 +----+--------+ 126 |VER | METHOD | 127 +----+--------+ 128 | 1 | 1 | 129 +----+--------+ 131 If the selected METHOD is X'FF', none of the methods listed by the 132 client are acceptable, and the client MUST close the connection. 134 The values currently defined for METHOD are: 136 o X'00' NO AUTHENTICATION REQUIRED 137 o X'01' GSSAPI 138 o X'02' USERNAME/PASSWORD 139 o X'03' to X'7F' IANA ASSIGNED 140 o X'80' to X'FE' RESERVED FOR PRIVATE METHODS 141 o X'FF' NO ACCEPTABLE METHODS 143 After agreeing on the authentication method, the client and server 144 then enter a method-specific sub-negotiation. Descriptions of the 145 method-dependent sub-negotiations appear in separate memos. 147 Developers of new METHOD support for this protocol SHOULD contact 148 IANA for a METHOD number. The ASSIGNED NUMBERS document may be 149 referred to for a current list of METHOD numbers and their 150 corresponding protocols. 152 Compliant implementations MUST support NO AUTHENTICATION REQUIRED and 153 GSSAPI, and SHOULD support USERNAME/PASSWORD. To assure secure 154 interoperability among multiple GSSAPI implementations, the 155 LIPKEY[RFC 2847] mechanism MUST be supported, and mechanism 156 negotiation using SPNEGO[RFC 2478] MUST be supported. 158 4. SOCKS Requests 160 Once the method-dependent subnegotiation has completed, the client 161 sends the request details. If the negotiated method includes 162 encapsulation for purposes of integrity checking and/or 163 confidentiality, these requests MUST be encapsulated in the method- 164 dependent encapsulation. 166 The SOCKS request is formed as follows: 168 +----+-----+------+------+----------+----------+ 169 |VER | CMD | FLAG | ATYP | DST.ADDR | DST.PORT | 170 +----+-----+------+------+----------+----------+ 171 | 1 | 1 | 1 | 1 | Variable | 2 | 172 +----+-----+------+------+----------+----------+ 174 Where: 176 o VER protocol version: X'05' 177 o CMD 178 o CONNECT X'01' 179 o BIND X'02' 180 o UDP ASSOCIATE X'03' 181 o IANA Reserved X'04' to X'7F' 182 o Private methods X'80' to X'FF' 183 o FLAG command dependent flag (defaults to X'00') 184 o ATYP address type of following address 185 o IP V4 address X'01' 186 o DOMAINNAME X'03' 187 o IP V6 address X'04' 189 o DST.ADDR desired destination address 190 o DST.PORT desired destination port (network octet order) 192 The SOCKS server will typically evaluate the request based on source 193 and destination addresses, and return one or more reply messages, as 194 appropriate for the request type. 196 5. Addressing 198 In an address field (DST.ADDR, BND.ADDR), the ATYP field specifies 199 the type of address contained within the field: 201 o X'01' 203 The address is a version-4 IP address, with a length of 4 octets. 205 o X'03' 207 The address field contains a fully-qualified domain name. The 208 first octet of the address field contains the number of octets of 209 name that follow, there is no terminating NUL octet. 211 o X'04' 213 The address is a version-6 IP address, with a length of 16 octets. 215 6. SOCKS Replies 217 The SOCKS request information is sent by the client as soon as it has 218 established a connection to the SOCKS server, and completed the 219 authentication negotiations. The server evaluates the request, and 220 returns a reply formed as follows: 222 +----+-----+------+------+----------+----------+ 223 |VER | REP | FLAG | ATYP | BND.ADDR | BND.PORT | 224 +----+-----+------+------+----------+----------+ 225 | 1 | 1 | 1 | 1 | Variable | 2 | 226 +----+-----+------+------+----------+----------+ 228 Where: 230 o VER protocol version: X'05' 231 o REP Reply field: 232 o X'00' succeeded 233 o X'01' general SOCKS server failure 234 o X'02' connection not allowed by ruleset 235 o X'03' Network unreachable 236 o X'04' Host unreachable 237 o X'05' Connection refused 238 o X'06' TTL expired 239 o X'07' Command not supported 240 o X'08' Address type not supported 241 o X'09' Invalid address 242 o X'0A' to X'FF' unassigned 243 o FLAG command dependent flag 244 o ATYP address type of following address 245 o IP V4 address: X'01' 246 o DOMAINNAME: X'03' 247 o IP V6 address: X'04' 248 o BND.ADDR server bound address 249 o BND.PORT server bound port (network octet order) 251 If the chosen method includes encapsulation for purposes of 252 authentication, integrity and/or confidentiality, the replies are 253 encapsulated in the method-dependent encapsulation. 255 When a reply indicates a failure (REP value other than X'00',) the 256 SOCKS server MUST terminate the TCP connection shortly after sending 257 the reply. This must be no more than 10 seconds after detecting the 258 condition that caused a failure. 260 If the reply code indicates a success, the client may now start 261 passing data. If the selected authentication method supports 262 encapsulation for the purposes of integrity, authentication and/or 263 confidentiality, the data are encapsulated using the method-dependent 264 encapsulation. Similarly, when data arrives at the SOCKS server for 265 the client, the server MUST encapsulate the data as appropriate for 266 the authentication method in use. 268 7. TCP Procedure 270 7.1. CONNECT 272 In the reply to a CONNECT, BND.PORT contains the port number that the 273 server assigned to connect to the target host, and BND.ADDR contains 274 the associated IP address. The supplied BND.ADDR is often different 275 from the IP address that the client uses to reach the SOCKS server, 276 since such servers are often multi-homed. It is expected that the 277 SOCKS server will use DST.ADDR and DST.PORT, and the client-side 278 source address and port in evaluating the CONNECT request. 280 7.2. BIND 281 The BIND request is used in protocols which require the client to 282 accept connections from the server. FTP is a well-known example, 283 which uses the primary client-to-server connection for commands and 284 status reports, but may use a server-to-client connection for 285 transferring data on demand (e.g. LS, GET, PUT). 287 It is expected that the client side of an application protocol will 288 use the BIND request only to establish secondary connections after a 289 primary connection is established using CONNECT. DST.ADDR contains 290 the address of the primary connection's destination. DST.PORT 291 contains the requested port (or 0 for a random, unused port). It is 292 expected that a SOCKS server will use DST.ADDR and DST.PORT in 293 evaluating the BIND request. 295 Two replies are sent from the SOCKS server to the client during a 296 BIND operation. The first is sent after the server creates and binds 297 a new socket. The BND.PORT field contains the port number that the 298 SOCKS server assigned to listen for an incoming connection. The 299 BND.ADDR field contains the associated IP address. The client will 300 typically use these pieces of information to notify (via the primary 301 or control connection) the application server of the rendezvous 302 address. The second reply occurs only after the anticipated incoming 303 connection succeeds or fails. 305 In the second reply, the BND.PORT and BND.ADDR fields contain the 306 address and port number of the connecting host. 308 Note: out-of-band data 309 As with other TCP application data, out of band data is normally 310 proxied to the SOCKS server as out of band data; note that 311 implementations may be limited to handling a single byte of such 312 data at a time. Authentication methods which define some content 313 encapsulation SHOULD define a method-specific mechanism for 314 proxying out of band data. 316 8. UDP procedure 318 8.1. UDP ASSOCIATE requests 320 The UDP ASSOCIATE request is used to establish an association within 321 the UDP relay process to handle UDP datagrams. The DST.ADDR and 322 DST.PORT fields contain the address and port that the client expects 323 to use to send UDP datagrams on for the association. The server MAY 324 use this information to limit access to the association. If the 325 client is not in possesion of the information at the time of the UDP 326 ASSOCIATE, the client MUST use address type X'01' with a port number 327 and address of all zeros. 329 A UDP association terminates when the TCP connection that the UDP 330 ASSOCIATE request arrived on terminates. 332 Flag bits in the request and reply are defined as follows: 334 o INTERFACE REQUEST X'01' 335 o USECLIENTSPORT X'04' 337 If the USECLIENTSPORT bit is set in the flag field of the request, 338 the server SHOULD interact with the application server using the same 339 port the client used in the request, and set the USECLIENTSPORT bit 340 in the flag field of the reply to acknowledge having done so. If no 341 port number was specified in the UDP ASSOCIATE request, this flag is 342 meaningless and MUST not be used. 344 If the INTERFACE REQUEST bit is set in the flag field of the request, 345 the server may indicate its support for this extension by setting 346 this bit in the reply. If both client and server support this 347 feature, the client SHOULD send INTERFACE DATA subcommands, described 348 below, during the UDP association. 350 In the reply to a UDP ASSOCIATE request, the BND.PORT and BND.ADDR 351 fields indicate the port number/address where the client MUST send 352 UDP request messages to be relayed. 354 8.2. UDP Control Channel 356 A UDP association terminates when the TCP connection that the UDP 357 ASSOCIATE request arrived on terminates. If the flag negotiation 358 indicated mutual support for it, the client SHOULD send INTERFACE 359 DATA subcommands to learn the external address information for the 360 UDP assocaiation with respect to a particular destination. The 361 server, in turn, MAY use this information to limit access to the 362 association to those destination addresses for which it has received 363 INTERFACE DATA queries; multiple INTERFACE DATA commands are 364 permitted, and have a cumulative effect. 366 Such requests are formatted as follows: 368 +----+-----+------+------+----------+------+ 369 |RSV | SUB | FLAG | ATYP | ADDR | PORT | 370 +----+-----+------+------+----------+------+ 371 | 1 | 1 | 1 | 1 | Variable | 2 | 372 +----+-----+------+------+----------+------+ 374 The fields in the CONTROL CHANNEL packet are: 376 o RSV Reserved X'00' 377 o SUB Subcommand 378 o INTERFACE DATA: X'01' 379 o FLAG subcommand dependent flag (normally X'00') 380 o ATYP address type of following addresses: 381 o IP V4 address: X'01' 382 o DOMAINNAME: X'03' 383 o IP V6 address: X'04' 384 o ADDR destination address information 385 o PORT destination port information (network octet order) 387 Replies to INTERFACE DATA commands are structured the same way as 388 ordinary SOCKS replies, as per section 6. 390 8.3. UDP packet structure 392 A UDP-based client MUST send its datagrams to the UDP relay server at 393 the UDP port indicated by BND.PORT in the reply to the UDP ASSOCIATE 394 request. If the selected authentication method provides 395 encapsulation for the purposes of authenticity, integrity, and/or 396 confidentiality, the datagram MUST be encapsulated using the 397 appropriate encapsulation. Each UDP datagram carries a UDP request 398 header with it: 400 +------+------+------+----------+----------+----------+ 401 | FLAG | FRAG | ATYP | DST.ADDR | DST.PORT | DATA | 402 +------+------+------+----------+----------+----------+ 403 | 2 | 1 | 1 | Variable | 2 | Variable | 404 +------+------+------+----------+----------+----------+ 406 The fields in the UDP request header are: 408 o FLAG Reserved (currently X'0000') 409 o FRAG Current fragment number 410 o ATYP address type of following addresses: 411 o IP V4 address: X'01' 412 o DOMAINNAME: X'03' 413 o IP V6 address: X'04' 414 o DST.ADDR desired destination address 415 o DST.PORT desired destination port (network octet order) 416 o DATA user payload data 418 FRAG is currently unused, and reserved for future work to deal with 419 fragmentation; it must be set to X'00'. 421 When a UDP relay server decides to relay a UDP datagram, it does so 422 silently, without any notification to the requesting client. 424 Similarly, it will drop datagrams it cannot or will not relay. When 425 a UDP relay server receives a reply datagram from a remote host, it 426 MUST encapsulate that datagram using the above UDP request header, 427 and any authentication-method-dependent encapsulation. 429 The UDP relay server MUST acquire from the SOCKS server the expected 430 IP address of the client that will send datagrams to the BND.PORT 431 given in the reply to UDP ASSOCIATE. It MUST drop any datagrams 432 arriving from any source IP address other than the one recorded for 433 the particular association. 435 The programming interface for a SOCKS-aware UDP MUST report an 436 available buffer space for UDP datagrams that is smaller than the 437 actual space provided by the operating system: 439 o if ATYP is X'01' - 10+method_dependent octets smaller 440 o if ATYP is X'03' - 262+method_dependent octets smaller 441 o if ATYP is X'04' - 20+method_dependent octets smaller 443 9. Security Considerations 445 This document describes a protocol for the application-layer 446 traversal of IP network firewalls. The security of such traversal is 447 highly dependent on the particular authentication and encapsulation 448 methods provided in a particular implementation, and selected during 449 negotiation between SOCKS client and SOCKS server. 451 Careful consideration should be given by the administrator to the 452 selection of authentication methods. 454 10. Acknowledgments 456 This memo describes a protocol that is an evolution of the previous 457 version of the protocol, version 4[SOCKS]. This new protocol stems 458 from active discussions and prototype implementations. The key 459 contributors are: 461 o Marcus Leech: Bell-Northern Research 462 o David Koblas: Independent Consultant 463 o Ying-Da Lee: NEC Systems Laboratory 464 o LaMont Jones: Hewlett-Packard Company 465 o Ron Kuris: Unify Corporation 466 o Matt Ganis: International Business Machines 467 o David Blob: NEC USA 468 o Wei Lu: NEC USA. 469 o William Perry: Aventail 470 o Dave Chouinard: Intel 472 11. References 474 [GSSAPI] Margrave, D., "GSS-API Authentication Method for SOCKS 475 Version 5," work in progress. 477 [RFC 1928] Leech, M., Ganis, M., Lee, Y., Kuris, R. Koblas, D., & 478 Jones, L., "SOCKS Protocol V5," RFC 1928, April 1996. 480 [RFC 1929] Leech, M., "Username/Password Authentication for SOCKS V5," 481 RFC 1929, March 1996. 483 [RFC 1961] McMahon, P., "GSS-API Authentication Method for SOCKS 484 Version 5," RFC 1961, June 1996. 486 [RFC 2478] Baize, E. and Pinkas, D., "The Simple and Protected GSS-API 487 Negotiation Mechanism," RFC 2478, December 1998. 489 [RFC 2847] Eisler, M., "LIPKEY - A Low Infrastructure Public Key 490 Mechanism Using SPKM," RFC 2847, June 2000. 492 [SOCKS] Koblas, D., "SOCKS", Proceedings: 1992 Usenix Security 493 Symposium. 495 Author's Address 497 Marc VanHeyningen 498 Aventail Corporation 499 808 Howell Streeet; Suite 200 500 Seattle, WA 98101 USA 502 Phone: +1 (206) 215-1111 503 Email: marcvh@aventail.com