idnits 2.17.1 draft-ietf-aft-socks-protocol-v5-04.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-25) 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 == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 481 lines 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 112: '..., and the client MUST close the connec...' RFC 2119 keyword, line 116: '... o X'00' NO AUTHENTICATION REQUIRED...' RFC 2119 keyword, line 135: '... implementations MUST support GSSAPI a...' RFC 2119 keyword, line 143: '..., these requests MUST be encapsulated ...' RFC 2119 keyword, line 271: '... server MAY use this information t...' (12 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 (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Socks Protocol Version 5 2 INTERNET-DRAFT 3 Expires: In Six Months M. Leech 4 M. Ganis 5 Y. Lee 6 R. Kuris 7 D. Koblas 8 L. Jones 10 SOCKS Protocol Version 5 12 Status of this Memo 14 This document is an Internet-Draft. Internet-Drafts are working 15 documents of the Internet Engineering Task Force (IETF), its areas, 16 and its working groups. Note that other groups may also distribute 17 working documents as Internet-Drafts. 19 Internet-Drafts are draft document valid for a maximum of six 20 months and may be updated, replaced or obsoleted by other documents 21 at any time. It is inappropriate to use Internet-Drafts as 22 reference material or to cite them other than as "work in 23 progress". 25 To learn the current status of any Internet-Draft, please check the 26 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 27 Directories on ds.internic.net (US East Coast), nic.nordu.net 28 (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific 29 Rim). 31 Acknowledgments 33 This memo describes a protocol that is an evolution of the previous 34 version of the protocol, version 4 [1]. This new protocol stems 35 from active discussions and prototype implementations. The key 36 contributors are: Marcus Leech: Bell-Northern Research, David 37 Koblas: Independent Consultant, Ying-Da Lee: NEC Systems 38 Laboratory, LaMont Jones: Hewlett-Packard Company, Ron Kuris: Unify 39 Corporation, Matt Ganis: International Business Machines. 41 1. Introduction 43 The use of network firewalls, systems that effectively isolate an 44 organizations internal network structure from an exterior network, 45 such as the INTERNET is becoming increasingly popular. These 46 firewall systems typically act as application-layer gateways 47 between networks, usually offering controlled TELNET, FTP, and SMTP 48 access. With the emergence of more sophisticated application layer 49 protocols designed to facilitate global information discovery, 50 there exists a need to provide a general framework for these 51 protocols to transparently and securely traverse a firewall. 53 There exists, also, a need for strong authentication of such 54 traversal in as fine-grained a manner as is practical. This 55 requirement stems from the realization that client-server 56 relationships emerge between the networks of various organizations, 57 and that such relationships need to be controlled and often 58 strongly authenticated. 60 The protocol described here is designed to provide a framework for 61 client-server applications in both the TCP and UDP domains to 62 conveniently and securely use the services of a network firewall. 63 The protocol is conceptually a "shim-layer" between the application 64 layer and the transport layer, and as such does not provide 65 network-layer gateway services, such as forwarding of ICMP 66 messages. 68 2. Existing practice 70 There currently exists a protocol, SOCKS Version 4, that provides 71 for unsecured firewall traversal for TCP-based client-server 72 applications, including TELNET, FTP and the popular information- 73 discovery protocols such as HTTP, WAIS and GOPHER. 75 This new protocol extends the SOCKS Version 4 model to include UDP, 76 and extends the framework to include provisions for generalized 77 strong authentication schemes, and extends the addressing scheme to 78 encompass domain-name and V6 IP addresses. 80 The implementation of the SOCKS protocol typically involves the 81 recompilation or relinking of TCP-based client applications to use 82 the appropriate encapsulation routines in the SOCKS library. 84 3. Procedure for TCP-based clients 86 When a TCP-based client wishes to establish a connection to an 87 object that is reachable only via a firewall (such determination is 88 left up to the implementation), it must open a TCP connection to 89 the appropriate SOCKS port on the SOCKS server system. The SOCKS 90 service is conventionally located on TCP port 1080. If the 91 connection request succeeds, the client enters a negotiation for 92 the authentication method to be used, authenticates with the chosen 93 method, then sends a relay request. The SOCKS server evaluates the 94 request, and either establishes the appropriate connection or 95 denies it. 97 The client connects to the server, and sends a version 98 identifier/method selection message: 100 tab(~) center box; c|c|c. VER~NMETHODS~METHODS = 1~1~1 to 255 102 The VER field is set to X'05' for this version of the protocol. 103 The NMETHODS field contains the number of method identifier octets 104 that appear in the METHODS field. 106 The server selects from one of the methods given in METHODS, and 107 sends a METHOD selection message: 109 center tab(~) box; c|c. VER~METHOD = 1~1 111 If the selected METHOD is X'FF', none of the methods listed by the 112 client are acceptable, and the client MUST close the connection. 114 The values currently defined for METHOD are: 116 o X'00' NO AUTHENTICATION REQUIRED 117 o X'01' GSSAPI 118 o X'02' USERNAME/PASSWORD 120 o X'03' to X'7F' IANA ASSIGNED 122 o X'80' to X'FE' RESERVED FOR PRIVATE METHODS 124 o X'FF' NO ACCEPTABLE METHODS 126 The client and server then enter a method-specific subnegotiation. 127 Descriptions of the method-dependent subnegotiations appear in 128 separate drafts. 130 Developers of new METHOD support for this protocol should contact 131 IANA for a METHOD number. The ASSIGNED NUMBERS document should be 132 referred to for a current list of METHOD numbers and their 133 corresponding protocols. 135 Compliant implementations MUST support GSSAPI and SHOULD support 136 USERNAME/PASSWORD authentication methods. 138 4. Requests 140 Once the method-dependent subnegotiation has completed, the client 141 sends the request details. If the negotiated method includes 142 encapsulation for purposes of integrity checking and/or 143 confidentiality, these requests MUST be encapsulated in the 144 method-dependent encapsulation. 146 The SOCKS request is formed as follows: 148 center box tab(~); c|c|c|c|c|c. VER~CMD~RSV~ATYP~DST.ADDR~DST.PORT 149 = 1~1~X'00'~1~Variable~2 151 Where: 153 o VER protocol version: X'05' 154 o CMD 155 o CONNECT X'01' 156 o BIND X'02' 157 o UDP ASSOCIATE X'03' 158 o RSV RESERVED 159 o ATYP address type of following address 160 o IP V4 address: X'01' 161 o DOMAINNAME: X'03' 162 o IP V6 address: X'04' 163 o DST.ADDR desired destination address 164 o DST.PORT desired destination port in network octet order 166 The SOCKS server will typically evaluate the request based on 167 source and destination addresses, and return one or more reply 168 messages, as appropriate for the request type. 170 5. Addressing 172 In an address field (DST.ADDR, BND.ADDR), the ATYP field specifies 173 the type of address contained within the field: 175 o X'01' 177 the address is a version-4 IP address, with a length of 4 octets 179 o X'03' 181 the address field contains a DNS-style domain name. The first 182 octet of the address field contains the number of octets that 183 follow. 185 o X'04' 187 the address is a version-6 IP address, with a length of 16 octets. 189 6. Replies 191 The SOCKS request information is sent by the client as soon as it 192 has established a connection to the SOCKS server, and completed the 193 authentication negotiations. The server evaluates the request, and 194 returns a reply formed as follows: 196 center tab(~) box; c|c|c|c|c|c. VER~REP~RSV~ATYP~BND.ADDR~BND.PORT 197 = 1~1~X'00'~1~Variable~2 199 Where: 201 o VER protocol version: X'05' 202 o REP Reply field: 203 o X'00' succeeded 204 o X'01' general SOCKS server failure 205 o X'02' connection not allowed by ruleset 206 o X'03' Network unreachable 207 o X'04' Host unreachable 208 o X'05' Connection refused 209 o X'06' TTL expired 210 o X'07' Command not supported 211 o X'08' Address type not supported 212 o X'09' to X'FF' unassigned 213 o RSV RESERVED 214 o ATYP address type of following address 215 o IP V4 address: X'01' 216 o DOMAINNAME: X'03' 217 o IP V6 address: X'04' 218 o BND.ADDR server bound address 219 o BND.PORT server bound port in network octet order 221 Fields marked RESERVED (RSV) must be set to X'00'. 223 If the chosen method includes encapsulation for purposes of 224 authentication, integrity and/or confidentiality, the replies are 225 encapsulated in the method-dependent encapsulation. 227 CONNECT 229 In the reply to a CONNECT, BND.PORT contains the port number that 230 the server assigned to connect to the target host, while BND.ADDR 231 contains the associated IP address. The supplied BND.ADDR is often 232 different from the IP address that the client uses to reach the 233 SOCKS server, since such servers are often multi-homed. It is 234 expected that the SOCKS server will use DST.ADDR and DST.PORT, and 235 the client-side source address and port in evaluating the CONNECT 236 request. 238 BIND 240 The BIND request is used in protocols which require the client to 241 accept connections from the server. FTP is a well-known example, 242 which uses the primary client-to-server connection for commands and 243 status reports, but may use a server-to-client connection for 244 transferring data on demand (e.g. LS, GET, PUT). 246 It is expected that the client side of an application protocol will 247 use the BIND request only to establish secondary connections after 248 a primary connection is established using CONNECT. In is expected 249 that a SOCKS server will use DST.ADDR and DST.PORT in evaluating 250 the BIND request. 252 Two replies are sent from the SOCKS server to the client during a 253 BIND operation. The first is sent after the server creates and 254 binds a new socket. The BND.PORT field contains the port number 255 that the SOCKS server assigned to listen for an incoming 256 connection. The BND.ADDR field contains the associated IP address. 257 The client will typically use these pieces of information to notify 258 (via the primary or control connection) the application server of 259 the rendezvous address. The second reply occurs only after the 260 anticipated incoming connection succeeds or fails. 262 In the second reply, the BND.PORT and BND.ADDR fields contain the 263 address and port number of the connecting host. 265 UDP ASSOCIATE 267 The UDP ASSOCIATE request is used to establish an association 268 within the UDP relay process to handle UDP datagrams. The DST.ADDR 269 and DST.PORT fields contain the address and port that the client 270 expects to use to send UDP datagrams on for the association. The 271 server MAY use this information to limit access to the association. 272 If the client is not in possesion of the information at the time of 273 the UDP ASSOCIATE, the client MUST use a port number and address of 274 all zeros. 276 A UDP association terminates when the TCP connection that the UDP 277 ASSOCIATE request arrived on terminates. 279 In the reply to a UDP ASSOCIATE request, the BND.PORT and BND.ADDR 280 fields indicate the port number/address where the client MUST send 281 UDP request messages to be relayed. 283 Reply Processing 285 When a reply (REP value other than X'00') indicates a failure, the 286 SOCKS server MUST terminate the TCP connection shortly after 287 sending the reply. This must be no more than 10 seconds after 288 detecting the condition that caused a failure. 290 If the reply code (REP value of X'00') indicates a success, and the 291 request was either a BIND or a CONNECT, the client may now start 292 passing data. If the selected authentication method supports 293 encapsulation for the purposes of integrity, authentication and/or 294 confidentiality, the data are encapsulated using the method- 295 dependent encapsulation. Similarly, when data arrives at the SOCKS 296 server for the client, the server MUST encapsulate the data as 297 appropriate for the authentication method in use. 299 7. Procedure for UDP-based clients 301 A UDP-based client MUST send its datagrams to the UDP relay server 302 at the UDP port indicated by BND.PORT in the reply to the UDP 303 ASSOCIATE request. If the selected authentication method provides 304 encapsulation for the purposes of authenticity, integrity, and/or 305 confidentiality, the datagram MUST be encapsulated using the 306 appropriate encapsulation. Each UDP datagram carries a UDP request 307 header with it: 309 center box tab(~); c|c|c|c|c|c. 310 RSV~FRAG~ATYP~DST.ADDR~DST.PORT~DATA = 2~1~1~Variable~2~Variable 312 The fields in the UDP request header are: 314 o RSV Reserved X'0000' 315 o FRAG Current fragment number 316 o ATYP address type of following addresses: 317 o IP V4 address: X'01' 318 o DOMAINNAME: X'03' 319 o IP V6 address: X'04' 320 o DST.ADDR desired destination address 321 o DST.PORT desired destination port 322 o DATA user data 324 When a UDP relay server decides to relay a UDP datagram, it does so 325 silently, without any notification to the requesting client. 326 Similarly, it will drop datagrams it cannot or will not relay. 327 When a UDP relay server receives a reply datagram from a remote 328 host, it MUST encapsulate that datagram using the above UDP request 329 header, and any authentication-method-dependent encapsulation. 331 The UDP relay server MUST acquire from the SOCKS server the 332 expected IP address of the client that will send datagrams to the 333 BND.PORT given in the reply to UDP ASSOCIATE. It MUST drop any 334 datagrams arriving from any source IP address other than the one 335 recorded for the particular association. 337 The FRAG field indicates whether or not this datagram is one of a 338 number of fragments. If implemented, the high-order bit indicates 339 end-of-fragment sequence, while a value of X'00' indicates that 340 this datagram is standalone. Values between 1 and 127 indicate the 341 fragment position within a fragment sequence. Each receiver will 342 have a REASSEMBLY QUEUE and a REASSEMBLY TIMER associated with 343 these fragments. The reassembly queue must be reinitialized and 344 the associated fragments abandoned whenever the REASSEMBLY TIMER 345 expires, or a new datagram arrives carrying a FRAG field whose 346 value is less than the highest FRAG value processed for this 347 fragment sequence. The reassembly timer MUST be no less than 5 348 seconds. It is recommended that fragmentation be avoided by 349 applications wherever possible. 351 Implementation of fragmentation is optional; an implementation that 352 does not support fragmentation MUST drop any datagram whose FRAG 353 field is other than X'00'. 355 The programming interface for a SOCKS-aware UDP MUST report an 356 available buffer space for UDP datagrams that is smaller than the 357 actual space provided by the operating system: 359 o if ATYP is X'01' - 10+method_dependent octets smaller 360 o if ATYP is X'03' - 262+method_dependent octets smaller 361 o if ATYP is X'04' - 20+method_dependent octets smaller 363 8. Security Considerations 365 This document describes a protocol for the application-layer 366 traversal of IP network firewalls. The security of such traversal 367 is highly dependent on the particular authentication and 368 encapsulation methods provided in a particular implementation, and 369 selected during negotiation between SOCKS client and SOCKS server. 371 Careful consideration should be given by the administrator to the 372 selection of authentication methods. 374 9. References 376 [1] Koblas, D., "SOCKS", Proceedings: 1992 Usenix Security 377 Symposium 379 Authors Address 381 Marcus Leech 382 Bell-Northern Research 383 P.O. Box 3511, Stn. C, 384 Ottawa, ON 385 CANADA K1Y 4H7 387 Email: mleech@bnr.ca 388 Phone: (613) 763-9145