idnits 2.17.1 draft-ietf-aft-socks-protocol-v5-01.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-19) 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 115: '...nt are acceptable, and the server MUST...' RFC 2119 keyword, line 120: '... o X'00' NO AUTHENTICATION REQUIRED...' RFC 2119 keyword, line 151: '... tion MUST support both compressed a...' RFC 2119 keyword, line 158: '...onfidentiality, these requests MUST be...' RFC 2119 keyword, line 298: '...rocessed, the SOCKS server MUST termi-...' (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' ** Downref: Normative reference to an Informational RFC: RFC 1321 (ref. '2') -- Possible downref: Non-RFC (?) normative reference: ref. '3' Summary: 12 errors (**), 0 flaws (~~), 2 warnings (==), 4 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 months 20 and may be updated, replaced or obsoleted by other documents at any 21 time. It is inappropriate to use Internet-Drafts as reference 22 material or to cite them other than as "work in progress". 24 To learn the current status of any Internet-Draft, please check the 25 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 26 Directories on ds.internic.net (US East Coast), nic.nordu.net 27 (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific 28 Rim). 30 Acknowledgments 32 This memo describes a protocol that is an evolution of the previous 33 version of the protocol, version 4 [1]. This new protocol stems from 34 active discussions and prototype implementations. The key 35 contributors are: Marcus Leech: Bell-Northern Research, David Koblas: 36 Independent Consultant, Ying-Da Lee: NEC Systems Laboratory, LaMont 37 Jones: Hewlett-Packard Company, Ron Kuris: Unify Corporation, Matt 38 Ganis: International Business Machines. 40 1. Introduction 42 The use of network firewalls, systems that effectively isolate an 43 organizations internal network structure from an exterior network, 44 such as the INTERNET is becoming increasingly popular. These firewall 45 systems typically act as application-layer gateways between networks, 46 usually offering controlled TELNET, FTP, and SMTP access. With the 47 emergence of more sophisticated application layer protocols designed 48 to facilitate global information discovery, there exists a need to 49 provide a general framework for these protocols to transparently and 50 securely traverse a firewall. 52 There exists, also, a need for strong authentication of such 53 traversal in as fine-grained a manner as is practical. This 54 requirement stems from the realization that client-server 55 relationships emerge between the networks of various organizations, 56 and that such relationships need to be controlled and often strongly 57 authenticated. 59 The protocol described here is designed to provide a framework for 60 client-server applications in both the TCP and UDP domains to 61 conveniently and securely use the services of a network firewall. 63 2. Existing practice 65 There currently exists a protocol, SOCKS Version 4, that provides for 66 unsecured firewall traversal for TCP-based client-server 67 applications, including TELNET, FTP and the popular information- 68 discovery protocols such as HTTP, WAIS and GOPHER. 70 This protocol extends the SOCKS Version 4 model to include UDP, and 71 extends the protocol to include provisions for generalized strong 72 authentication schemes, and extends the addressing scheme to 73 encompass domain-name and V6 IP addresses. The implementation of the 74 SOCKS protocol typically involves the recompilation or relinking of 75 TCP-based client applications to use the appropriate encapsulation 76 routines in the SOCKS library. 78 3. Procedure for TCP-based clients 80 When a TCP-based client wishes to establish a connection to an object 81 that is reachable only via a firewall (such determination is left up 82 to the implementation), it must open a TCP connection to the 83 appropriate SOCKS port on the SOCKS server system. The SOCKS service 84 is conventionally located on TCP port 1080. If the connection request 85 succeeds, the client enters a negotiation for the authentication 86 method to be used, authenticates with the chosen method, then sends a 87 relay request. The SOCKS server evaluates the request, and either 88 establishes the appropriate connection or denies it. 90 The client connects to the server, and sends a version 91 identifier/method selection packet: 93 +----+----------+----------+------+ 94 |VER | NMETHODS | METHODS | MACS | 95 +----+----------+----------+------+ 96 | 1 | 1 | 1 to 255 | 1 | 97 +----+----------+----------+------+ 99 The VER field is set to X'05' for this version of the 100 protocol. The NMETHODS field contains the number of 101 method identifier octets that appear in the METHODS 102 field. 104 The server selects from one of the methods given in METH- 105 ODS, and a MAC algorithm, then sends a selection indica- 106 tor: 108 +----+--------+--------+ 109 |VER | METHOD | MACSEL | 110 +----+--------+--------+ 111 | 1 | 1 | 1 | 112 +----+--------+--------+ 114 If the selection indicator is X'FF', none of the METHODS 115 listed by the client are acceptable, and the server MUST 116 close the connection. 118 The values currently defined for METHOD are: 120 o X'00' NO AUTHENTICATION REQUIRED 121 o X'01' BNR-1 122 o X'02' GSSAPI 123 o X'03' IKMP 124 o X'04' KERBEROS4 125 o X'05' KERBEROS5 126 o X'06' USERNAME/PASSWORD 127 o X'07' SECURE TOKEN TYPE 1 (NO CHALLENGE/RESPONSE) 128 o X'08' SECURE TOKEN TYPE 2 (CHALLENGE/RESPONSE) 129 o X'09' S/KEY 130 o X'0A' to X'FE' RESERVED 131 o X'FF' NO ACCEPTABLE METHODS 133 The client and server then enter a method-specific subne- 134 gotiation. 136 Descriptions of the method-dependant subnegotiations 137 appear in separate drafts. 139 The MACS field contains a bit-vector indicating the MAC 140 algorithms available to the client. Bits are labelled 141 from most-significant (0) to least significant (7): 143 o 0 - MD5 with 64-bit compression [2] 144 o 1 - MD5 with no compression (complete digest of 128 bits) 145 o 2 - SHA with 80-bit compression [3] 146 o 3 - SHA with no compression (complete digest of 160 bits) 148 The MACSEL field indicates which MAC algorithm that the 149 server wishes the client to use during computation of the 150 MAC field for UDP relay requests. A compliant implementa- 151 tion MUST support both compressed and uncompressed MD5. 153 4. Requests 155 Once the method-dependant subnegotiation has completed, 156 the client sends the request details. If the negotiated 157 method includes encapsulation for purposes of integrity 158 checking/and or confidentiality, these requests MUST be 159 encapsulated in the method-dependant encapsulation. 161 The SOCKS request is formed as follows: 163 +----+-----+-------+------+----------+----------+ 164 |VER | CMD | RSV | ATYP | DST.ADDR | DST.PORT | 165 +----+-----+-------+------+----------+----------+ 166 | 1 | 1 | X'00' | 1 | Variable | 2 | 167 +----+-----+-------+------+----------+----------+ 169 Where: 171 o VER protocol version: X'05' 172 o CMD 173 o CONNECT X'01' 174 o BIND X'02' 175 o UDP ASSOCIATE X'03' 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 evaluate the request based on 185 source and destination addresses, and return one or more 186 reply packets, as appropriate for the request type. 188 5. Addressing 190 In an address field (DST.ADDR, BND.ADDR), the ATYP field 191 specifies the type of address contained within the field: 193 o X'01' 195 the address is a version-4 IP address, with a length of 4 196 octets 198 o X'03' 200 the address field contains a DNS-style domain name. The 201 first octet of the address field contains the length of 202 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 | COOKIE | 219 +----+-----+-------+------+----------+----------+--------+ 220 | 1 | 1 | X'00' | 1 | Variable | 2 | 8 | 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 235 o RSV RESERVED 236 o ATYP address type of following address 237 o IP V4 address: X'01' 238 o DOMAINNAME: X'03' 239 o IP V6 address: X'04' 240 o BND.ADDR server bound address 241 o BND.PORT server bound port in network octet order 242 o COOKIE extra data used by UDP ASSOCIATE 244 Fields marked RESERVED (RSV) must be set to X'00'. 246 If the chosen method includes encapsulation for purposes 247 of authentication, integrity and or confidentiality, the 248 replies are encapsulated in the method-dependant encapsu- 249 lation. 251 In a reply, the BND.ADDR and BND.PORT fields are the 252 SOCKS server address and port number of the outbound con- 253 nection for a CONNECT request, and contain the SOCKS 254 server bind() address for a BIND request. 256 The BIND request is used in protocols which require the 257 client to accept connections from the server. FTP is a 258 well-known example, which uses the primary client-to- 259 server connection for commands and status reports, but 260 may use a server-to-client connection for transferring 261 data on demand (e.g. LS, GET, PUT). 263 It is expected that the client side of an application 264 protocol will use the BIND request only to establish sec- 265 ondary connections after a primary connection is estab- 266 lished using CONNECT. In is expected that a SOCKS server 267 will use DST.ADDR and DST.PORT in evaluating the BIND 268 request. 270 Two replies are sent from the SOCKS server to the client 271 during a BIND operation. The first is sent after the 272 server creates and binds a new socket. The BND.PORT field 273 contains the port number that the SOCKS server assigned 274 to listen for an incoming connection. The BND.ADDR field 275 contains the associated IP address. The client will typi- 276 cally use these pieces of information to notify (via the 277 primary or control connection) the application server of 278 the `rendezvous point'. The second reply occurs only 279 after the anticipated incoming connection succeeds or 280 fails. In the second reply, the BND.PORT and BND.ADDR 281 fields contain the address and port number of the 282 connecting host. 284 In the reply to a CONNECT, BND.PORT contains the port 285 number that the server assigned to connect to the target 286 host, while BND.ADDR contains the associated IP address. 287 The supplied BND.ADDR is often different from the IP 288 address that the client uses to reach the SOCKS server, 289 since such servers are often multi-homed. 291 The UDP ASSOCIATE request is used to establish an associ- 292 ation within the UDP relay process to handle UDP data- 293 grams. In the reply to a UDP ASSOCIATE request, the 294 BND.PORT and BND.ADDR fields indicate the port num- 295 ber/address where the client may send UDP request packets 296 to be relayed. The DST.ADDR and DST.PORT fields are 297 ignored in a UDP ASSOCIATE request. Once a UDP ASSOCIATE 298 request has been processed, the SOCKS server MUST termi- 299 nate the connection. The COOKIE field is used in the com- 300 putation of a Message Authentication Code by the UDP 301 relay server. The SOCKS server MUST set this field to a 302 random value. The association created by the UDP ASSOCI- 303 ATE request has a specific and site or implementation 304 dependant lifetime. 306 When a reply (REP value other than X'00') indicates a 307 failure, the SOCKS server MUST terminate the TCP connec- 308 tion shortly after sending the reply. This must be no 309 more than 10 seconds after detecting the condition that 310 caused a failure. 312 If the reply code (REP value of X'00') indicates a suc- 313 cess, and the request was either a BIND or a CONNECT, the 314 client may now start passing data. If the selected 315 authentication method supports encapsulation for the pur- 316 poses of integrity, authentication and or confidential- 317 ity, the data are encapsulated using the method-dependent 318 encapsulation. Similarly, when data arrives at the SOCKS 319 server for the client, the server MUST encapsulate the 320 data as appropriate for the authentication method in use. 322 7. Procedure for UDP-based clients 324 A UDP-based client must send its datagrams to the UDP 325 relay server at the UDP port indicated by BND.PORT in the 326 reply to the UDP ASSOCIATE request. Each UDP datagram 327 carries a UDP request header with it: 329 +-----+------+----------+----------+---------+----------+ 330 |FRAG | ATYP | DST.ADDR | DST.PORT | MAC | DATA | 331 +-----+------+----------+----------+---------+----------+ 332 | 1 | 1 | Variable | 2 | 8 to 20 | Variable | 333 +-----+------+----------+----------+---------+----------+ 335 The fields in the UDP request header are: 337 o FRAG Current fragment number 338 o ATYP address type of following addresses: 339 o IP V4 address: X'01' 340 o DOMAINNAME: X'03' 341 o IP V6 address: X'04' 342 o DST.ADDR desired destination address 343 o DST.PORT desired destination port 344 o MAC Message Authentication Code 346 When a UDP relay server decides to relay a UDP datagram, 347 it does so silently, without any notification to the 348 requesting client. Similarly, it will drop datagrams it 349 cannot or will not relay. When a UDP relay server 350 receives a reply datagram from a remote host, it MUST 351 encapsulate that datagram using the above UDP request 352 header. 354 The UDP relay server MUST acquire from the SOCKS server 355 the expected IP address of the client that will send 356 datagrams to the BND.PORT given in the reply to UDP ASSO- 357 CIATE. It MUST drop any datagrams arriving from any 358 source IP address other than the one recorded for the 359 particular association. 361 Related to each UDP association is a pair of unsigned 362 32-bit counters. These counters are used to assist in 363 computing the current value of the MAC field. The MAC 364 (Message Authentication Code) field contains a message- 365 digest computation of: 367 o the XCOOKIE digest 368 o the counter 369 o the ATYP 370 o the DST.ADDR (in network octet order) 371 o the DST.PORT (in network octet order) 372 o the DATA 373 o the XCOOKIE digest 375 Each algorithm uses a different length of residue after 376 computing the digest function. For MD5 with 8-octet 377 compression, the residue is formed by taking octets 378 0,2,4,6,8,10,12,14 of the digest, and concatenating them 379 into an 8-octet string. Similarly for SHA, octets 380 0,2,4,6,8,10,12,14,16,18 are concatenated to form a 381 10-octet string. For algorithms that don't specify a 382 compression, the complete digest is used. 384 The value for the XCOOKIE digest is determined by a mes- 385 sage-digest consisting of: 387 o the method-dependant authentication key material 388 (if any, else 8 octets of X'AA') 389 o the COOKIE from the UDP ASSOCIATE request 390 o the method-dependant authentication key material 391 (if any, else 8 octets of X'AA') 393 The method-dependant authentication key material MUST be 394 at least 8 octets in length. 396 The sender increments its counter after sending the data- 397 gram, while the receiver increments its counter after 398 receipt. The receiver MUST be prepared to accept data- 399 grams whose counter value is several units ahead of the 400 expected value, due to datagram loss. This is typically 401 implemented by the receiver looking for a MAC match by 402 repeatedly incrementing its counter value, and looking 403 for a match. The receiver does this until either there is 404 a MAC match, or the tolerance has been exceeded The rec- 405 ommended counter mismatch tolerance is 7 units.The coun- 406 ters start at zero. 408 The FRAG field indicates whether or not this datagram is 409 one of a number of fragments. The high-order bit indi- 410 cates end-of-fragment sequence, while a value of X'00' 411 indicates that this datagram is standalone. Values 412 between 1 and 127 indicate the fragment position within a 413 fragment sequence. The implicit counter value increments 414 on every fragment. Each receiver will have a REASSEMBLY 415 QUEUE and a REASSEMBLY TIMER associated with these frag- 416 ments. The reassembly queue must be reinitialized and 417 the associated fragments abandoned whenever the REASSEM- 418 BLY TIMER expires, or a new datagram arrives carrying a 419 FRAG field whose value is less than the highest FRAG 420 value processed for this fragment sequence. The reassem- 421 bly timer MUST be no less than 5 seconds. It is strongly 422 recommended that fragmentation be avoided by applications 423 wherever possible. 425 Implementation of fragmentation is optional; an implemen- 426 tation that does not support fragmentation MUST drop any 427 datagram whose FRAG field is other than X'00'. 429 The UDP relay server MUST drop any datagrams for which 430 the MAC value is outside of the acceptable range. 431 Repeated occurrences of invalid MAC values should cause 432 the UDP relay server to destroy the association. 434 The programming interface for a SOCKS-aware UDP MUST 435 report an available buffer space for UDP datagrams that 436 is smaller than the actual space provided by the operat- 437 ing system: 439 o if ATYP is X'01' - 16 octets smaller 440 o if ATYP is X'03' - 272 octets smaller 441 o if ATYP is X'04' - 28 octets smaller 443 The ASSOCIATION established with a UDP ASSOCIATE request 444 has a specific lifetime. It is strongly recommended that 445 this lifetime be extended by the lifetime value every 446 time a valid datagram arrives from the client at the UDP 447 relay server. 449 8. Security Considerations 451 This document describes a protocol for the application- 452 layer traversal of IP network firewalls. The security of 453 such traversal is highly dependant on the particular 454 authentication and encapsulation methods used in a par- 455 ticular implementation. 457 The protection for relayed UDP data when an authentica- 458 tion method doesn't supply suitable keying material is 459 quite weak. Careful consideration should be given to 460 selection of authentication methods when a firewall is 461 expected to relay UDP data using this protocol. 463 9. References 465 [1] Koblas, D., "SOCKS", Proceedings: 1992 Usenix Secu- 466 rity Symposium 468 [2] Rivest, Ron. RFC1321, "The MD5 Message-Digest Algo- 469 rithm" 471 [3] FIPS180-1, "Secure Hash Standard", NIST Publication 473 Authors Address 475 Marcus Leech 476 Bell-Northern Research 477 P.O. Box 3511, Stn. C, 478 Ottawa, ON 479 CANADA K1Y 4H7 481 Email: mleech@bnr.ca 482 Phone: (613) 763-9145