idnits 2.17.1 draft-ietf-aft-socks-protocol-v5-02.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-03-29) 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 both GSS...' RFC 2119 keyword, line 156: '... requests MUST be encapsulated in ...' RFC 2119 keyword, line 304: '...T is zero, the SOCKS server SHOULD use...' (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 both GSSAPI and 148 USERNAME/PASSWORD authentication methods. 150 4. Requests 152 Once the method-dependent subnegotiation has completed, 153 the client sends the request details. If the negoti- 154 ated method includes encapsulation for purposes of 155 integrity checking and/or confidentiality, these 156 requests MUST be encapsulated in the method-dependent 157 encapsulation. 159 The SOCKS request is formed as follows: 161 +----+-----+-------+------+----------+----------+ 162 |VER | CMD | RSV | ATYP | DST.ADDR | DST.PORT | 163 +----+-----+-------+------+----------+----------+ 164 | 1 | 1 | X'00' | 1 | Variable | 2 | 165 +----+-----+-------+------+----------+----------+ 167 Where: 169 o VER protocol version: X'05' 170 o CMD 171 o CONNECT X'01' 172 o BIND X'02' 173 o UDP ASSOCIATE X'03' 174 o UDP DESTROY X'04' 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 DNS-style domain name. 201 The first octet of the address field contains the 202 length of the domain name. 204 o X'04' 206 the address is a version-6 IP address, with a length of 207 16 octets. 209 6. Replies 211 The SOCKS request information is sent by the client as 212 soon as it has established a connection to the SOCKS 213 server, and completed the authentication negotiations. 214 The server evaluates the request, and returns a reply 215 formed as follows: 217 +----+-----+-------+------+----------+----------+ 218 |VER | REP | RSV | ATYP | BND.ADDR | BND.PORT | 219 +----+-----+-------+------+----------+----------+ 220 | 1 | 1 | X'00' | 1 | Variable | 2 | 221 +----+-----+-------+------+----------+----------+ 223 Where: 225 o VER protocol version: X'05' 226 o REP Reply field: 227 o X'00' succeeded 228 o X'01' general SOCKS server failure 229 o X'02' connection not allowed by ruleset 230 o X'03' Network unreachable 231 o X'04' Host unreachable 232 o X'05' Connection refused 233 o X'06' TTL expired 234 o X'07' to X'FF' unassigned 236 o RSV RESERVED 237 o ATYP address type of following address 238 o IP V4 address: X'01' 239 o DOMAINNAME: X'03' 240 o IP V6 address: X'04' 241 o BND.ADDR server bound address 242 o BND.PORT server bound port in network octet order 244 Fields marked RESERVED (RSV) must be set to X'00'. 246 If the chosen method includes encapsulation for pur- 247 poses of authentication, integrity and/or confidential- 248 ity, the replies are encapsulated in the method- 249 dependent encapsulation. 251 CONNECT 253 In the reply to a CONNECT, BND.PORT contains the port 254 number that the server assigned to connect to the tar- 255 get host, while BND.ADDR contains the associated IP 256 address. The supplied BND.ADDR is often different from 257 the IP address that the client uses to reach the SOCKS 258 server, since such servers are often multi-homed. It 259 is expected that the SOCKS server will use DST.ADDR and 260 DST.PORT, and the client-side source address and port 261 in evaluating the CONNECT request. 263 BIND 265 The BIND request is used in protocols which require the 266 client to accept connections from the server. FTP is a 267 well-known example, which uses the primary client-to- 268 server connection for commands and status reports, but 269 may use a server-to-client connection for transferring 270 data on demand (e.g. LS, GET, PUT). 272 It is expected that the client side of an application 273 protocol will use the BIND request only to establish 274 secondary connections after a primary connection is 275 established using CONNECT. In is expected that a SOCKS 276 server will use DST.ADDR and DST.PORT in evaluating the 277 BIND request. 279 Two replies are sent from the SOCKS server to the 280 client during a BIND operation. The first is sent 281 after the server creates and binds a new socket. The 282 BND.PORT field contains the port number that the SOCKS 283 server assigned to listen for an incoming connection. 285 The BND.ADDR field contains the associated IP address. 286 The client will typically use these pieces of informa- 287 tion to notify (via the primary or control connection) 288 the application server of the rendezvous address. The 289 second reply occurs only after the anticipated incoming 290 connection succeeds or fails. 292 In the second reply, the BND.PORT and BND.ADDR fields 293 contain the address and port number of the connecting 294 host. 296 UDP ASSOCIATE 298 The UDP ASSOCIATE request is used to establish an asso- 299 ciation within the UDP relay process to handle UDP 300 datagrams. The DST.ADDR field is ignored in a UDP 301 ASSOCIATE request, while the DST.PORT field contains 302 the idle-timeout time, in minutes, that an association 303 is allowed to exist without explicit client-side activ- 304 ity. If DST.PORT is zero, the SOCKS server SHOULD use 305 an administrator-defined default. 307 In the reply to a UDP ASSOCIATE request, the BND.PORT 308 and BND.ADDR fields indicate the port number/address 309 where the client may send UDP request messages to be 310 relayed. Once a UDP ASSOCIATE request has been pro- 311 cessed, the SOCKS client MUST terminate the connection. 313 UDP DESTROY 315 The UDP DESTROY request is used to destroy an existing 316 association within the UDP relay process. The DST.ADDR 317 and DST.PORT fields contain the address and port number 318 of the UDP relay process corresponding to the associa- 319 tion to destroy. Once a UDP ASSOCIATE request has been 320 processed, the SOCKS client MUST terminate the connec- 321 tion. 323 When a reply (REP value other than X'00') indicates a 324 failure, the SOCKS server MUST terminate the TCP con- 325 nection shortly after sending the reply. This must be 326 no more than 10 seconds after detecting the condition 327 that caused a failure. 329 If the reply code (REP value of X'00') indicates a suc- 330 cess, and the request was either a BIND or a CONNECT, 331 the client may now start passing data. If the selected 332 authentication method supports encapsulation for the 333 purposes of integrity, authentication and/or confiden- 334 tiality, the data are encapsulated using the method- 335 dependent encapsulation. Similarly, when data arrives 336 at the SOCKS server for the client, the server MUST 337 encapsulate the data as appropriate for the authentica- 338 tion method in use. 340 7. Procedure for UDP-based clients 342 A UDP-based client MUST send its datagrams to the UDP 343 relay server at the UDP port indicated by BND.PORT in 344 the reply to the UDP ASSOCIATE request. If the 345 selected authentication method provides encapsulation 346 for the purposes of authenticity, integrity, and/or 347 confidentiality, the datagram MUST be encapsulated 348 using the appropriate encapsulation. Each UDP datagram 349 carries a UDP request header with it: 351 +----+------+------+----------+----------+----------+ 352 |RSV | FRAG | ATYP | DST.ADDR | DST.PORT | DATA | 353 +----+------+------+----------+----------+----------+ 354 | 1 | 2 | 1 | Variable | 2 | Variable | 355 +----+------+------+----------+----------+----------+ 357 The fields in the UDP request header are: 359 o RSV Reserved X'0000' 360 o FRAG Current fragment number 361 o ATYP address type of following addresses: 362 o IP V4 address: X'01' 363 o DOMAINNAME: X'03' 364 o IP V6 address: X'04' 365 o DST.ADDR desired destination address 366 o DST.PORT desired destination port 367 o DATA user data 369 When a UDP relay server decides to relay a UDP data- 370 gram, it does so silently, without any notification to 371 the requesting client. Similarly, it will drop data- 372 grams it cannot or will not relay. When a UDP relay 373 server receives a reply datagram from a remote host, it 374 MUST encapsulate that datagram using the above UDP 375 request header, and any authentication-method-dependent 376 encapsulation. 378 The UDP relay server MUST acquire from the SOCKS server 379 the expected IP address of the client that will send 380 datagrams to the BND.PORT given in the reply to UDP 381 ASSOCIATE. It MUST drop any datagrams arriving from 382 any source IP address other than the one recorded for 383 the particular association. 385 The FRAG field indicates whether or not this datagram 386 is one of a number of fragments. The high-order bit 387 indicates end-of-fragment sequence, while a value of 388 X'00' indicates that this datagram is standalone. Val- 389 ues between 1 and 127 indicate the fragment position 390 within a fragment sequence. Each receiver will have a 391 REASSEMBLY QUEUE and a REASSEMBLY TIMER associated with 392 these fragments. The reassembly queue must be reini- 393 tialized and the associated fragments abandoned when- 394 ever the REASSEMBLY TIMER expires, or a new datagram 395 arrives carrying a FRAG field whose value is less than 396 the highest FRAG value processed for this fragment 397 sequence. The reassembly timer MUST be no less than 5 398 seconds. It is recommended that fragmentation be 399 avoided by applications wherever possible. 401 Implementation of fragmentation is optional; an imple- 402 mentation that does not support fragmentation MUST drop 403 any datagram whose FRAG field is other than X'00'. 405 The programming interface for a SOCKS-aware UDP MUST 406 report an available buffer space for UDP datagrams that 407 is smaller than the actual space provided by the oper- 408 ating system: 410 o if ATYP is X'01' - 10+method_dependent octets smaller 411 o if ATYP is X'03' - 262+method_dependent octets smaller 412 o if ATYP is X'04' - 20+method_dependent octets smaller 414 The ASSOCIATION established with a UDP ASSOCIATE 415 request has a specific lifetime. The UDP server SHOULD 416 refresh the lifetime every time a valid datagram 417 arrives from the client at the UDP relay server. 419 8. Security Considerations 421 This document describes a protocol for the application- 422 layer traversal of IP network firewalls. The security 423 of such traversal is highly dependent on the particular 424 authentication and encapsulation methods provided in a 425 particular implementation, and selected during negotia- 426 tion between SOCKS client and SOCKS server. 428 Careful consideration should be given by the adminis- 429 trator to the selection of authentication methods. 431 9. References 433 [1] Koblas, D., "SOCKS", Proceedings: 1992 Usenix Secu- 434 rity Symposium 436 Authors Address 438 Marcus Leech 439 Bell-Northern Research 440 P.O. Box 3511, Stn. C, 441 Ottawa, ON 442 CANADA K1Y 4H7 444 Email: mleech@bnr.ca 445 Phone: (613) 763-9145