idnits 2.17.1 draft-olteanu-intarea-socks-6-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC3849-compliant IPv6 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 13, 2020) is 1381 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- == Outdated reference: A later version (-13) exists of draft-ietf-tls-dtls-connection-id-07 == Outdated reference: A later version (-18) exists of draft-ietf-tls-esni-07 -- Obsolete informational reference (is this intentional?): RFC 6824 (Obsoleted by RFC 8684) Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Area Working Group V. Olteanu 3 Internet-Draft D. Niculescu 4 Intended status: Experimental University Politehnica of Bucharest 5 Expires: January 14, 2021 July 13, 2020 7 SOCKS Protocol Version 6 8 draft-olteanu-intarea-socks-6-10 10 Abstract 12 The SOCKS protocol is used primarily to proxy TCP connections to 13 arbitrary destinations via the use of a proxy server. Under the 14 latest version of the protocol (version 5), it takes 2 RTTs (or 3, if 15 authentication is used) before data can flow between the client and 16 the server. 18 This memo proposes SOCKS version 6, which reduces the number of RTTs 19 used, takes full advantage of TCP Fast Open, and adds support for 20 0-RTT authentication. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at https://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on January 14, 2021. 39 Copyright Notice 41 Copyright (c) 2020 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (https://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.1. Revision log . . . . . . . . . . . . . . . . . . . . . . 4 58 2. Requirements language . . . . . . . . . . . . . . . . . . . . 10 59 3. Mode of operation . . . . . . . . . . . . . . . . . . . . . . 10 60 4. Requests . . . . . . . . . . . . . . . . . . . . . . . . . . 12 61 5. Version Mismatch Replies . . . . . . . . . . . . . . . . . . 14 62 6. Authentication Replies . . . . . . . . . . . . . . . . . . . 14 63 7. Operation Replies . . . . . . . . . . . . . . . . . . . . . . 15 64 7.1. Handling CONNECT . . . . . . . . . . . . . . . . . . . . 17 65 7.2. Handling BIND . . . . . . . . . . . . . . . . . . . . . . 17 66 7.3. Handling UDP ASSOCIATE . . . . . . . . . . . . . . . . . 17 67 7.3.1. Proxying UDP servers . . . . . . . . . . . . . . . . 20 68 7.3.2. Proxying multicast traffic . . . . . . . . . . . . . 20 69 7.3.3. Reporting ICMP Errors . . . . . . . . . . . . . . . . 20 70 8. SOCKS Options . . . . . . . . . . . . . . . . . . . . . . . . 22 71 8.1. Stack options . . . . . . . . . . . . . . . . . . . . . . 22 72 8.1.1. IP TOS options . . . . . . . . . . . . . . . . . . . 24 73 8.1.2. Happy Eyeballs options . . . . . . . . . . . . . . . 24 74 8.1.3. TTL options . . . . . . . . . . . . . . . . . . . . . 25 75 8.1.4. No Fragmentaion options . . . . . . . . . . . . . . . 25 76 8.1.5. TFO options . . . . . . . . . . . . . . . . . . . . . 25 77 8.1.6. Multipath options . . . . . . . . . . . . . . . . . . 26 78 8.1.7. Listen Backlog options . . . . . . . . . . . . . . . 27 79 8.1.8. UDP Error options . . . . . . . . . . . . . . . . . . 28 80 8.1.9. Port Parity options . . . . . . . . . . . . . . . . . 28 81 8.2. Authentication Method options . . . . . . . . . . . . . . 29 82 8.3. Authentication Data options . . . . . . . . . . . . . . . 31 83 8.4. Session options . . . . . . . . . . . . . . . . . . . . . 31 84 8.4.1. Session initiation . . . . . . . . . . . . . . . . . 32 85 8.4.2. Further SOCKS Requests . . . . . . . . . . . . . . . 33 86 8.4.3. Tearing down the session . . . . . . . . . . . . . . 33 87 8.5. Idempotence options . . . . . . . . . . . . . . . . . . . 34 88 8.5.1. Requesting a token window . . . . . . . . . . . . . . 34 89 8.5.2. Spending a token . . . . . . . . . . . . . . . . . . 35 90 8.5.3. Shifting windows . . . . . . . . . . . . . . . . . . 37 91 8.5.4. Out-of-order Window Advertisements . . . . . . . . . 37 92 9. Username/Password Authentication . . . . . . . . . . . . . . 37 93 10. TCP Fast Open on the Client-Proxy Leg . . . . . . . . . . . . 38 94 11. False Starts . . . . . . . . . . . . . . . . . . . . . . . . 38 95 12. DNS provided by SOCKS . . . . . . . . . . . . . . . . . . . . 39 96 13. Security Considerations . . . . . . . . . . . . . . . . . . . 39 97 13.1. Large requests . . . . . . . . . . . . . . . . . . . . . 39 98 13.2. Replay attacks . . . . . . . . . . . . . . . . . . . . . 40 99 13.3. Resource exhaustion . . . . . . . . . . . . . . . . . . 40 100 14. Privacy Considerations . . . . . . . . . . . . . . . . . . . 40 101 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 40 102 16. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 41 103 17. References . . . . . . . . . . . . . . . . . . . . . . . . . 42 104 17.1. Normative References . . . . . . . . . . . . . . . . . . 42 105 17.2. Informative References . . . . . . . . . . . . . . . . . 42 106 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 43 108 1. Introduction 110 Versions 4 and 5 [RFC1928] of the SOCKS protocol were developed two 111 decades ago and are in widespread use for circuit level gateways or 112 as circumvention tools, and enjoy wide support and usage from various 113 software, such as web browsers, SSH clients, and proxifiers. 114 However, their design needs an update in order to take advantage of 115 the new features of transport protocols, such as TCP Fast Open 116 [RFC7413], or to better assist newer transport protocols, such as 117 MPTCP [RFC6824]. 119 One of the main issues faced by SOCKS version 5 is that, when taking 120 into account the TCP handshake, method negotiation, authentication, 121 connection request and grant, it may take up to 5 RTTs for a data 122 exchange to take place at the application layer. This is especially 123 costly in networks with a large delay at the access layer, such as 124 3G, 4G, or satelite. 126 The desire to reduce the number of RTTs manifests itself in the 127 design of newer security protocols. TLS version 1.3 [RFC8446] 128 defines a zero round trip (0-RTT) handshake mode for connections if 129 the client and server had previously communicated. 131 TCP Fast Open [RFC7413] is a TCP option that allows TCP to send data 132 in the SYN and receive a response in the first ACK, and aims at 133 obtaining a data response in one RTT. The SOCKS protocol needs to 134 concern itself with at least two TFO deployment scenarios: First, 135 when TFO is available end-to-end (at the client, at the proxy, and at 136 the server); second, when TFO is active between the client and the 137 proxy, but not at the server. 139 This document describes the SOCKS protocol version 6. The key 140 improvements over SOCKS version 5 are: 142 o The client sends as much information upfront as possible, and does 143 not wait for the authentication process to conclude before 144 requesting the creation of a socket. 146 o The connection request also mimics the semantics of TCP Fast Open 147 [RFC7413]. As part of the connection request, the client can 148 supply the potential payload for the initial SYN that is sent out 149 to the server. 151 o The protocol can be extended via options without breaking 152 backward-compatibility. 154 o The protocol can leverage the aforementioned options to support 155 0-RTT authentication schemes. 157 1.1. Revision log 159 Typos and minor clarifications are not listed. 161 draft-10 163 o Removed untrusted sessions 165 o IP DF 167 o UDP relay: 169 * Support ICMPv6 Too Big 171 * Shifted some fields in the error messages 173 * RTP support 175 draft-09 177 o Revamped UDP relay 179 * Support for ICMP errors: host/net unreachable, TTL exceeded 181 * Datagrams can be sent over TCP 183 * Timeout for the receipt of the initial datagram 185 o TTL stack option (intended use: traceroute) 187 o Added the "Privacy Considerations" section 189 o SOCKS-provided DNS: the proxy may provide a valid bind address and 190 port 192 draft-08 193 o Removed Address Resolution options 195 o Happy Eyeballs options 197 o DNS provided by SOCKS 199 draft-07 201 o All fields are now alignned. 203 o Eliminated version minors 205 o Lots of changes to options 207 * 2-byte option kinds 209 * Flattened option kinds/types/reply codes; also renamed some 210 options 212 * Socket options 214 + Proxies MUST always answer them (Clients can probe for 215 support) 217 + MPTCP Options: expanded functionality ("please do/don't do 218 MPTCP on my behalf") 220 + MPTCP Scheduler options removed 222 + Listen Backlog options: code changed to 0x03 224 * Revamped Idempotence options 226 * Auth data options limited to one per method 228 o Authentication Reply: all authentication-related information is 229 now in the options 231 * Authentication replies no longer have a field indicating the 232 chosen auth. method 234 * Method that must proceed (or whereby authentication succeeded) 235 indicated in options 237 * Username/password authentication: proxy now sends reply in 238 option 240 o Removed requirements w.r.t. caching authentication methods by 241 multihomed clients 243 o UDP: 8-byte association IDs 245 o Sessions 247 * The proxy is now free to terminate ongoing connections along 248 with the session. 250 * The session-terminating request is not part of the session that 251 it terminated. 253 o Address Resolution options 255 draft-06 257 o Session options 259 o Options now have a 2-byte length field. 261 o Stack options 263 * Stack options can no longer contain duplicate information. 265 * TFO: Better payload size semantics 267 * TOS: Added missing code field. 269 * MPTCP Scheduler options: 271 + Removed support for round-robin 273 + "Default" renamed to "Lowest latency first" 275 * Listen Backlog options: now tied to sessions, instead of an 276 authenticated user 278 o Idempotence options 280 * Now used in the context of a session (no longer tied to an 281 authenticated user) 283 * Idempotence options have a different codepoint: 0x05. (Was 284 0x04.) 286 * Clarified that implementations that support Idempotence Options 287 must support all Idempotence Option Types. 289 * Shifted Idempotence Option Types by 1. (Makes implementation 290 easier.) 292 o Shrunk vendor-specific option range to 32 (down from 64). 294 o Removed reference to dropping initial data. (It could no longer 295 be done as of -05.) 297 o Initial data size capped at 16KB. 299 o Application data is never encrypted by SOCKS 6. (It can still be 300 encrypted by the TLS layer under SOCKS.) 302 o Messages now carry the total length of the options, rather than 303 the number of options. Limited options length to 16KB. 305 o Security Considerations 307 * Updated the section to reflect the smaller maximum message 308 size. 310 * Added a subsection on resource exhaustion. 312 draft-05 314 o Limited the "slow" authentication negociations to one (and 315 Authentication Replies to 2) 317 o Revamped the handling of the first bytes in the application data 318 stream 320 * False starts are now recommended. (Added the "False Start" 321 section.) 323 * Initial data is only available to clients willing to do "slow" 324 authentication. Moved the "Initial data size" field from 325 Requests to Authentication Method options. 327 * Initial data size capped at 2^13. Initial data can no longer 328 be dropped by the proxy. 330 * The TFO option can hint at the desired SYN payload size. 332 o Request: clarified the meaning of the Address and Port fields. 334 o Better reverse TCP proxy support: optional listen backlog for TCP 335 BIND 337 o TFO options can no longer be placed inside Operation Replies. 339 o IP TOS stack option 341 o Suggested a range for vendor-specific options. 343 o Revamped UDP functionality 345 * Now using fixed UDP ports 347 * DTLS support 349 o Stack options: renamed Proxy-Server leg to Proxy-Remote leg 351 draft-04 353 o Moved Token Expenditure Replies to the Authentication Reply. 355 o Shifted the Initial Data Size field in the Request, in order to 356 make it easier to parse. 358 draft-03 360 o Shifted some fields in the Operation Reply to make it easier to 361 parse. 363 o Added connection attempt timeout response code to Operation 364 Replies. 366 o Proxies send an additional Authentication Reply after the 367 authentication phase. (Useful for token window advertisements.) 369 o Renamed the section "Connection Requests" to "Requests" 371 o Clarified the fact that proxies don't need to support any command 372 in particular. 374 o Added the section "TCP Fast Open on the Client-Proxy Leg" 376 o Options: 378 * Added constants for option kinds 380 * Salt options removed, along with the relevant section from 381 Security Considerations. (TLS 1.3 Makes AEAD mandatory.) 383 * Limited Authentication Data options to one per method. 385 * Relaxed proxy requirements with regard to handling multiple 386 Authentication Data options. (When the client violates the 387 above bullet point.) 389 * Removed interdependence between Authentication Method and 390 Authentication Data options. 392 * Clients SHOULD omit advertising the "No authentication 393 required" option. (Was MAY.) 395 * Idempotence options: 397 + Token Window Advertisements are now part of successful 398 Authentication Replies (so that the proxy-server RTT has no 399 impact on their timeliness). 401 + Proxies can't advetise token windows of size 0. 403 + Tweaked token expenditure response codes. 405 + Support no longer mandatory on the proxy side. 407 * Revamped Socket options 409 + Renamed Socket options to Stack options. 411 + Banned contradictory socket options. 413 + Added socket level for generic IP. Removed the "socket" 414 socket level. 416 + Stack options no longer use option codes from setsockopt(). 418 + Changed MPTCP Scheduler constants. 420 draft-02 422 o Made support for Idempotence options mandatory for proxies. 424 o Clarified what happens when proxies can not or will not issue 425 tokens. 427 o Limited token windows to 2^31 - 1. 429 o Fixed definition of "less than" for tokens. 431 o NOOP commands now trigger Operation Replies. 433 o Renamed Authentication options to Authentication Data options. 435 o Authentication Data options are no longer mandatory. 437 o Authentication methods are now advertised via options. 439 o Shifted some Request fields. 441 o Option range for vendor-specific options. 443 o Socket options. 445 o Password authentication. 447 o Salt options. 449 draft-01 451 o Added this section. 453 o Support for idempotent commands. 455 o Removed version numbers from operation replies. 457 o Request port number for SOCKS over TLS. Deprecate encryption/ 458 encapsulation within SOCKS. 460 o Added Version Mismatch Replies. 462 o Renamed the AUTH command to NOOP. 464 o Shifted some fields to make requests and operation replies easier 465 to parse. 467 2. Requirements language 469 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 470 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 471 document are to be interpreted as described in [RFC2119]. 473 3. Mode of operation 474 CLIENT PROXY 476 +------------------------+ 477 | Authentication methods | Request 478 --------> Command code +------------------------------> 479 | Address | 480 | Port | 481 | Options | 482 +------------------------+ 484 +------------------------+ 485 --------> Initial data +------------------------------> 486 +------------------------+ 488 +-----------------------+ 489 Authentication Reply | Type | 490 <----------------------------------+ Options <----- 491 +-----------------------+ 493 <-------------------(Authentication protocol)------------------> 495 +-----------------------+ 496 Authentication Reply | Type = Success | 497 <----------------------------------+ Options <----- 498 +-----------------------+ 500 +-----------------------+ 501 Operation Reply | Reply code | 502 <--------------------+ Bind address <------------------ 503 | Bind port | 504 | Options | 505 +-----------------------+ 507 Figure 1: The SOCKS version 6 protocol message exchange 509 When a TCP-based client wishes to establish a connection to a server, 510 it must open a TCP connection to the appropriate SOCKS port on the 511 SOCKS proxy. The client then enters a negotiation phase, by sending 512 the request in Figure 1, that contains, in addition to fields present 513 in SOCKS 5 [RFC1928], fields that facilitate low RTT usage and faster 514 authentication negotiation. 516 Next, the server sends an authentication reply. If the request did 517 not contain the necessary authentication information, the proxy 518 indicates an authentication method that must proceed. This may 519 trigger a longer authentication sequence that could include tokens 520 for ulterior faster authentications. The part labeled 521 "Authentication protocol" is specific to the authentication method 522 employed and is not expected to be employed for every connection 523 between a client and its proxy server. The authentication protocol 524 typically takes up 1 RTT or more. 526 If the authentication is successful, an operation reply is generated 527 by the proxy. It indicates whether the proxy was successful in 528 creating the requested socket or not. 530 In the fast case, when authentication is properly set up, the proxy 531 attempts to create the socket immediately after the receipt of the 532 request, thus achieving an operational conection in one RTT (provided 533 TFO functionality is available at the client, proxy, and server). 535 4. Requests 537 The client starts by sending a request to the proxy. 539 1 2 3 540 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 541 +---------------+---------------+-------------------------------+ 542 | Version = 6 | Command Code | Options Length | 543 +---------------+---------------+---------------+---------------+ 544 | Port | Padding = 0 | Address Type | 545 +-------------------------------+---------------+---------------+ 546 | ... 547 ... Address (variable length) ... 548 ... | 549 +---------------------------------------------------------------+ 550 | ... 551 ... Options (variable length) ... 552 ... | 553 +---------------------------------------------------------------+ 555 Figure 2: SOCKS 6 Request 557 o Version: 6 559 o Command Code: 561 * 0x00 NOOP: does nothing. 563 * 0x01 CONNECT: requests the establishment of a TCP connection. 564 TFO MUST NOT be used unless explicitly requested. 566 * 0x02 BIND: requests the establishment of a TCP port binding. 568 * 0x03 UDP ASSOCIATE: requests a UDP port association. 570 o Address Type: 572 * 0x01: IPv4 574 * 0x03: Domain Name 576 * 0x04: IPv6 578 o Address: this field's format depends on the address type: 580 * IPv4: a 4-byte IPv4 address 582 * Domain Name: one byte that contains the length of the FQDN, 583 followed by the FQDN itself. The string is not NUL-terminated, 584 but padded by NUL characters, if needed. 586 * IPv6: a 16-byte IPv6 address 588 o Port: the port in network byte order. 590 o Padding: set to 0 592 o Options Length: the total size of the SOCKS options that appear in 593 the Options field. MUST NOT exceed 16KB. 595 o Options: see Section 8. 597 The Address and Port fields have different meanings based on the 598 Command Code: 600 o NOOP: The fields have no meaning. The Address Type field MUST be 601 either 0x01 (IPv4) or 0x04 (IPv6). The Address and Port fields 602 MUST be 0. 604 o CONNECT: The fields signify the address and port to which the 605 client wishes to connect. 607 o BIND, UDP ASSOCIATE: The fields indicate the desired bind address 608 and port. If the client does not require a certain address, it 609 can set the Address Type field to 0x01 (IPv4) or 0x04 (IPv6), and 610 the Address field to 0. Likewise, if the client does not require 611 a certain port, it can set the Port field to 0. 613 Clients can advertise their supported authentication methods by 614 including an Authentication Method Advertisement option (see 615 Section 8.2). 617 5. Version Mismatch Replies 619 Upon receipt of a request starting with a version number other than 620 6, the proxy sends the following response: 622 0 1 2 3 4 5 6 7 623 +---------------+ 624 | Version = 6 | 625 +---------------+ 627 Figure 3: SOCKS 6 Version Mismatch Reply 629 o Version: 6 631 A client MUST close the connection after receiving such a reply. 633 6. Authentication Replies 635 Upon receipt of a valid request, the proxy sends an Authentication 636 Reply: 638 1 2 3 639 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 640 +---------------+---------------+-------------------------------+ 641 | Version = 6 | Type | Options Length | 642 +---------------+---------------+-------------------------------+ 643 | ... 644 ... Options (variable length) ... 645 ... | 646 +---------------------------------------------------------------+ 648 Figure 4: SOCKS 6 Authentication Reply 650 o Version: 6 652 o Type: 654 * 0x00: authentication successful. 656 * 0x01: authentication failed. 658 o Options Length: the total size of the SOCKS options that appear in 659 the Options field. MUST NOT exceed 16KB. 661 o Options: see Section 8. 663 If the server signals that the authentication has failed and does not 664 signal that any authentication negotiation can continue (via an 665 Authentication Method Selection option), the client MUST close the 666 connection. 668 The client and proxy begin a method-specific negotiation. During 669 such negotiations, the proxy MAY supply information that allows the 670 client to authenticate a future request using an Authentication Data 671 option. Application data is not subject to any encryption negotiated 672 during this phase. Descriptions of such negotiations are beyond the 673 scope of this memo. 675 When the negotiation is complete (either successfully or 676 unsuccessfully), the proxy sends a second Authentication Reply. The 677 second Authentication Reply MUST NOT allow for further negotiations. 679 7. Operation Replies 681 After the authentication negotiations are complete, the proxy sends 682 an Operation Reply: 684 1 2 3 685 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 686 +---------------+---------------+-------------------------------+ 687 | Version = 6 | Reply Code | Options Length | 688 +---------------+---------------+---------------+---------------+ 689 | Bind Port | Padding = 0 | Address Type | 690 +-------------------------------+---------------+---------------+ 691 | ... 692 ... Bind Address (variable length) ... 693 ... | 694 +---------------------------------------------------------------+ 695 | ... 696 ... Options (variable length) ... 697 ... | 698 +---------------------------------------------------------------+ 700 Figure 5: SOCKS 6 Operation Reply 702 o Version: 6 704 o Reply Code: 706 * 0x00: Succes 708 * 0x01: General SOCKS server failure 709 * 0x02: Connection not allowed by ruleset 711 * 0x03: Network unreachable 713 * 0x04: Host unreachable 715 * 0x05: Connection refused 717 * 0x06: TTL expired 719 * 0x07: Command not supported 721 * 0x08: Address type not supported 723 * 0x09: Connection attempt timed out 725 o Bind Port: the proxy bound port in network byte order. 727 o Padding: set to 0 729 o Address Type: 731 * 0x01: IPv4 733 * 0x03: Domain Name 735 * 0x04: IPv6 737 o Bind Address: the proxy bound address in the following format: 739 * IPv4: a 4-byte IPv4 address 741 * Domain Name: one byte that contains the length of the FQDN, 742 followed by the FQDN itself. The string is not NUL-terminated, 743 but padded by NUL characters, if needed. 745 * IPv6: a 16-byte IPv6 address 747 o Options Length: the total size of the SOCKS options that appear in 748 the Options field. MUST NOT exceed 16KB. 750 o Options: see Section 8. 752 Proxy implementations MAY support any subset of the client commands 753 listed in Section 4. 755 If the proxy returns a reply code other than "Success", the client 756 MUST close the connection. 758 If the client issued an NOOP command, the client MUST close the 759 connection after receiving the Operation Reply. 761 7.1. Handling CONNECT 763 In case the client has issued a CONNECT request, data can now pass. 765 7.2. Handling BIND 767 In case the client has issued a BIND request, it must wait for a 768 second Operation reply from the proxy, which signifies that a host 769 has connected to the bound port. The Bind Address and Bind Port 770 fields contain the address and port of the connecting host. 771 Afterwards, application data may pass. 773 7.3. Handling UDP ASSOCIATE 775 Proxies offering UDP functionality may be configured with a UDP port 776 used for relaying UDP datagrams to and from the client, and/or a port 777 used for relaying datagrams over DTLS. 779 Following a successful Operation Reply, the client and the proxy 780 begin exchanging messages with the following header: 782 1 2 3 783 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 784 +---------------+---------------+-------------------------------+ 785 | Version = 6 | Message Type | Message Length | 786 +---------------+---------------+-------------------------------+ 787 | Association ID | 788 | (8 bytes) | 789 +---------------------------------------------------------------+ 791 Figure 6: UDP Association Header 793 o Message Type: 795 * 0x01: Association Initialization 797 * 0x02: Association Confirmation 799 * 0x03: Datagram 801 * 0x04: Error 803 o Message Length: the total length of the message 804 o Association ID: the identifier of the UDP association 806 First, the proxy picks an Association ID sends a an Association 807 Initialization message: 809 1 2 3 810 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 811 +---------------+---------------+-------------------------------+ 812 | Version = 6 | 0x01 | Message Length = 12 | 813 +---------------+---------------+-------------------------------+ 814 | Association ID | 815 | (8 bytes) | 816 +---------------------------------------------------------------+ 818 Figure 7: UDP Association Initialization 820 Proxy implementations SHOULD generate Association IDs randomly or 821 pseudo-randomly. 823 Clients may start sending datagrams to the proxy either: 825 o over the TCP connection, 827 o in plaintext, using the proxy's configured UDP port(s), or 829 o over an established DTLS session. 831 A client's datagrams are prefixed by a Datagram Header, indicating 832 the remote host's address and port: 834 1 2 3 835 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 836 +---------------+---------------+-------------------------------+ 837 | Version = 6 | 0x03 | Message Length | 838 +---------------+---------------+-------------------------------+ 839 | Association ID | 840 | (8 bytes) | 841 +---------------+---------------+-------------------------------+ 842 | Address Type | Padding = 0 | Port | 843 +---------------+---------------+-------------------------------+ 844 | ... 845 ... Address (variable length) ... 846 ... | 847 +---------------------------------------------------------------+ 849 Figure 8: Datagram Header 851 o Version: 0x06 853 o Association ID: the identifier of the UDP association 855 o Address Type: 857 * 0x01: IPv4 859 * 0x03: Domain Name 861 * 0x04: IPv6 863 o Address: this field's format depends on the address type: 865 * IPv4: a 4-byte IPv4 address 867 * Domain Name: one byte that contains the length of the FQDN, 868 followed by the FQDN itself. The string is not NUL-terminated. 870 * IPv6: a 16-byte IPv6 address 872 o Port: the port in network byte order. 874 Datagrams sent over UDP MAY be padded with arbitrary data (i. e., the 875 Message Length MAY be smaller than the actual UDP/DTLS payload). 876 Client and proxy implementations MUST ignore the padding. If the 877 Message Length is larger than the size of the UDP or DTLS payload, 878 the message MUST be silently ignored. 880 Following the receipt of the first datagram from the client, the 881 proxy makes a one-way mapping between the Association ID and: 883 o the TCP connection, if it was received over TCP, or 885 o the 5-tuple of the UDP conversation, if the datagram was received 886 over plain UDP, or 888 o the DTLS connection, if the datagram was received over DTLS. The 889 DTLS connection is identified either by its 5-tuple, or some other 890 mechanism, like [I-D.ietf-tls-dtls-connection-id]. 892 The proxy SHOULD close the TCP connection if the initial datagram is 893 not received after a timeout. 895 Further datagrams carrying the same Association ID, but not matching 896 the established mapping, are silently dropped. 898 The proxy then sends an UDP Association Confirmation message over the 899 TCP connection with the client: 901 1 2 3 902 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 903 +---------------+---------------+-------------------------------+ 904 | Version = 6 | 0x02 | Message Length = 12 | 905 +---------------+---------------+-------------------------------+ 906 | Association ID | 907 | (8 bytes) | 908 +---------------------------------------------------------------+ 910 Figure 9: UDP Association Confirmation 912 Following the confirmation message, UDP packets bound for the proxy's 913 bind address and port are relayed to the client, also prefixed by a 914 Datagram Header. 916 The UDP association remains active for as long as the TCP connection 917 between the client and the proxy is kept open. 919 7.3.1. Proxying UDP servers 921 Under some circumstances (e.g. when hosting a server), the SOCKS 922 client expects the remote host to send UDP datagrams first. As such, 923 the SOCKS client must trigger a UDP Association Confirmation without 924 having the proxy relay any datagrams on its behalf. 926 To that end, it sends an empty datagram prefixed by a Datagram Header 927 with an IP address and port consisting of zeroes. If it is using 928 UDP, the client SHOULD resend the empty datagram if an UDP 929 Association Confirmation is not received after a timeout. 931 7.3.2. Proxying multicast traffic 933 The use of multicast addessses is permitted for UDP traffic only. 935 7.3.3. Reporting ICMP Errors 937 If a client has opted in (see Section 8.1.8), the proxy MAY relay 938 information contained in some ICMP Error packets. The message format 939 is as follows: 941 1 2 3 942 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 943 +---------------+---------------+-------------------------------+ 944 | Version = 6 | 0x04 | Message Length | 945 +---------------+---------------+-------------------------------+ 946 | Association ID | 947 | (8 bytes) | 948 +---------------+---------------+-------------------------------+ 949 | Address Type | Padding = 0 | Port | 950 +---------------+---------------+-------------------------------+ 951 | ... 952 ... Address (variable length) ... 953 ... | 954 +---------------+---------------+-------------------------------+ 955 | Reporter ATYP | Error Code | Padding = 0 | 956 +---------------+---------------+-------------------------------+ 957 | ... 958 ... Reporter Address (variable length) ... 959 ... | 960 +---------------------------------------------------------------+ 962 Figure 10: Datagram Error Message 964 o Address: The destination address of the IP header contained in the 965 ICMP payload 967 o Address Type: Either 0x01 (IPv4) or 0x04 (IPv6) 969 o Port: The destination port of the UDP header contained in the ICMP 970 payload 972 o Reporter Address: The IP address of the host that issued the ICMP 973 error 975 o Reporter Address Type (ATYP): Either 0x01 (IPv4) or 0x04 (IPv6) 977 o Error code: 979 * 0x01: Network unreachable 981 * 0x02: Host unreachable 983 * 0x03: TTL expired 985 * 0x04: Datagram too big (IPv6 only) 987 It is possible for ICMP Error packets to be spurious, and not be 988 related to any UDP packet that was sent out. The proxy is not 989 required to check the validity of ICMP Error packets before reporting 990 them to the client. 992 Clients MUST NOT send Datagram Error messages to the proxy. Proxies 993 MUST NOT send Error messages unless the clients have opted in. 995 8. SOCKS Options 997 SOCKS options have the following format: 999 1 2 3 1000 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1001 +-------------------------------+-------------------------------+ 1002 | Kind | Length | 1003 +-------------------------------+-------------------------------+ 1004 | ... 1005 ... Option Data (variable length) ... 1006 ... | 1007 +---------------------------------------------------------------+ 1009 Figure 11: SOCKS 6 Option 1011 o Kind: Allocated by IANA. (See Section 15.) 1013 o Length: The total length of the option. MUST be a multiple of 4. 1015 o Option Data: The contents are specific to each option kind. 1017 Unless otherwise noted, client and proxy implementations MAY omit 1018 supporting any of the options described in this document. Upon 1019 encountering an unsupported option, a SOCKS endpoint MUST silently 1020 ignore it. 1022 8.1. Stack options 1024 Stack options can be used by clients to alter the behavior of the 1025 protocols on top of which SOCKS is running, as well the protcols used 1026 by the proxy to communicate with the remote host (i.e. IP, TCP, 1027 UDP). A Stack option can affect either the proxy's protocol on the 1028 client-proxy leg or on the proxy-remote leg. Clients can only place 1029 Stack options inside SOCKS Requests. 1031 Proxies MAY choose not to honor any Stack options sent by the client. 1033 Proxies include Stack options in their Operation Replies to signal 1034 their behavior, and MUST do so for every supported Stack option sent 1035 by the client. Said options MAY also be unsolicited, i. e. the proxy 1036 MAY send them to signal behaviour that was not explicitly requested 1037 by the client. 1039 If a particular Stack option is unsupported, the proxy MUST silently 1040 ignore it. 1042 In case of UDP ASSOCIATE, the stack options refer to the UDP traffic 1043 relayed by the proxy. 1045 Stack options that are part of the same message MUST NOT contradict 1046 one another or contain duplicate information. 1048 1 2 3 1049 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1050 +-------------------------------+-------------------------------+ 1051 | Kind = 1 | Length | 1052 +---+-----------+---------------+-------------------------------+ 1053 |Leg| Level | Code | ... 1054 +---+-----------+---------------+ ... 1055 ... ... 1056 ... Option Data (variable length) ... 1057 ... | 1058 +---------------------------------------------------------------+ 1060 Figure 12: Stack Option 1062 o Leg: 1064 * 1: Client-Proxy Leg 1066 * 2: Proxy-Remote Leg 1068 * 3: Both Legs 1070 o Level: 1072 * 1: IP: options that apply to either IPv4 or IPv6 1074 * 2: IPv4 1076 * 3: IPv6 1078 * 4: TCP 1079 * 5: UDP 1081 o Code: Option code 1083 o Option Data: Option-specific data 1085 8.1.1. IP TOS options 1087 1 2 3 1088 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1089 +-------------------------------+-------------------------------+ 1090 | Kind = 1 | Length = 8 | 1091 +---+-----------+---------------+---------------+---------------+ 1092 |Leg| Level = 1 | Code = 1 | TOS | Padding = 0 | 1093 +---+-----------+---------------+---------------+---------------+ 1095 Figure 13: IP TOS Option 1097 o TOS: The IP TOS code 1099 The client can use IP TOS options to request that the proxy use a 1100 certain value for the IP TOS field. Likewise, the proxy can use IP 1101 TOS options to advertise the TOS values being used. 1103 8.1.2. Happy Eyeballs options 1105 1 2 3 1106 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1107 +-------------------------------+-------------------------------+ 1108 | Kind = 1 | Length = 8 | 1109 +---+-----------+---------------+-------------------------------+ 1110 | 2 | Level = 1 | Code = 2 | Padding = 0 | 1111 +---+-----------+---------------+-------------------------------+ 1113 Figure 14: Happy Eyeballs Option 1115 This memo provides enough features for clients to implement a 1116 mechanism analogous to Happy Eyeballs [RFC8305] over SOCKS. However, 1117 when the delay between the client and the proxy, or the proxy's 1118 vantage point, is high, doing so can become impractical or 1119 inefficient. 1121 In such cases, the client can instruct the proxy to employ the Happy 1122 Eyeballs technique on its behalf when connecting to a remote host. 1124 The client MUST supply a Domain Name as part of its Request. 1125 Otherwise, the proxy MUST silently ignore the option. 1127 TODO: Figure out which knobs to include. 1129 8.1.3. TTL options 1131 1 2 3 1132 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1133 +-------------------------------+-------------------------------+ 1134 | Kind = 1 | Length = 8 | 1135 +---+-----------+---------------+---------------+---------------+ 1136 |Leg| Level = 1 | Code = 3 | TTL | Padding = 0 | 1137 +---+-----------+---------------+---------------+---------------+ 1139 Figure 15: IP TTL Option 1141 o TTL: The IP TTL or Hop Limit 1143 8.1.4. No Fragmentaion options 1145 1 2 3 1146 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1147 +-------------------------------+-------------------------------+ 1148 | Kind = 1 | Length = 8 | 1149 +---+-----------+---------------+-------------------------------+ 1150 |Leg| Level = 1 | Code = 4 | Padding = 0 | 1151 +---+-----------+---------------+-------------------------------+ 1153 Figure 16: No Fragmentaion Option 1155 A No Fragmentation option instructs the proxy to avoid IP 1156 fragmentation. In the case of IPv4, this also entails setting the DF 1157 bit on outgoing packets. 1159 8.1.5. TFO options 1160 1 2 3 1161 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1162 +-------------------------------+-------------------------------+ 1163 | Kind = 1 | Length = 8 | 1164 +---+-----------+---------------+-------------------------------+ 1165 | 2 | Level = 4 | Code = 1 | Payload Size | 1166 +---+-----------+---------------+-------------------------------+ 1168 Figure 17: TFO Option 1170 o Payload Size: The desired payload size of the TFO SYN. Ignored in 1171 case of a BIND command. 1173 If a SOCKS Request contains a TFO option, the proxy SHOULD attempt to 1174 use TFO in case of a CONNECT command, or accept TFO in case of a BIND 1175 command. Otherwise, the proxy MUST NOT attempt to use TFO in case of 1176 a CONNECT command, or accept TFO in case of a BIND command. 1178 In case of a CONNECT command, the client can indicate the desired 1179 payload size of the SYN. If the field is 0, the proxy can use an 1180 arbitrary payload size. If the field is non-zero, the proxy MUST NOT 1181 use a payload size larger than the one indicated. The proxy MAY use 1182 a smaller payload size than the one indicated. 1184 8.1.6. Multipath options 1186 In case of a CONNECT or BIND command, the client can inform the proxy 1187 whether MPTCP is desired on the proxy-remote leg by sending a 1188 Multipath option. 1190 Conversely, the proxy can use a Multipath option to convey the 1191 following information: 1193 o whether or not the connection uses MPTCP or not, when replying to 1194 a CONNECT command, or in the second Operation reply to a BIND 1195 command, or 1197 o whether an MPTCP connection will be accepted, when first replying 1198 to a BIND command. 1200 1 2 3 1201 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1202 +-------------------------------+-------------------------------+ 1203 | Kind = 1 | Length = 8 | 1204 +---+-----------+---------------+---------------+---------------+ 1205 | 2 | Level = 4 | Code = 2 | Availability | Padding = 0 | 1206 +---+-----------+---------------+---------------+---------------+ 1208 Figure 18: Multipath Option 1210 o Availability: 1212 * 0x01: MPTCP is not desired or available 1214 * 0x02: MPTCP is desired or available 1216 In the absence of such an option, the proxy SHOULD NOT enable MPTCP. 1218 8.1.7. Listen Backlog options 1220 1 2 3 1221 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1222 +-------------------------------+-------------------------------+ 1223 | Kind = 1 | Length = 8 | 1224 +---+-----------+---------------+-------------------------------+ 1225 | 2 | Level = 4 | Code = 3 | Backlog | 1226 +---+-----------+---------------+-------------------------------+ 1228 Figure 19: Listen Backlog Option 1230 o Backlog: The length of the listen backlog. 1232 The default behavior of the BIND does not allow a client to 1233 simultaneously handle multiple connections to the same bind address. 1234 A client can alter BIND's behavior by adding a TCP Listen Backlog 1235 Option to a BIND Request, provided that the Request is part of a 1236 Session. 1238 In response, the proxy sends a TCP Listen Backlog Option as part of 1239 the Operation Reply, with the Backlog field signalling the actual 1240 backlog used. The proxy SHOULD NOT use a backlog longer than 1241 requested. 1243 Following the successful negotiation of a backlog, the proxy listens 1244 for incoming connections for as long as the initial connection stays 1245 open. The initial connection is not used to relay data between the 1246 client and a remote host. 1248 To accept connections, the client issues further BIND Requests using 1249 the bind address and port supplied by the proxy in the initial 1250 Operation Reply. Said BIND requests must belong to the same Session 1251 as the original Request. 1253 If no backlog is issued, the proxy signals a backlog length of 0, and 1254 BIND's behavior remains unaffected. 1256 8.1.8. UDP Error options 1258 1 2 3 1259 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1260 +-------------------------------+-------------------------------+ 1261 | Kind = 1 | Length = 8 | 1262 +---+-----------+---------------+-------------------------------+ 1263 | 2 | Level = 5 | Code = 1 | Padding = 0 | 1264 +---+-----------+---------------+-------------------------------+ 1266 Figure 20: UDP Error Option 1268 Clients can use this option to turn on error reporting for a 1269 particular UDP association. See Section 7.3.3. 1271 8.1.9. Port Parity options 1273 The RTP specification [RFC3550] recommends runnng the protocol on 1274 consecutive UDP ports, where the even port is the lower of the two. 1276 SOCKS clients can specify the desired port parity when issuing a UDP 1277 ASSOCIATE command, and request that the port's counterpart be 1278 reserved. 1280 1 2 3 1281 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1282 +-------------------------------+-------------------------------+ 1283 | Kind = 1 | Length = 8 | 1284 +---+-----------+---------------+---------------+---------------+ 1285 | 2 | Level = 5 | Code = 2 | Parity | Reserve | 1286 +---+-----------+---------------+---------------+---------------+ 1288 Figure 21: Port Parity Option 1290 o Parity: 1292 * 0x00: Even 1294 * Ox01: Odd 1296 o Reserve: whether or not to reserve the port's counterpart 1298 * 0x00: Don't reserve 1300 * 0x01: Reserve 1302 If the UDP ASSOCIATE request does not have the Port field set to 0 1303 (indicating that an arbitrary port can be chosen), the proxy MUST 1304 silently ignore this option. 1306 A port's counterpart is determined as follows: 1308 o for even ports, it is the next higher port and 1310 o for odd ports, it is the next lower port. 1312 If the proxy can not or will not comply with the requested parity, it 1313 does so silently, and also does not reserve the allocated port's 1314 counterpart. If it can not or will not comply with the reservation 1315 request, the reply MUST have its Reserve field set to 0. 1317 Port reservations are in place until either: 1319 o the original association ends, or 1321 o an association involving the reserved port is made. 1323 An association involving a reserved port can only be made if a client 1324 explicitly requests said port. Further, if the original association 1325 is part of a session (see Section 8.4), the reserved port can only be 1326 claimed from within the same session. 1328 8.2. Authentication Method options 1330 A client that is willing to go through the authentication phase MUST 1331 include an Authentication Method Advertisement option in its Request. 1332 In case of a CONNECT Request, the option is also used to specify the 1333 amount of initial data supplied before any method-specific 1334 authentication negotiations take place. 1336 1 2 3 1337 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1338 +-------------------------------+-------------------------------+ 1339 | Kind = 2 | Length | 1340 +-------------------------------+-------------------------------+ 1341 | Initial Data Length | ... 1342 +-------------------------------+ ... 1343 ... ... 1344 ... Methods (variable length) ... 1345 ... ... 1346 ... +-----------------------------------------------+ 1347 ... | Padding = 0 (variable length, 0-3 bytes) | 1348 +---------------+-----------------------------------------------+ 1350 Figure 22: Authentication Method Advertisement Option 1352 o Initial Data Size: A two-byte number in network byte order. In 1353 case of CONNECT, this is the number of bytes of initial data that 1354 are supplied by the client immediately following the Request. 1355 This number MUST NOT be larger than 2^14. 1357 o Methods: One byte per advertised method. Method numbers are 1358 assigned by IANA. 1360 o Padding: A minimally-sized sequence of zeroes, such that the 1361 option length is a multiple of 4. Note that 0 coincides with the 1362 value for "No Authentication Required". 1364 Clients MUST support the "No authentication required" method. 1365 Clients SHOULD omit advertising the "No authentication required" 1366 option. 1368 The proxy indicates which authentication method must proceed by 1369 sending an Authentication Method Selection option in the 1370 corresponding Authentication Reply: 1372 1 2 3 1373 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1374 +-------------------------------+-------------------------------+ 1375 | Kind = 3 | Length = 8 | 1376 +---------------+---------------+-------------------------------+ 1377 | Method | Padding = 0 | 1378 +---------------+-----------------------------------------------+ 1380 Figure 23: Authentication Method Selection Option 1382 o Method: The selected method. 1384 If the proxy selects "No Acceptable Methods", the client MUST close 1385 the connection. 1387 If authentication is successful via some other means, or not required 1388 at all, the proxy silently ignores the Authentication Method 1389 Advertisement option. 1391 8.3. Authentication Data options 1393 Authentication Data options carry method-specific authentication 1394 data. They can be part of SOCKS Requests and Authentication Replies. 1396 Authentication Data options have the following format: 1398 1 2 3 1399 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1400 +-------------------------------+-------------------------------+ 1401 | Kind = 4 | Length | 1402 +---------------+---------------+-------------------------------+ 1403 | Method | ... 1404 +---------------+ ... 1405 ... ... 1406 ... Authentication Data (variable length) ... 1407 ... | 1408 +---------------------------------------------------------------+ 1410 Figure 24: Authentication Data Option 1412 o Method: The number of the authentication method. These numbers 1413 are assigned by IANA. 1415 o Authentication Data: The contents are specific to each method. 1417 Clients MUST only place one Authentication Data option per 1418 authentication method. 1420 8.4. Session options 1422 Clients and proxies can establish SOCKS sessions, which span one or 1423 more Requests. All session-related negotiations are done via Session 1424 Options, which are placed in Requests and Authentication Replies by 1425 the client and, respectively, by the proxy. 1427 Client and proxy implementations MUST either support all Session 1428 Option Types, or none. 1430 8.4.1. Session initiation 1432 A client can initiate a session by sending a Session Request Option: 1434 1 2 3 1435 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1436 +-------------------------------+-------------------------------+ 1437 | Kind = 5 | Length = 4 | 1438 +-------------------------------+-------------------------------+ 1440 Figure 25: Session Request Option 1442 The proxy then replies with a Session ID Option in the successful 1443 Operation Reply: 1445 1 2 3 1446 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1447 +-------------------------------+-------------------------------+ 1448 | Kind = 6 | Length | 1449 +-------------------------------+-------------------------------+ 1450 | ... 1451 ... Session ID (variable length) ... 1452 ... | 1453 +---------------------------------------------------------------+ 1455 Figure 26: Session ID Option 1457 o Session ID: An opaque sequence of bytes specific to the session. 1458 The size MUST be a multiple of 4. MUST NOT be empty. 1460 The Session ID serves to identify the session and is opaque to the 1461 client. 1463 The credentials, or lack thereof, used to initiate the session are 1464 tied to the session. 1466 The SOCKS Request that initiated the session is considered part of 1467 the session. A client MUST NOT attempt to initiate a session from 1468 within a different session. 1470 If the proxy can not or will not honor the Session Request, it does 1471 so silently. 1473 8.4.2. Further SOCKS Requests 1475 Any further SOCKS Requests that are part of the session MUST include 1476 a Session ID Option (as seen in Figure 26). The proxy MUST silently 1477 ignore any authentication attempt in the Request, and MUST NOT 1478 require any authentication. 1480 The proxy then replies by placing a Session OK option in the 1481 successful Authentication Reply: 1483 1 2 3 1484 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1485 +-------------------------------+-------------------------------+ 1486 | Kind = 8 | Length = 4 | 1487 +-------------------------------+-------------------------------+ 1489 Figure 27: Session OK Option 1491 If the Session ID is invalid, the first Authentication Reply MUST 1492 signal that authentication failed and can not continue (by setting 1493 the Type field to 0x01). Further, it SHALL contain a Session Invalid 1494 option: 1496 1 2 3 1497 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1498 +-------------------------------+-------------------------------+ 1499 | Kind = 9 | Length = 4 | 1500 +-------------------------------+-------------------------------+ 1502 Figure 28: Session Invalid Option 1504 8.4.3. Tearing down the session 1506 Proxies can, at their discretion, tear down a session and free all 1507 associated state. Proxy implementations SHOULD feature a timeout 1508 mechanism that destroys sessions after a period of inactivity. When 1509 a session is terminated, the proxy MAY close all connections 1510 associated with said session. 1512 Clients can signal that a session is no longer needed, and can be 1513 torn down, by sending a Session Teardown option in addition to the 1514 Session ID option: 1516 1 2 3 1517 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1518 +-------------------------------+-------------------------------+ 1519 | Kind = 10 | Length = 4 | 1520 +-------------------------------+-------------------------------+ 1522 Figure 29: Session Teardown Option 1524 After sending such an option, the client MUST assume that the session 1525 is no longer valid. The proxy MUST treat the session-terminating 1526 request as if it were not part of any session. 1528 8.5. Idempotence options 1530 To protect against duplicate SOCKS Requests, clients can request, and 1531 then spend, idempotence tokens. A token can only be spent on a 1532 single SOCKS request. 1534 Tokens are 4-byte unsigned integers in a modular 4-byte space. 1535 Therefore, if x and y are tokens, x is less than y if 0 < (y - x) < 1536 2^31 in unsigned 32-bit arithmetic. 1538 Proxies grant contiguous ranges of tokens called token windows. 1539 Token windows are defined by their base (the first token in the 1540 range) and size. 1542 All token-related operations are done via Idempotence options. 1544 Idempotence options are only valid in the context of a SOCKS Session. 1545 If a SOCKS Request is not part of a Session (either by supplying a 1546 valid Session ID or successfully initiating one via a Session 1547 Request), the proxy MUST silently ignore any Idempotence options. 1549 Token windows are tracked by the proxy on a per-session basis. There 1550 can be at most one token window for every session and its tokens can 1551 only be spent from within said session. 1553 Client and proxy implementations MUST either support all Idempotence 1554 Option Types, or none. 1556 8.5.1. Requesting a token window 1558 A client can obtain a window of tokens by sending an Idempotence 1559 Request option as part of a SOCKS Request: 1561 1 2 3 1562 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1563 +-------------------------------+-------------------------------+ 1564 | Kind = 11 | Length = 8 | 1565 +-------------------------------+-------------------------------+ 1566 | Window Size | 1567 +---------------------------------------------------------------+ 1569 Figure 30: Token Request 1571 o Window Size: The requested window size. 1573 Once a token window is issued, the proxy MUST include an Idempotence 1574 Window option in all subsequent successful Authentication Replies: 1576 1 2 3 1577 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1578 +-------------------------------+-------------------------------+ 1579 | Kind = 12 | Length = 12 | 1580 +-------------------------------+-------------------------------+ 1581 | Window Base | 1582 +---------------------------------------------------------------+ 1583 | Window Size | 1584 +---------------------------------------------------------------+ 1586 Figure 31: Idempotence Window 1588 o Window Base: The first token in the window. 1590 o Window Size: The window size. This value MAY differ from the 1591 requested window size. Window sizes MUST be less than 2^31. 1592 Window sizes MUST NOT be 0. 1594 If no token window is issued, the proxy MUST silently ignore the 1595 Token Request. If there is already a token window associated with 1596 the session, the proxy MUST NOT issue a new window. 1598 8.5.2. Spending a token 1600 The client can attempt to spend a token by including a Idempotence 1601 Expenditure option in its SOCKS request: 1603 1 2 3 1604 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1605 +-------------------------------+-------------------------------+ 1606 | Kind = 13 | Length = 4 | 1607 +-------------------------------+-------------------------------+ 1608 | Token | 1609 +---------------------------------------------------------------+ 1611 Figure 32: Idempotence Expenditure 1613 o Kind: 13 (Idempotence Expenditure option) 1615 o Length: 8 1617 o Token: The token being spent. 1619 Clients SHOULD prioritize spending the smaller tokens. 1621 The proxy responds by sending either an Idempotence Accepted or 1622 Rejected option as part of the Authentication Reply: 1624 1 2 3 1625 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1626 +-------------------------------+-------------------------------+ 1627 | Kind = 14 | Length = 4 | 1628 +-------------------------------+-------------------------------+ 1630 Figure 33: Idempotence Accepted 1632 1 2 3 1633 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1634 +-------------------------------+-------------------------------+ 1635 | Kind = 15 | Length = 4 | 1636 +-------------------------------+-------------------------------+ 1638 Figure 34: Idempotence Rejected 1640 If eligible, the token is spent before attempting to honor the 1641 Request. If the token is not eligible for spending, the 1642 Authentication Reply MUST indicate failure. 1644 8.5.3. Shifting windows 1646 Windows can be shifted (i. e. have their base increased, while 1647 retaining their size) unilaterally by the proxy. 1649 Proxy implementations SHOULD shift the window: * as soon as the 1650 lowest-order token in the window is spent and * when a sufficiently 1651 high-order token is spent. 1653 Proxy implementations SHOULD NOT shift the window's base beyond the 1654 highest unspent token. 1656 8.5.4. Out-of-order Window Advertisements 1658 Even though the proxy increases the window's base monotonically, 1659 there is no mechanism whereby a SOCKS client can receive the Token 1660 Window Advertisements in order. As such, clients SHOULD disregard 1661 Token Window Advertisements with a Window Base less than the 1662 previously known value. 1664 9. Username/Password Authentication 1666 Username/Password authentication is carried out as in [RFC1929]. 1668 Clients can also attempt to authenticate by placing the Username/ 1669 Password request in an Authentication Data Option. 1671 1 2 3 1672 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1673 +-------------------------------+-------------------------------+ 1674 | Kind = 4 | Length | 1675 +---------------+---------------+---------------+---------------+ 1676 | Method = 2 | ... 1677 +---------------+ ... 1678 ... ... 1679 ... Username/Password Request ... 1680 ... ... 1681 ... +-----------------------------------------------+ 1682 ... | Padding = 0 (variable length, 0-3 bytes) | 1683 +---------------+-----------------------------------------------+ 1685 Figure 35: Password authentication via a SOCKS Option 1687 o Username/Password Request: The Username/Password Request, as 1688 described in [RFC1929]. 1690 Proxies reply by including a Authentication Data Option in the next 1691 Authentication Reply which contains the Username/Password reply: 1693 1 2 3 1694 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1695 +-------------------------------+-------------------------------+ 1696 | Kind = 4 | Length = 8 | 1697 +---------------+---------------+---------------+---------------+ 1698 | Method = 2 | Username/Password Reply | Padding = 0 | 1699 +---------------+-------------------------------+---------------+ 1701 Figure 36: Reply to password authentication via a SOCKS Option 1703 o Username/Password Reply: The Username/Password Reply, as described 1704 in [RFC1929]. 1706 10. TCP Fast Open on the Client-Proxy Leg 1708 TFO breaks TCP semantics, causing replays of the data in the SYN's 1709 payload under certain rare circumstances [RFC7413]. A replayed SOCKS 1710 Request could itself result in a replayed connection on behalf of the 1711 client. 1713 As such, client implementations SHOULD NOT use TFO on the client- 1714 proxy leg unless: 1716 o The protocol running on top of SOCKS tolerates the risks of TFO, 1717 or 1719 o The SYN's payload does not contain any application data (so that 1720 no data is replayed to the server, even though duplicate 1721 connections are still possible), or 1723 o The client uses Idempotence Options, making replays very unlikely, 1724 or 1726 o SOCKS is running on top of TLS and Early Data is not used. 1728 11. False Starts 1730 In case of CONNECT Requests, the client MAY start sending application 1731 data as soon as possible, as long as doing so does not incur the risk 1732 of breaking the SOCKS protocol. 1734 Clients must work around the authentication phase by doing any of the 1735 following: 1737 o If the Request does not contain an Authentication Method 1738 Advertisement option, the authentication phase is guaranteed not 1739 to happen. In this case, application data MAY be sent immediately 1740 after the Request. 1742 o Application data MAY be sent immediately after receiving an 1743 Authentication Reply indicating success. 1745 o When performing a method-specific authentication sequence, 1746 application data MAY be sent immediately after the last client 1747 message. 1749 12. DNS provided by SOCKS 1751 Clients may require information typically obtained from DNS servers, 1752 albeit from the proxy's vantage point. 1754 While the CONNECT command can work with domain names, some clients' 1755 workflows require that addresses be resolved as a separate step prior 1756 to connecting. Moreover, the SOCKS Datagram Header, as described in 1757 Section 7.3, can be reduced in size by providing the resolved 1758 destination IP address, rather than the FQDN. 1760 Emerging techniques may also make use of DNS to deliver server- 1761 specific information to clients. For example, Encrypted SNI 1762 [I-D.ietf-tls-esni] relies on DNS to publish encryption keys. 1764 Proxy implementations MAY provide a default plaintext DNS service. A 1765 client looking to make use of it issues a CONNECT Request to IP 1766 address 0.0.0.0 or 0:0:0:0:0:0:0:0 on port 53. Following successful 1767 authentication, the Operation Reply MAY indicate an unspecified bind 1768 address (0.0.0.0 or ::) and port (0). The client and proxy then 1769 behave as per [RFC7766]. 1771 The service itself can be provided directly by the proxy daemon, or 1772 by proxying the client's request to a pre-configured DNS server. 1774 If the proxy does not implement such functionality, it MAY return an 1775 error code signalling "Connection refused". 1777 13. Security Considerations 1779 13.1. Large requests 1781 Given the format of the request message, a malicious client could 1782 craft a request that is in excess of 16 KB and proxies could be prone 1783 to DDoS attacks. 1785 To mitigate such attacks, proxy implementations SHOULD be able to 1786 incrementally parse the requests. Proxies MAY close the connection 1787 to the client if: 1789 o the request is not fully received after a certain timeout, or 1791 o the number of options or their size exceeds an imposed hard cap. 1793 13.2. Replay attacks 1795 In TLS 1.3, early data (which is likely to contain a full SOCKS 1796 request) is prone to replay attacks. 1798 While Token Expenditure options can be used to mitigate replay 1799 attacks, anything prior to the initial Token Request is still 1800 vulnerable. As such, client implementations SHOULD NOT make use of 1801 TLS early data unless the Request attempts to spend a token. 1803 13.3. Resource exhaustion 1805 Malicious clients can issue a large number of Session Requests, 1806 forcing the proxy to keep large amounts of state. 1808 To mitigate this, the proxy MAY implement policies restricting the 1809 number of concurrent sessions on a per-IP or per-user basis, or 1810 barring unauthenticated clients from establishing sessions. 1812 14. Privacy Considerations 1814 The timing of Operation Replies can reveal some information about a 1815 proxy's recent usage: 1817 o The DNS resolver used by the proxy may cache the answer to recent 1818 queries. As such, subsequent connection attempts to the same 1819 hostname are likely to be slightly faster, even if requested by 1820 different clients. 1822 o Likewise, the proxy's OS typically caches TFO cookies. Repeated 1823 TFO connection attempts tend to be sped up, regardless of the 1824 client. 1826 15. IANA Considerations 1828 This document requests that IANA allocate 2-byte option kinds for 1829 SOCKS 6 options. Further, this document requests the following 1830 option kinds: 1832 o Unassigned: 0 1833 o Stack: 1 1835 o Authentication Method Advertisement: 2 1837 o Authentication Method Selection: 3 1839 o Authentication Data: 4 1841 o Session Request: 5 1843 o Session ID: 6 1845 o Session OK: 8 1847 o Session Invalid: 9 1849 o Session Teardown: 10 1851 o Idempotence Request: 11 1853 o Idempotence Window: 12 1855 o Idempotence Expenditure: 13 1857 o Idempotence Accepted: 14 1859 o Idempotence Rejected: 15 1861 o Resolution Request: 16 1863 o IPv4 Resolution: 17 1865 o IPv6 Resolution: 18 1867 o Vendor-specific: 64512-0xFFFF 1869 This document also requests that IANA allocate a TCP and UDP port for 1870 SOCKS over TLS and DTLS, respectively. 1872 16. Acknowledgements 1874 The protocol described in this draft builds upon and is a direct 1875 continuation of SOCKS 5 [RFC1928]. 1877 17. References 1879 17.1. Normative References 1881 [RFC1929] Leech, M., "Username/Password Authentication for SOCKS 1882 V5", RFC 1929, DOI 10.17487/RFC1929, March 1996, 1883 . 1885 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1886 Requirement Levels", BCP 14, RFC 2119, 1887 DOI 10.17487/RFC2119, March 1997, 1888 . 1890 [RFC7766] Dickinson, J., Dickinson, S., Bellis, R., Mankin, A., and 1891 D. Wessels, "DNS Transport over TCP - Implementation 1892 Requirements", RFC 7766, DOI 10.17487/RFC7766, March 2016, 1893 . 1895 [RFC8305] Schinazi, D. and T. Pauly, "Happy Eyeballs Version 2: 1896 Better Connectivity Using Concurrency", RFC 8305, 1897 DOI 10.17487/RFC8305, December 2017, 1898 . 1900 17.2. Informative References 1902 [I-D.ietf-tls-dtls-connection-id] 1903 Rescorla, E., Tschofenig, H., and T. Fossati, "Connection 1904 Identifiers for DTLS 1.2", draft-ietf-tls-dtls-connection- 1905 id-07 (work in progress), October 2019. 1907 [I-D.ietf-tls-esni] 1908 Rescorla, E., Oku, K., Sullivan, N., and C. Wood, "TLS 1909 Encrypted Client Hello", draft-ietf-tls-esni-07 (work in 1910 progress), June 2020. 1912 [RFC1928] Leech, M., Ganis, M., Lee, Y., Kuris, R., Koblas, D., and 1913 L. Jones, "SOCKS Protocol Version 5", RFC 1928, 1914 DOI 10.17487/RFC1928, March 1996, 1915 . 1917 [RFC3550] Schulzrinne, H., Casner, S., Frederick, R., and V. 1918 Jacobson, "RTP: A Transport Protocol for Real-Time 1919 Applications", STD 64, RFC 3550, DOI 10.17487/RFC3550, 1920 July 2003, . 1922 [RFC6824] Ford, A., Raiciu, C., Handley, M., and O. Bonaventure, 1923 "TCP Extensions for Multipath Operation with Multiple 1924 Addresses", RFC 6824, DOI 10.17487/RFC6824, January 2013, 1925 . 1927 [RFC7413] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP 1928 Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014, 1929 . 1931 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1932 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1933 . 1935 Authors' Addresses 1937 Vladimir Olteanu 1938 University Politehnica of Bucharest 1939 313 Splaiul Independentei, Sector 6 1940 Bucharest 1941 Romania 1943 Email: vladimir.olteanu@cs.pub.ro 1945 Dragos Niculescu 1946 University Politehnica of Bucharest 1947 313 Splaiul Independentei, Sector 6 1948 Bucharest 1949 Romania 1951 Email: dragos.niculescu@cs.pub.ro