idnits 2.17.1 draft-ietf-aft-socks-protocol-v5-05.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-18) 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 ...' (13 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 RSV RESERVED 176 o ATYP address type of following address 177 o IP V4 address: X'01' 178 o DOMAINNAME: X'03' 179 o IP V6 address: X'04' 180 o DST.ADDR desired destination address 181 o DST.PORT desired destination port in network octet order 183 The SOCKS server will typically evaluate the request 184 based on source and destination addresses, and return 185 one or more reply messages, as appropriate for the 186 request type. 188 5. Addressing 189 In an address field (DST.ADDR, BND.ADDR), the ATYP 190 field specifies the type of address contained within 191 the field: 193 o X'01' 195 the address is a version-4 IP address, with a length of 196 4 octets 198 o X'03' 200 the address field contains a fully-qualified domain 201 name. The first octet of the address field contains 202 the number of octets of name that follow, there is no 203 terminating NUL octet. 205 o X'04' 207 the address is a version-6 IP address, with a length of 208 16 octets. 210 6. Replies 212 The SOCKS request information is sent by the client as 213 soon as it has established a connection to the SOCKS 214 server, and completed the authentication negotiations. 215 The server evaluates the request, and returns a reply 216 formed as follows: 218 +----+-----+-------+------+----------+----------+ 219 |VER | REP | RSV | ATYP | BND.ADDR | BND.PORT | 220 +----+-----+-------+------+----------+----------+ 221 | 1 | 1 | X'00' | 1 | Variable | 2 | 222 +----+-----+-------+------+----------+----------+ 224 Where: 226 o VER protocol version: X'05' 227 o REP Reply field: 228 o X'00' succeeded 229 o X'01' general SOCKS server failure 230 o X'02' connection not allowed by ruleset 231 o X'03' Network unreachable 232 o X'04' Host unreachable 233 o X'05' Connection refused 234 o X'06' TTL expired 235 o X'07' Command not supported 236 o X'08' Address type not supported 237 o X'09' to X'FF' unassigned 238 o RSV RESERVED 239 o ATYP address type of following address 240 o IP V4 address: X'01' 241 o DOMAINNAME: X'03' 242 o IP V6 address: X'04' 243 o BND.ADDR server bound address 244 o BND.PORT server bound port in network octet order 246 Fields marked RESERVED (RSV) must be set to X'00'. 248 If the chosen method includes encapsulation for pur- 249 poses of authentication, integrity and/or confidential- 250 ity, the replies are encapsulated in the method- 251 dependent encapsulation. 253 CONNECT 255 In the reply to a CONNECT, BND.PORT contains the port 256 number that the server assigned to connect to the tar- 257 get host, while BND.ADDR contains the associated IP 258 address. The supplied BND.ADDR is often different from 259 the IP address that the client uses to reach the SOCKS 260 server, since such servers are often multi-homed. It 261 is expected that the SOCKS server will use DST.ADDR and 262 DST.PORT, and the client-side source address and port 263 in evaluating the CONNECT request. 265 BIND 267 The BIND request is used in protocols which require the 268 client to accept connections from the server. FTP is a 269 well-known example, which uses the primary client-to- 270 server connection for commands and status reports, but 271 may use a server-to-client connection for transferring 272 data on demand (e.g. LS, GET, PUT). 274 It is expected that the client side of an application 275 protocol will use the BIND request only to establish 276 secondary connections after a primary connection is 277 established using CONNECT. In is expected that a SOCKS 278 server will use DST.ADDR and DST.PORT in evaluating the 279 BIND request. 281 Two replies are sent from the SOCKS server to the 282 client during a BIND operation. The first is sent 283 after the server creates and binds a new socket. The 284 BND.PORT field contains the port number that the SOCKS 285 server assigned to listen for an incoming connection. 286 The BND.ADDR field contains the associated IP address. 287 The client will typically use these pieces of informa- 288 tion to notify (via the primary or control connection) 289 the application server of the rendezvous address. The 290 second reply occurs only after the anticipated incoming 291 connection succeeds or fails. 293 In the second reply, the BND.PORT and BND.ADDR fields 294 contain the address and port number of the connecting 295 host. 297 UDP ASSOCIATE 299 The UDP ASSOCIATE request is used to establish an asso- 300 ciation within the UDP relay process to handle UDP 301 datagrams. The DST.ADDR and DST.PORT fields contain 302 the address and port that the client expects to use to 303 send UDP datagrams on for the association. The server 304 MAY use this information to limit access to the associ- 305 ation. If the client is not in possesion of the infor- 306 mation at the time of the UDP ASSOCIATE, the client 307 MUST use a port number and address of all zeros. 309 A UDP association terminates when the TCP connection 310 that the UDP ASSOCIATE request arrived on terminates. 312 In the reply to a UDP ASSOCIATE request, the BND.PORT 313 and BND.ADDR fields indicate the port number/address 314 where the client MUST send UDP request messages to be 315 relayed. 317 Reply Processing 319 When a reply (REP value other than X'00') indicates a 320 failure, the SOCKS server MUST terminate the TCP con- 321 nection shortly after sending the reply. This must be 322 no more than 10 seconds after detecting the condition 323 that caused a failure. 325 If the reply code (REP value of X'00') indicates a suc- 326 cess, and the request was either a BIND or a CONNECT, 327 the client may now start passing data. If the selected 328 authentication method supports encapsulation for the 329 purposes of integrity, authentication and/or confiden- 330 tiality, the data are encapsulated using the method- 331 dependent encapsulation. Similarly, when data arrives 332 at the SOCKS server for the client, the server MUST 333 encapsulate the data as appropriate for the authentica- 334 tion method in use. 336 7. Procedure for UDP-based clients 338 A UDP-based client MUST send its datagrams to the UDP 339 relay server at the UDP port indicated by BND.PORT in 340 the reply to the UDP ASSOCIATE request. If the 341 selected authentication method provides encapsulation 342 for the purposes of authenticity, integrity, and/or 343 confidentiality, the datagram MUST be encapsulated 344 using the appropriate encapsulation. Each UDP datagram 345 carries a UDP request header with it: 347 +----+------+------+----------+----------+----------+ 348 |RSV | FRAG | ATYP | DST.ADDR | DST.PORT | DATA | 349 +----+------+------+----------+----------+----------+ 350 | 2 | 1 | 1 | Variable | 2 | Variable | 351 +----+------+------+----------+----------+----------+ 353 The fields in the UDP request header are: 355 o RSV Reserved X'0000' 356 o FRAG Current fragment number 357 o ATYP address type of following addresses: 358 o IP V4 address: X'01' 359 o DOMAINNAME: X'03' 360 o IP V6 address: X'04' 361 o DST.ADDR desired destination address 362 o DST.PORT desired destination port 363 o DATA user data 365 When a UDP relay server decides to relay a UDP data- 366 gram, it does so silently, without any notification to 367 the requesting client. Similarly, it will drop data- 368 grams it cannot or will not relay. When a UDP relay 369 server receives a reply datagram from a remote host, it 370 MUST encapsulate that datagram using the above UDP 371 request header, and any authentication-method-dependent 372 encapsulation. 374 The UDP relay server MUST acquire from the SOCKS server 375 the expected IP address of the client that will send 376 datagrams to the BND.PORT given in the reply to UDP 377 ASSOCIATE. It MUST drop any datagrams arriving from 378 any source IP address other than the one recorded for 379 the particular association. 381 The FRAG field indicates whether or not this datagram 382 is one of a number of fragments. If implemented, the 383 high-order bit indicates end-of-fragment sequence, 384 while a value of X'00' indicates that this datagram is 385 standalone. Values between 1 and 127 indicate the 386 fragment position within a fragment sequence. Each 387 receiver will have a REASSEMBLY QUEUE and a REASSEMBLY 388 TIMER associated with these fragments. The reassembly 389 queue must be reinitialized and the associated frag- 390 ments abandoned whenever the REASSEMBLY TIMER expires, 391 or a new datagram arrives carrying a FRAG field whose 392 value is less than the highest FRAG value processed for 393 this fragment sequence. The reassembly timer MUST be 394 no less than 5 seconds. It is recommended that frag- 395 mentation be avoided by applications wherever possible. 397 Implementation of fragmentation is optional; an imple- 398 mentation that does not support fragmentation MUST drop 399 any datagram whose FRAG field is other than X'00'. 401 The programming interface for a SOCKS-aware UDP MUST 402 report an available buffer space for UDP datagrams that 403 is smaller than the actual space provided by the oper- 404 ating system: 406 o if ATYP is X'01' - 10+method_dependent octets smaller 407 o if ATYP is X'03' - 262+method_dependent octets smaller 408 o if ATYP is X'04' - 20+method_dependent octets smaller 410 8. Security Considerations 412 This document describes a protocol for the application- 413 layer traversal of IP network firewalls. The security 414 of such traversal is highly dependent on the particular 415 authentication and encapsulation methods provided in a 416 particular implementation, and selected during negotia- 417 tion between SOCKS client and SOCKS server. 419 Careful consideration should be given by the adminis- 420 trator to the selection of authentication methods. 422 9. References 424 [1] Koblas, D., "SOCKS", Proceedings: 1992 Usenix Secu- 425 rity Symposium 427 Authors Address 429 Marcus Leech 430 Bell-Northern Research 431 P.O. Box 3511, Stn. C, 432 Ottawa, ON 433 CANADA K1Y 4H7 435 Email: mleech@bnr.ca 436 Phone: (613) 763-9145