idnits 2.17.1 draft-ietf-aft-socks-protocol-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-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 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 7 instances of too long lines in the document, the longest one being 8 characters 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 123: '... MUST close the connection....' RFC 2119 keyword, line 127: '... o X'00' NO AUTHENTICATION REQUIRED...' RFC 2119 keyword, line 147: '... implementations MUST support GSSAPI a...' RFC 2119 keyword, line 148: '... SHOULD support USERNAME/PASSWORD ...' RFC 2119 keyword, line 157: '... requests MUST be encapsulated in ...' (14 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The "Author's Address" (or "Authors' Addresses") section title is misspelled. -- 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.) -- Couldn't find a document date in the document -- date freshness check skipped. 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: 11 errors (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Socks Protocol Version 5 3 INTERNET-DRAFT 4 Expires: In Six Months M. Leech 5 M. Ganis 6 Y. Lee 7 R. Kuris 8 D. Koblas 9 L. Jones 11 SOCKS Protocol Version 5 13 Status of this Memo 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 are draft document valid for a maximum of six 21 months and may be updated, replaced or obsoleted by other documents 22 at any time. It is inappropriate to use Internet-Drafts as 23 reference material or to cite them other than as "work in 24 progress". 26 To learn the current status of any Internet-Draft, please check the 27 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 28 Directories on ds.internic.net (US East Coast), nic.nordu.net 29 (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific 30 Rim). 32 Acknowledgments 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 36 from active discussions and prototype implementations. The key 37 contributors are: Marcus Leech: Bell-Northern Research, David 38 Koblas: Independent Consultant, Ying-Da Lee: NEC Systems 39 Laboratory, LaMont Jones: Hewlett-Packard Company, Ron Kuris: Unify 40 Corporation, Matt Ganis: International Business Machines. 42 1. Introduction 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 48 between networks, usually offering controlled TELNET, FTP, and SMTP 49 access. With the emergence of more sophisticated application layer 50 protocols designed to facilitate global information discovery, 51 there exists a need to provide a general framework for these 52 protocols to transparently and securely traverse a firewall. 54 There exists, also, a need for strong authentication of such 55 traversal in as fine-grained a manner as is practical. This 56 requirement stems from the realization that client-server 57 relationships emerge between the networks of various organizations, 58 and that such relationships need to be controlled and often 59 strongly authenticated. 61 The protocol described here is designed to provide a framework for 62 client-server applications in both the TCP and UDP domains to 63 conveniently and securely use the services of a network firewall. 64 The protocol is conceptually a "shim-layer" between the application 65 layer and the transport layer, and as such does not provide 66 network-layer gateway services, such as forwarding of ICMP 67 messages. 69 2. Existing practice 71 There currently exists a protocol, SOCKS Version 4, that provides 72 for unsecured firewall traversal for TCP-based client-server 73 applications, including TELNET, FTP and the popular information- 74 discovery protocols such as HTTP, WAIS and GOPHER. 76 This new protocol extends the SOCKS Version 4 model to include UDP, 77 and extends the framework to include provisions for generalized 78 strong authentication schemes, and extends the addressing scheme to 79 encompass domain-name and V6 IP addresses. 81 The implementation of the SOCKS protocol typically involves the 82 recompilation or relinking of TCP-based client applications to use 83 the appropriate encapsulation routines in the SOCKS library. 85 3. Procedure for TCP-based clients 87 When a TCP-based client wishes to establish a connection to an 88 object that is reachable only via a firewall (such determination is 89 left up to the implementation), it must open a TCP connection to 90 the appropriate SOCKS port on the SOCKS server system. The SOCKS 91 service is conventionally located on TCP port 1080. If the 92 connection request succeeds, the client enters a negotiation for 93 the authentication method to be used, authenticates with the chosen 94 method, then sends a relay request. The SOCKS server evaluates the 95 request, and either establishes the appropriate connection or 96 denies it. 98 The client connects to the server, and sends a version 99 identifier/method selection message: 101 +----+----------+----------+ 102 |VER | NMETHODS | METHODS | 103 +----+----------+----------+ 104 | 1 | 1 | 1 to 255 | 105 +----+----------+----------+ 107 The VER field is set to X'05' for this version of the 108 protocol. The NMETHODS field contains the number of 109 method identifier octets that appear in the METHODS 110 field. 112 The server selects from one of the methods given in 113 METHODS, and sends a METHOD selection message: 115 +----+--------+ 116 |VER | METHOD | 117 +----+--------+ 118 | 1 | 1 | 119 +----+--------+ 121 If the selected METHOD is X'FF', none of the methods 122 listed by the client are acceptable, and the client 123 MUST close the connection. 125 The values currently defined for METHOD are: 127 o X'00' NO AUTHENTICATION REQUIRED 128 o X'01' GSSAPI 129 o X'02' USERNAME/PASSWORD 131 o X'03' to X'7F' IANA ASSIGNED 133 o X'80' to X'FE' RESERVED FOR PRIVATE METHODS 135 o X'FF' NO ACCEPTABLE METHODS 137 The client and server then enter a method-specific sub- 138 negotiation. Descriptions of the method-dependent sub- 139 negotiations appear in separate drafts. 141 Developers of new METHOD support for this protocol 142 should contact IANA for a METHOD number. The ASSIGNED 143 NUMBERS document should be referred to for a current 144 list of METHOD numbers and their corresponding proto- 145 cols. 147 Compliant implementations MUST support GSSAPI and 148 SHOULD support USERNAME/PASSWORD authentication meth- 149 ods. 151 4. Requests 153 Once the method-dependent subnegotiation has completed, 154 the client sends the request details. If the negoti- 155 ated method includes encapsulation for purposes of 156 integrity checking and/or confidentiality, these 157 requests MUST be encapsulated in the method-dependent 158 encapsulation. 160 The SOCKS request is formed as follows: 162 +----+-----+-------+------+----------+----------+ 163 |VER | CMD | RSV | ATYP | DST.ADDR | DST.PORT | 164 +----+-----+-------+------+----------+----------+ 165 | 1 | 1 | X'00' | 1 | Variable | 2 | 166 +----+-----+-------+------+----------+----------+ 168 Where: 170 o VER protocol version: X'05' 171 o CMD 172 o CONNECT X'01' 173 o BIND X'02' 174 o UDP ASSOCIATE X'03' 175 o UDP DESTROY X'04' 176 o RSV RESERVED 177 o ATYP address type of following address 178 o IP V4 address: X'01' 179 o DOMAINNAME: X'03' 180 o IP V6 address: X'04' 181 o DST.ADDR desired destination address 182 o DST.PORT desired destination port in network octet order 184 The SOCKS server will typically evaluate the request 185 based on source and destination addresses, and return 186 one or more reply messages, as appropriate for the 187 request type. 189 5. Addressing 191 In an address field (DST.ADDR, BND.ADDR), the ATYP 192 field specifies the type of address contained within 193 the field: 195 o X'01' 197 the address is a version-4 IP address, with a length of 198 4 octets 200 o X'03' 202 the address field contains a DNS-style domain name. 203 The first octet of the address field contains the num- 204 ber of octets that follow. 206 o X'04' 208 the address is a version-6 IP address, with a length of 209 16 octets. 211 6. Replies 213 The SOCKS request information is sent by the client as 214 soon as it has established a connection to the SOCKS 215 server, and completed the authentication negotiations. 216 The server evaluates the request, and returns a reply 217 formed as follows: 219 +----+-----+-------+------+----------+----------+ 220 |VER | REP | RSV | ATYP | BND.ADDR | BND.PORT | 221 +----+-----+-------+------+----------+----------+ 222 | 1 | 1 | X'00' | 1 | Variable | 2 | 223 +----+-----+-------+------+----------+----------+ 225 Where: 227 o VER protocol version: X'05' 228 o REP Reply field: 229 o X'00' succeeded 230 o X'01' general SOCKS server failure 231 o X'02' connection not allowed by ruleset 232 o X'03' Network unreachable 233 o X'04' Host unreachable 234 o X'05' Connection refused 235 o X'06' TTL expired 236 o X'07' Command not supported 237 o X'08' Address type not supported 238 o X'09' to X'FF' unassigned 239 o RSV RESERVED 240 o ATYP address type of following address 241 o IP V4 address: X'01' 242 o DOMAINNAME: X'03' 243 o IP V6 address: X'04' 244 o BND.ADDR server bound address 245 o BND.PORT server bound port in network octet order 247 Fields marked RESERVED (RSV) must be set to X'00'. 249 If the chosen method includes encapsulation for pur- 250 poses of authentication, integrity and/or confidential- 251 ity, the replies are encapsulated in the method- 252 dependent encapsulation. 254 CONNECT 256 In the reply to a CONNECT, BND.PORT contains the port 257 number that the server assigned to connect to the tar- 258 get host, while BND.ADDR contains the associated IP 259 address. The supplied BND.ADDR is often different from 260 the IP address that the client uses to reach the SOCKS 261 server, since such servers are often multi-homed. It 262 is expected that the SOCKS server will use DST.ADDR and 263 DST.PORT, and the client-side source address and port 264 in evaluating the CONNECT request. 266 BIND 268 The BIND request is used in protocols which require the 269 client to accept connections from the server. FTP is a 270 well-known example, which uses the primary client-to- 271 server connection for commands and status reports, but 272 may use a server-to-client connection for transferring 273 data on demand (e.g. LS, GET, PUT). 275 It is expected that the client side of an application 276 protocol will use the BIND request only to establish 277 secondary connections after a primary connection is 278 established using CONNECT. In is expected that a SOCKS 279 server will use DST.ADDR and DST.PORT in evaluating the 280 BIND request. 282 Two replies are sent from the SOCKS server to the 283 client during a BIND operation. The first is sent 284 after the server creates and binds a new socket. The 285 BND.PORT field contains the port number that the SOCKS 286 server assigned to listen for an incoming connection. 287 The BND.ADDR field contains the associated IP address. 288 The client will typically use these pieces of informa- 289 tion to notify (via the primary or control connection) 290 the application server of the rendezvous address. The 291 second reply occurs only after the anticipated incoming 292 connection succeeds or fails. 294 In the second reply, the BND.PORT and BND.ADDR fields 295 contain the address and port number of the connecting 296 host. 298 UDP ASSOCIATE 300 The UDP ASSOCIATE request is used to establish an asso- 301 ciation within the UDP relay process to handle UDP 302 datagrams. The DST.ADDR field is ignored in a UDP 303 ASSOCIATE request, while the DST.PORT field contains 304 the idle-timeout time, in minutes, that an association 305 is allowed to exist without explicit client-side activ- 306 ity. If DST.PORT is zero, the SOCKS server SHOULD use 307 an administrator-defined default. 309 In the reply to a UDP ASSOCIATE request, the BND.PORT 310 and BND.ADDR fields indicate the port number/address 311 where the client may send UDP request messages to be 312 relayed. Once a UDP ASSOCIATE request has been pro- 313 cessed, the SOCKS client MUST terminate the connection. 315 UDP DESTROY 317 The UDP DESTROY request is used to destroy an existing 318 association within the UDP relay process. The DST.ADDR 319 and DST.PORT fields contain the address and port number 320 of the UDP relay process corresponding to the associa- 321 tion to destroy. Once a UDP ASSOCIATE request has been 322 processed, the SOCKS client MUST terminate the connec- 323 tion. 325 Reply Processing 327 When a reply (REP value other than X'00') indicates a 328 failure, the SOCKS server MUST terminate the TCP con- 329 nection shortly after sending the reply. This must be 330 no more than 10 seconds after detecting the condition 331 that caused a failure. 333 If the reply code (REP value of X'00') indicates a suc- 334 cess, and the request was either a BIND or a CONNECT, 335 the client may now start passing data. If the selected 336 authentication method supports encapsulation for the 337 purposes of integrity, authentication and/or confiden- 338 tiality, the data are encapsulated using the method- 339 dependent encapsulation. Similarly, when data arrives 340 at the SOCKS server for the client, the server MUST 341 encapsulate the data as appropriate for the authentica- 342 tion method in use. 344 7. Procedure for UDP-based clients 346 A UDP-based client MUST send its datagrams to the UDP 347 relay server at the UDP port indicated by BND.PORT in 348 the reply to the UDP ASSOCIATE request. If the 349 selected authentication method provides encapsulation 350 for the purposes of authenticity, integrity, and/or 351 confidentiality, the datagram MUST be encapsulated 352 using the appropriate encapsulation. Each UDP datagram 353 carries a UDP request header with it: 355 +----+------+------+----------+----------+----------+ 356 |RSV | FRAG | ATYP | DST.ADDR | DST.PORT | DATA | 357 +----+------+------+----------+----------+----------+ 358 | 2 | 1 | 1 | Variable | 2 | Variable | 359 +----+------+------+----------+----------+----------+ 361 The fields in the UDP request header are: 363 o RSV Reserved X'0000' 364 o FRAG Current fragment number 365 o ATYP address type of following addresses: 366 o IP V4 address: X'01' 367 o DOMAINNAME: X'03' 368 o IP V6 address: X'04' 369 o DST.ADDR desired destination address 370 o DST.PORT desired destination port 371 o DATA user data 373 When a UDP relay server decides to relay a UDP data- 374 gram, it does so silently, without any notification to 375 the requesting client. Similarly, it will drop data- 376 grams it cannot or will not relay. When a UDP relay 377 server receives a reply datagram from a remote host, it 378 MUST encapsulate that datagram using the above UDP 379 request header, and any authentication-method-dependent 380 encapsulation. 382 The UDP relay server MUST acquire from the SOCKS server 383 the expected IP address of the client that will send 384 datagrams to the BND.PORT given in the reply to UDP 385 ASSOCIATE. It MUST drop any datagrams arriving from 386 any source IP address other than the one recorded for 387 the particular association. 389 The FRAG field indicates whether or not this datagram 390 is one of a number of fragments. If implemented, the 391 high-order bit indicates end-of-fragment sequence, 392 while a value of X'00' indicates that this datagram is 393 standalone. Values between 1 and 127 indicate the 394 fragment position within a fragment sequence. Each 395 receiver will have a REASSEMBLY QUEUE and a REASSEMBLY 396 TIMER associated with these fragments. The reassembly 397 queue must be reinitialized and the associated frag- 398 ments abandoned whenever the REASSEMBLY TIMER expires, 399 or a new datagram arrives carrying a FRAG field whose 400 value is less than the highest FRAG value processed for 401 this fragment sequence. The reassembly timer MUST be 402 no less than 5 seconds. It is recommended that frag- 403 mentation be avoided by applications wherever possible. 405 Implementation of fragmentation is optional; an imple- 406 mentation that does not support fragmentation MUST drop 407 any datagram whose FRAG field is other than X'00'. 409 The programming interface for a SOCKS-aware UDP MUST 410 report an available buffer space for UDP datagrams that 411 is smaller than the actual space provided by the oper- 412 ating system: 414 o if ATYP is X'01' - 10+method_dependent octets smaller 415 o if ATYP is X'03' - 262+method_dependent octets smaller 416 o if ATYP is X'04' - 20+method_dependent octets smaller 418 The ASSOCIATION established with a UDP ASSOCIATE 419 request has a specific lifetime. The UDP server SHOULD 420 refresh the lifetime every time a valid datagram 421 arrives from the client at the UDP relay server. 423 8. Security Considerations 425 This document describes a protocol for the application- 426 layer traversal of IP network firewalls. The security 427 of such traversal is highly dependent on the particular 428 authentication and encapsulation methods provided in a 429 particular implementation, and selected during negotia- 430 tion between SOCKS client and SOCKS server. 432 Careful consideration should be given by the adminis- 433 trator to the selection of authentication methods. 435 9. References 437 [1] Koblas, D., "SOCKS", Proceedings: 1992 Usenix Secu- 438 rity Symposium 440 Authors Address 442 Marcus Leech 443 Bell-Northern Research 444 P.O. Box 3511, Stn. C, 445 Ottawa, ON 446 CANADA K1Y 4H7 448 Email: mleech@bnr.ca 449 Phone: (613) 763-9145