idnits 2.17.1 draft-olteanu-intarea-socks-6-09.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 (March 09, 2020) is 1508 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-05 -- 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: September 10, 2020 March 09, 2020 7 SOCKS Protocol Version 6 8 draft-olteanu-intarea-socks-6-09 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 September 10, 2020. 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. TFO options . . . . . . . . . . . . . . . . . . . . . 25 76 8.1.5. Multipath options . . . . . . . . . . . . . . . . . . 25 77 8.1.6. Listen Backlog options . . . . . . . . . . . . . . . 26 78 8.1.7. UDP Error options . . . . . . . . . . . . . . . . . . 27 79 8.2. Authentication Method options . . . . . . . . . . . . . . 27 80 8.3. Authentication Data options . . . . . . . . . . . . . . . 29 81 8.4. Session options . . . . . . . . . . . . . . . . . . . . . 29 82 8.4.1. Session initiation . . . . . . . . . . . . . . . . . 30 83 8.4.2. Further SOCKS Requests . . . . . . . . . . . . . . . 31 84 8.4.3. Tearing down the session . . . . . . . . . . . . . . 32 85 8.5. Idempotence options . . . . . . . . . . . . . . . . . . . 32 86 8.5.1. Requesting a token window . . . . . . . . . . . . . . 33 87 8.5.2. Spending a token . . . . . . . . . . . . . . . . . . 34 88 8.5.3. Shifting windows . . . . . . . . . . . . . . . . . . 35 89 8.5.4. Out-of-order Window Advertisements . . . . . . . . . 35 90 9. Username/Password Authentication . . . . . . . . . . . . . . 35 91 10. TCP Fast Open on the Client-Proxy Leg . . . . . . . . . . . . 36 92 11. False Starts . . . . . . . . . . . . . . . . . . . . . . . . 36 93 12. DNS provided by SOCKS . . . . . . . . . . . . . . . . . . . . 37 94 13. Security Considerations . . . . . . . . . . . . . . . . . . . 37 95 13.1. Large requests . . . . . . . . . . . . . . . . . . . . . 38 96 13.2. Replay attacks . . . . . . . . . . . . . . . . . . . . . 38 97 13.3. Resource exhaustion . . . . . . . . . . . . . . . . . . 38 98 14. Privacy Considerations . . . . . . . . . . . . . . . . . . . 38 99 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39 100 16. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 40 101 17. References . . . . . . . . . . . . . . . . . . . . . . . . . 40 102 17.1. Normative References . . . . . . . . . . . . . . . . . . 40 103 17.2. Informative References . . . . . . . . . . . . . . . . . 40 104 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 41 106 1. Introduction 108 Versions 4 and 5 [RFC1928] of the SOCKS protocol were developed two 109 decades ago and are in widespread use for circuit level gateways or 110 as circumvention tools, and enjoy wide support and usage from various 111 software, such as web browsers, SSH clients, and proxifiers. 112 However, their design needs an update in order to take advantage of 113 the new features of transport protocols, such as TCP Fast Open 114 [RFC7413], or to better assist newer transport protocols, such as 115 MPTCP [RFC6824]. 117 One of the main issues faced by SOCKS version 5 is that, when taking 118 into account the TCP handshake, method negotiation, authentication, 119 connection request and grant, it may take up to 5 RTTs for a data 120 exchange to take place at the application layer. This is especially 121 costly in networks with a large delay at the access layer, such as 122 3G, 4G, or satelite. 124 The desire to reduce the number of RTTs manifests itself in the 125 design of newer security protocols. TLS version 1.3 [RFC8446] 126 defines a zero round trip (0-RTT) handshake mode for connections if 127 the client and server had previously communicated. 129 TCP Fast Open [RFC7413] is a TCP option that allows TCP to send data 130 in the SYN and receive a response in the first ACK, and aims at 131 obtaining a data response in one RTT. The SOCKS protocol needs to 132 concern itself with at least two TFO deployment scenarios: First, 133 when TFO is available end-to-end (at the client, at the proxy, and at 134 the server); second, when TFO is active between the client and the 135 proxy, but not at the server. 137 This document describes the SOCKS protocol version 6. The key 138 improvements over SOCKS version 5 are: 140 o The client sends as much information upfront as possible, and does 141 not wait for the authentication process to conclude before 142 requesting the creation of a socket. 144 o The connection request also mimics the semantics of TCP Fast Open 145 [RFC7413]. As part of the connection request, the client can 146 supply the potential payload for the initial SYN that is sent out 147 to the server. 149 o The protocol can be extended via options without breaking 150 backward-compatibility. 152 o The protocol can leverage the aforementioned options to support 153 0-RTT authentication schemes. 155 1.1. Revision log 157 Typos and minor clarifications are not listed. 159 draft-09 161 o Revamped UDP relay 163 * Support for ICMP errors: host/net unreachable, TTL exceeded 165 * Datagrams can be sent over TCP 167 * Timeout for the receipt of the initial datagram 169 o TTL stack option (intended use: traceroute) 171 o Added the "Privacy Considerations" section 173 o SOCKS-provided DNS: the proxy may provide a valid bind address and 174 port 176 draft-08 178 o Removed Address Resolution options 180 o Happy Eyeballs options 182 o DNS provided by SOCKS 184 draft-07 186 o All fields are now alignned. 188 o Eliminated version minors 190 o Lots of changes to options 191 * 2-byte option kinds 193 * Flattened option kinds/types/reply codes; also renamed some 194 options 196 * Socket options 198 + Proxies MUST always answer them (Clients can probe for 199 support) 201 + MPTCP Options: expanded functionality ("please do/don't do 202 MPTCP on my behalf") 204 + MPTCP Scheduler options removed 206 + Listen Backlog options: code changed to 0x03 208 * Revamped Idempotence options 210 * Auth data options limited to one per method 212 o Authentication Reply: all authentication-related information is 213 now in the options 215 * Authentication replies no longer have a field indicating the 216 chosen auth. method 218 * Method that must proceed (or whereby authentication succeeded) 219 indicated in options 221 * Username/password authentication: proxy now sends reply in 222 option 224 o Removed requirements w.r.t. caching authentication methods by 225 multihomed clients 227 o UDP: 8-byte association IDs 229 o Sessions 231 * The proxy is now free to terminate ongoing connections along 232 with the session. 234 * The session-terminating request is not part of the session that 235 it terminated. 237 o Address Resolution options 238 o Session options 240 o Options now have a 2-byte length field. 242 o Stack options 244 * Stack options can no longer contain duplicate information. 246 * TFO: Better payload size semantics 248 * TOS: Added missing code field. 250 * MPTCP Scheduler options: 252 + Removed support for round-robin 254 + "Default" renamed to "Lowest latency first" 256 * Listen Backlog options: now tied to sessions, instead of an 257 authenticated user 259 o Idempotence options 261 * Now used in the context of a session (no longer tied to an 262 authenticated user) 264 * Idempotence options have a different codepoint: 0x05. (Was 265 0x04.) 267 * Clarified that implementations that support Idempotence Options 268 must support all Idempotence Option Types. 270 * Shifted Idempotence Option Types by 1. (Makes implementation 271 easier.) 273 o Shrunk vendor-specific option range to 32 (down from 64). 275 o Removed reference to dropping initial data. (It could no longer 276 be done as of -05.) 278 o Initial data size capped at 16KB. 280 o Application data is never encrypted by SOCKS 6. (It can still be 281 encrypted by the TLS layer under SOCKS.) 283 o Messages now carry the total length of the options, rather than 284 the number of options. Limited options length to 16KB. 286 o Security Considerations 288 * Updated the section to reflect the smaller maximum message 289 size. 291 * Added a subsection on resource exhaustion. 293 draft-05 295 o Limited the "slow" authentication negociations to one (and 296 Authentication Replies to 2) 298 o Revamped the handling of the first bytes in the application data 299 stream 301 * False starts are now recommended. (Added the "False Start" 302 section.) 304 * Initial data is only available to clients willing to do "slow" 305 authentication. Moved the "Initial data size" field from 306 Requests to Authentication Method options. 308 * Initial data size capped at 2^13. Initial data can no longer 309 be dropped by the proxy. 311 * The TFO option can hint at the desired SYN payload size. 313 o Request: clarified the meaning of the Address and Port fields. 315 o Better reverse TCP proxy support: optional listen backlog for TCP 316 BIND 318 o TFO options can no longer be placed inside Operation Replies. 320 o IP TOS stack option 322 o Suggested a range for vendor-specific options. 324 o Revamped UDP functionality 326 * Now using fixed UDP ports 328 * DTLS support 330 o Stack options: renamed Proxy-Server leg to Proxy-Remote leg 331 o Moved Token Expenditure Replies to the Authentication Reply. 333 o Shifted the Initial Data Size field in the Request, in order to 334 make it easier to parse. 336 draft-03 338 o Shifted some fields in the Operation Reply to make it easier to 339 parse. 341 o Added connection attempt timeout response code to Operation 342 Replies. 344 o Proxies send an additional Authentication Reply after the 345 authentication phase. (Useful for token window advertisements.) 347 o Renamed the section "Connection Requests" to "Requests" 349 o Clarified the fact that proxies don't need to support any command 350 in particular. 352 o Added the section "TCP Fast Open on the Client-Proxy Leg" 354 o Options: 356 * Added constants for option kinds 358 * Salt options removed, along with the relevant section from 359 Security Considerations. (TLS 1.3 Makes AEAD mandatory.) 361 * Limited Authentication Data options to one per method. 363 * Relaxed proxy requirements with regard to handling multiple 364 Authentication Data options. (When the client violates the 365 above bullet point.) 367 * Removed interdependence between Authentication Method and 368 Authentication Data options. 370 * Clients SHOULD omit advertising the "No authentication 371 required" option. (Was MAY.) 373 * Idempotence options: 375 + Token Window Advertisements are now part of successful 376 Authentication Replies (so that the proxy-server RTT has no 377 impact on their timeliness). 379 + Proxies can't advetise token windows of size 0. 381 + Tweaked token expenditure response codes. 383 + Support no longer mandatory on the proxy side. 385 * Revamped Socket options 387 + Renamed Socket options to Stack options. 389 + Banned contradictory socket options. 391 + Added socket level for generic IP. Removed the "socket" 392 socket level. 394 + Stack options no longer use option codes from setsockopt(). 396 + Changed MPTCP Scheduler constants. 398 draft-02 400 o Made support for Idempotence options mandatory for proxies. 402 o Clarified what happens when proxies can not or will not issue 403 tokens. 405 o Limited token windows to 2^31 - 1. 407 o Fixed definition of "less than" for tokens. 409 o NOOP commands now trigger Operation Replies. 411 o Renamed Authentication options to Authentication Data options. 413 o Authentication Data options are no longer mandatory. 415 o Authentication methods are now advertised via options. 417 o Shifted some Request fields. 419 o Option range for vendor-specific options. 421 o Socket options. 423 o Password authentication. 425 o Salt options. 427 draft-01 429 o Added this section. 431 o Support for idempotent commands. 433 o Removed version numbers from operation replies. 435 o Request port number for SOCKS over TLS. Deprecate encryption/ 436 encapsulation within SOCKS. 438 o Added Version Mismatch Replies. 440 o Renamed the AUTH command to NOOP. 442 o Shifted some fields to make requests and operation replies easier 443 to parse. 445 2. Requirements language 447 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 448 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 449 document are to be interpreted as described in [RFC2119]. 451 3. Mode of operation 452 CLIENT PROXY 454 +------------------------+ 455 | Authentication methods | Request 456 --------> Command code +------------------------------> 457 | Address | 458 | Port | 459 | Options | 460 +------------------------+ 462 +------------------------+ 463 --------> Initial data +------------------------------> 464 +------------------------+ 466 +-----------------------+ 467 Authentication Reply | Type | 468 <----------------------------------+ Options <----- 469 +-----------------------+ 471 <-------------------(Authentication protocol)------------------> 473 +-----------------------+ 474 Authentication Reply | Type = Success | 475 <----------------------------------+ Options <----- 476 +-----------------------+ 478 +-----------------------+ 479 Operation Reply | Reply code | 480 <--------------------+ Bind address <------------------ 481 | Bind port | 482 | Options | 483 +-----------------------+ 485 Figure 1: The SOCKS version 6 protocol message exchange 487 When a TCP-based client wishes to establish a connection to a server, 488 it must open a TCP connection to the appropriate SOCKS port on the 489 SOCKS proxy. The client then enters a negotiation phase, by sending 490 the request in Figure 1, that contains, in addition to fields present 491 in SOCKS 5 [RFC1928], fields that facilitate low RTT usage and faster 492 authentication negotiation. 494 Next, the server sends an authentication reply. If the request did 495 not contain the necessary authentication information, the proxy 496 indicates an authentication method that must proceed. This may 497 trigger a longer authentication sequence that could include tokens 498 for ulterior faster authentications. The part labeled 499 "Authentication protocol" is specific to the authentication method 500 employed and is not expected to be employed for every connection 501 between a client and its proxy server. The authentication protocol 502 typically takes up 1 RTT or more. 504 If the authentication is successful, an operation reply is generated 505 by the proxy. It indicates whether the proxy was successful in 506 creating the requested socket or not. 508 In the fast case, when authentication is properly set up, the proxy 509 attempts to create the socket immediately after the receipt of the 510 request, thus achieving an operational conection in one RTT (provided 511 TFO functionality is available at the client, proxy, and server). 513 4. Requests 515 The client starts by sending a request to the proxy. 517 1 2 3 518 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 519 +---------------+---------------+-------------------------------+ 520 | Version = 6 | Command Code | Options Length | 521 +---------------+---------------+---------------+---------------+ 522 | Port | Padding = 0 | Address Type | 523 +-------------------------------+---------------+---------------+ 524 | ... 525 ... Address (variable length) ... 526 ... | 527 +---------------------------------------------------------------+ 528 | ... 529 ... Options (variable length) ... 530 ... | 531 +---------------------------------------------------------------+ 533 Figure 2: SOCKS 6 Request 535 o Version: 6 537 o Command Code: 539 * 0x00 NOOP: does nothing. 541 * 0x01 CONNECT: requests the establishment of a TCP connection. 542 TFO MUST NOT be used unless explicitly requested. 544 * 0x02 BIND: requests the establishment of a TCP port binding. 546 * 0x03 UDP ASSOCIATE: requests a UDP port association. 548 o Address Type: 550 * 0x01: IPv4 552 * 0x03: Domain Name 554 * 0x04: IPv6 556 o Address: this field's format depends on the address type: 558 * IPv4: a 4-byte IPv4 address 560 * Domain Name: one byte that contains the length of the FQDN, 561 followed by the FQDN itself. The string is not NUL-terminated, 562 but padded by NUL characters, if needed. 564 * IPv6: a 16-byte IPv6 address 566 o Port: the port in network byte order. 568 o Padding: set to 0 570 o Options Length: the total size of the SOCKS options that appear in 571 the Options field. MUST NOT exceed 16KB. 573 o Options: see Section 8. 575 The Address and Port fields have different meanings based on the 576 Command Code: 578 o NOOP: The fields have no meaning. The Address Type field MUST be 579 either 0x01 (IPv4) or 0x04 (IPv6). The Address and Port fields 580 MUST be 0. 582 o CONNECT: The fields signify the address and port to which the 583 client wishes to connect. 585 o BIND, UDP ASSOCIATE: The fields indicate the desired bind address 586 and port. If the client does not require a certain address, it 587 can set the Address Type field to 0x01 (IPv4) or 0x04 (IPv6), and 588 the Address field to 0. Likewise, if the client does not require 589 a certain port, it can set the Port field to 0. 591 Clients can advertise their supported authentication methods by 592 including an Authentication Method Advertisement option (see 593 Section 8.2). 595 5. Version Mismatch Replies 597 Upon receipt of a request starting with a version number other than 598 6, the proxy sends the following response: 600 0 1 2 3 4 5 6 7 601 +---------------+ 602 | Version = 6 | 603 +---------------+ 605 Figure 3: SOCKS 6 Version Mismatch Reply 607 o Version: 6 609 A client MUST close the connection after receiving such a reply. 611 6. Authentication Replies 613 Upon receipt of a valid request, the proxy sends an Authentication 614 Reply: 616 1 2 3 617 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 618 +---------------+---------------+-------------------------------+ 619 | Version = 6 | Type | Options Length | 620 +---------------+---------------+-------------------------------+ 621 | ... 622 ... Options (variable length) ... 623 ... | 624 +---------------------------------------------------------------+ 626 Figure 4: SOCKS 6 Authentication Reply 628 o Version: 6 630 o Type: 632 * 0x00: authentication successful. 634 * 0x01: authentication failed. 636 o Options Length: the total size of the SOCKS options that appear in 637 the Options field. MUST NOT exceed 16KB. 639 o Options: see Section 8. 641 If the server signals that the authentication has failed and does not 642 signal that any authentication negotiation can continue (via an 643 Authentication Method Selection option), the client MUST close the 644 connection. 646 The client and proxy begin a method-specific negotiation. During 647 such negotiations, the proxy MAY supply information that allows the 648 client to authenticate a future request using an Authentication Data 649 option. Application data is not subject to any encryption negotiated 650 during this phase. Descriptions of such negotiations are beyond the 651 scope of this memo. 653 When the negotiation is complete (either successfully or 654 unsuccessfully), the proxy sends a second Authentication Reply. The 655 second Authentication Reply MUST NOT allow for further negotiations. 657 7. Operation Replies 659 After the authentication negotiations are complete, the proxy sends 660 an Operation Reply: 662 1 2 3 663 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 664 +---------------+---------------+-------------------------------+ 665 | Version = 6 | Reply Code | Options Length | 666 +---------------+---------------+---------------+---------------+ 667 | Bind Port | Padding = 0 | Address Type | 668 +-------------------------------+---------------+---------------+ 669 | ... 670 ... Bind Address (variable length) ... 671 ... | 672 +---------------------------------------------------------------+ 673 | ... 674 ... Options (variable length) ... 675 ... | 676 +---------------------------------------------------------------+ 678 Figure 5: SOCKS 6 Operation Reply 680 o Version: 6 682 o Reply Code: 684 * 0x00: Succes 686 * 0x01: General SOCKS server failure 687 * 0x02: Connection not allowed by ruleset 689 * 0x03: Network unreachable 691 * 0x04: Host unreachable 693 * 0x05: Connection refused 695 * 0x06: TTL expired 697 * 0x07: Command not supported 699 * 0x08: Address type not supported 701 * 0x09: Connection attempt timed out 703 o Bind Port: the proxy bound port in network byte order. 705 o Padding: set to 0 707 o Address Type: 709 * 0x01: IPv4 711 * 0x03: Domain Name 713 * 0x04: IPv6 715 o Bind Address: the proxy bound address in the following format: 717 * IPv4: a 4-byte IPv4 address 719 * Domain Name: one byte that contains the length of the FQDN, 720 followed by the FQDN itself. The string is not NUL-terminated, 721 but padded by NUL characters, if needed. 723 * IPv6: a 16-byte IPv6 address 725 o Options Length: the total size of the SOCKS options that appear in 726 the Options field. MUST NOT exceed 16KB. 728 o Options: see Section 8. 730 Proxy implementations MAY support any subset of the client commands 731 listed in Section 4. 733 If the proxy returns a reply code other than "Success", the client 734 MUST close the connection. 736 If the client issued an NOOP command, the client MUST close the 737 connection after receiving the Operation Reply. 739 7.1. Handling CONNECT 741 In case the client has issued a CONNECT request, data can now pass. 743 7.2. Handling BIND 745 In case the client has issued a BIND request, it must wait for a 746 second Operation reply from the proxy, which signifies that a host 747 has connected to the bound port. The Bind Address and Bind Port 748 fields contain the address and port of the connecting host. 749 Afterwards, application data may pass. 751 7.3. Handling UDP ASSOCIATE 753 Proxies offering UDP functionality may be configured with a UDP port 754 used for relaying UDP datagrams to and from the client, and/or a port 755 used for relaying datagrams over DTLS. 757 Following a successful Operation Reply, the client and the proxy 758 begin exchanging messages with the following header: 760 1 2 3 761 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 762 +---------------+---------------+-------------------------------+ 763 | Version = 6 | Message Type | Message Length | 764 +---------------+---------------+-------------------------------+ 765 | Association ID | 766 | (8 bytes) | 767 +---------------------------------------------------------------+ 769 Figure 6: UDP Association Header 771 o Message Type: 773 * 0x01: Association Initialization 775 * 0x02: Association Confirmation 777 * 0x03: Datagram 779 * 0x04: Error 781 o Message Length: the total length of the message 782 o Association ID: the identifier of the UDP association 784 First, the proxy picks an Association ID sends a an Association 785 Initialization message: 787 1 2 3 788 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 789 +---------------+---------------+-------------------------------+ 790 | Version = 6 | 0x01 | Message Length = 12 | 791 +---------------+---------------+-------------------------------+ 792 | Association ID | 793 | (8 bytes) | 794 +---------------------------------------------------------------+ 796 Figure 7: UDP Association Initialization 798 Proxy implementations SHOULD generate Association IDs randomly or 799 pseudo-randomly. 801 Clients may start sending datagrams to the proxy either: 803 o over the TCP connection, 805 o in plaintext, using the proxy's configured UDP port(s), or 807 o over an established DTLS session. 809 A client's datagrams are prefixed by a Datagram Header, indicating 810 the remote host's address and port: 812 1 2 3 813 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 814 +---------------+---------------+-------------------------------+ 815 | Version = 6 | 0x03 | Message Length | 816 +---------------+---------------+-------------------------------+ 817 | Association ID | 818 | (8 bytes) | 819 +---------------+---------------+-------------------------------+ 820 | Address Type | Padding = 0 | Port | 821 +---------------+---------------+-------------------------------+ 822 | ... 823 ... Address (variable length) ... 824 ... | 825 +---------------------------------------------------------------+ 827 Figure 8: Datagram Header 829 o Version: 0x06 831 o Association ID: the identifier of the UDP association 833 o Address Type: 835 * 0x01: IPv4 837 * 0x03: Domain Name 839 * 0x04: IPv6 841 o Address: this field's format depends on the address type: 843 * IPv4: a 4-byte IPv4 address 845 * Domain Name: one byte that contains the length of the FQDN, 846 followed by the FQDN itself. The string is not NUL-terminated. 848 * IPv6: a 16-byte IPv6 address 850 o Port: the port in network byte order. 852 Datagrams sent over UDP MAY be padded with arbitrary data (i. e., the 853 Message Length MAY be smaller than the actual UDP/DTLS payload). 854 Client and proxy implementations MUST ignore the padding. If the 855 Message Length is larger than the size of the UDP or DTLS payload, 856 the message MUST be silently ignored. 858 Following the receipt of the first datagram from the client, the 859 proxy makes a one-way mapping between the Association ID and: 861 o the TCP connection, if it was received over TCP, or 863 o the 5-tuple of the UDP conversation, if the datagram was received 864 over plain UDP, or 866 o the DTLS connection, if the datagram was received over DTLS. The 867 DTLS connection is identified either by its 5-tuple, or some other 868 mechanism, like [I-D.ietf-tls-dtls-connection-id]. 870 The proxy SHOULD close the TCP connection if the initial datagram is 871 not received after a timeout. 873 Further datagrams carrying the same Association ID, but not matching 874 the established mapping, are silently dropped. 876 The proxy then sends an UDP Association Confirmation message over the 877 TCP connection with the client: 879 1 2 3 880 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 881 +---------------+---------------+-------------------------------+ 882 | Version = 6 | 0x02 | Message Length = 12 | 883 +---------------+---------------+-------------------------------+ 884 | Association ID | 885 | (8 bytes) | 886 +---------------------------------------------------------------+ 888 Figure 9: UDP Association Confirmation 890 Following the confirmation message, UDP packets bound for the proxy's 891 bind address and port are relayed to the client, also prefixed by a 892 Datagram Header. 894 The UDP association remains active for as long as the TCP connection 895 between the client and the proxy is kept open. 897 7.3.1. Proxying UDP servers 899 Under some circumstances (e.g. when hosting a server), the SOCKS 900 client expects the remote host to send UDP datagrams first. As such, 901 the SOCKS client must trigger a UDP Association Confirmation without 902 having the proxy relay any datagrams on its behalf. 904 To that end, it sends an empty datagram prefixed by a Datagram Header 905 with an IP address and port consisting of zeroes. If it is using 906 UDP, the client SHOULD resend the empty datagram if an UDP 907 Association Confirmation is not received after a timeout. 909 7.3.2. Proxying multicast traffic 911 The use of multicast addessses is permitted for UDP traffic only. 913 7.3.3. Reporting ICMP Errors 915 If a client has opted in (see Section 8.1.7), the proxy MAY relay 916 information contained in some ICMP Error packets. The message format 917 is as follows: 919 1 2 3 920 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 921 +---------------+---------------+-------------------------------+ 922 | Version = 6 | 0x04 | Message Length | 923 +---------------+---------------+-------------------------------+ 924 | Association ID | 925 | (8 bytes) | 926 +---------------+---------------+-------------------------------+ 927 | Address Type | Padding = 0 | Port | 928 +---------------+---------------+-------------------------------+ 929 | ... 930 ... Address (variable length) ... 931 ... | 932 +---------------+---------------+-------------------------------+ 933 | Error Code | Reporter ATYP | Padding = 0 | 934 +---------------+---------------+-------------------------------+ 935 | ... 936 ... Reporter Address (variable length) ... 937 ... | 938 +---------------------------------------------------------------+ 940 Figure 10: Datagram Error Message 942 o Address: The destination address of the IP header contained in the 943 ICMP payload 945 o Address Type: Either 0x01 (IPv4) or 0x04 (IPv6) 947 o Port: The destination port of the UDP header contained in the ICMP 948 payload 950 o Reporter Address: The IP address of the host that issued the ICMP 951 error 953 o Reporter Address Type (ATYP): Either 0x01 (IPv4) or 0x04 (IPv6) 955 o Error code: 957 * 0x01: Network unreachable 959 * 0x02: Host unreachable 961 * 0x03: TTL expired 963 It is possible for ICMP Error packets to be spurious, and not be 964 related to any UDP packet that was sent out. The proxy is not 965 required to check the validity of ICMP Error packets before reporting 966 them to the client. 968 Clients MUST NOT send Datagram Error messages to the proxy. Proxies 969 MUST NOT send Error messages unless the clients have opted in. 971 8. SOCKS Options 973 SOCKS options have the following format: 975 1 2 3 976 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 977 +-------------------------------+-------------------------------+ 978 | Kind | Length | 979 +-------------------------------+-------------------------------+ 980 | ... 981 ... Option Data (variable length) ... 982 ... | 983 +---------------------------------------------------------------+ 985 Figure 11: SOCKS 6 Option 987 o Kind: Allocated by IANA. (See Section 15.) 989 o Length: The total length of the option. MUST be a multiple of 4. 991 o Option Data: The contents are specific to each option kind. 993 Unless otherwise noted, client and proxy implementations MAY omit 994 supporting any of the options described in this document. Upon 995 encountering an unsupported option, a SOCKS endpoint MUST silently 996 ignore it. 998 8.1. Stack options 1000 Stack options can be used by clients to alter the behavior of the 1001 protocols on top of which SOCKS is running, as well the protcols used 1002 by the proxy to communicate with the remote host (i.e. IP, TCP, 1003 UDP). A Stack option can affect either the proxy's protocol on the 1004 client-proxy leg or on the proxy-remote leg. Clients can only place 1005 Stack options inside SOCKS Requests. 1007 Proxies MAY choose not to honor any Stack options sent by the client. 1009 Proxies include Stack options in their Operation Replies to signal 1010 their behavior, and MUST do so for every supported Stack option sent 1011 by the client. Said options MAY also be unsolicited, i. e. the proxy 1012 MAY send them to signal behaviour that was not explicitly requested 1013 by the client. 1015 If a particular Stack option is unsupported, the proxy MUST silently 1016 ignore it. 1018 In case of UDP ASSOCIATE, the stack options refer to the UDP traffic 1019 relayed by the proxy. 1021 Stack options that are part of the same message MUST NOT contradict 1022 one another or contain duplicate information. 1024 1 2 3 1025 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 1026 +-------------------------------+-------------------------------+ 1027 | Kind = 1 | Length | 1028 +---+-----------+---------------+-------------------------------+ 1029 |Leg| Level | Code | ... 1030 +---+-----------+---------------+ ... 1031 ... ... 1032 ... Option Data (variable length) ... 1033 ... | 1034 +---------------------------------------------------------------+ 1036 Figure 12: Stack Option 1038 o Leg: 1040 * 1: Client-Proxy Leg 1042 * 2: Proxy-Remote Leg 1044 * 3: Both Legs 1046 o Level: 1048 * 1: IP: options that apply to either IPv4 or IPv6 1050 * 2: IPv4 1052 * 3: IPv6 1054 * 4: TCP 1056 * 5: UDP 1058 o Code: Option code 1059 o Option Data: Option-specific data 1061 8.1.1. IP TOS options 1063 1 2 3 1064 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 1065 +-------------------------------+-------------------------------+ 1066 | Kind = 1 | Length = 8 | 1067 +---+-----------+---------------+---------------+---------------+ 1068 |Leg| Level = 1 | Code = 1 | TOS | Padding = 0 | 1069 +---+-----------+---------------+---------------+---------------+ 1071 Figure 13: IP TOS Option 1073 o TOS: The IP TOS code 1075 The client can use IP TOS options to request that the proxy use a 1076 certain value for the IP TOS field. Likewise, the proxy can use IP 1077 TOS options to advertise the TOS values being used. 1079 8.1.2. Happy Eyeballs options 1081 1 2 3 1082 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 1083 +-------------------------------+-------------------------------+ 1084 | Kind = 1 | Length = 8 | 1085 +---+-----------+---------------+-------------------------------+ 1086 | 2 | Level = 1 | Code = 2 | Padding = 0 | 1087 +---+-----------+---------------+-------------------------------+ 1089 Figure 14: Happy Eyeballs Option 1091 This memo provides enough features for clients to implement a 1092 mechanism analogous to Happy Eyeballs [RFC8305] over SOCKS. However, 1093 when the delay between the client and the proxy, or the proxy's 1094 vantage point, is high, doing so can become impractical or 1095 inefficient. 1097 In such cases, the client can instruct the proxy to employ the Happy 1098 Eyeballs technique on its behalf when connecting to a remote host. 1100 The client MUST supply a Domain Name as part of its Request. 1101 Otherwise, the proxy MUST silently ignore the option. 1103 TODO: Figure out which knobs to include. 1105 8.1.3. TTL options 1107 1 2 3 1108 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 1109 +-------------------------------+-------------------------------+ 1110 | Kind = 1 | Length = 8 | 1111 +---+-----------+---------------+---------------+---------------+ 1112 |Leg| Level = 1 | Code = 3 | TTL | Padding = 0 | 1113 +---+-----------+---------------+---------------+---------------+ 1115 Figure 15: IP TTL Option 1117 o TTL: The IP TTL 1119 8.1.4. TFO options 1121 1 2 3 1122 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 1123 +-------------------------------+-------------------------------+ 1124 | Kind = 1 | Length = 8 | 1125 +---+-----------+---------------+-------------------------------+ 1126 | 2 | Level = 4 | Code = 1 | Payload Size | 1127 +---+-----------+---------------+-------------------------------+ 1129 Figure 16: TFO Option 1131 o Payload Size: The desired payload size of the TFO SYN. Ignored in 1132 case of a BIND command. 1134 If a SOCKS Request contains a TFO option, the proxy SHOULD attempt to 1135 use TFO in case of a CONNECT command, or accept TFO in case of a BIND 1136 command. Otherwise, the proxy MUST NOT attempt to use TFO in case of 1137 a CONNECT command, or accept TFO in case of a BIND command. 1139 In case of a CONNECT command, the client can indicate the desired 1140 payload size of the SYN. If the field is 0, the proxy can use an 1141 arbitrary payload size. If the field is non-zero, the proxy MUST NOT 1142 use a payload size larger than the one indicated. The proxy MAY use 1143 a smaller payload size than the one indicated. 1145 8.1.5. Multipath options 1147 In case of a CONNECT or BIND command, the client can inform the proxy 1148 whether MPTCP is desired on the proxy-remote leg by sending a 1149 Multipath option. 1151 Conversely, the proxy can use a Multipath option to convey the 1152 following information: * whether or not the connection uses MPTCP or 1153 not, when replying to a CONNECT command, or in the second Operation 1154 reply to a BIND command, or * whether an MPTCP connection will be 1155 accepted, when first replying to a BIND command. 1157 1 2 3 1158 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 1159 +-------------------------------+-------------------------------+ 1160 | Kind = 1 | Length = 8 | 1161 +---+-----------+---------------+---------------+---------------+ 1162 | 2 | Level = 4 | Code = 2 | Availability | Padding = 0 | 1163 +---+-----------+---------------+---------------+---------------+ 1165 Figure 17: Multipath Option 1167 o Availability: 1169 * 0x01: MPTCP is not desired or available 1171 * 0x02: MPTCP is desired or available 1173 In the absence of such an option, the proxy SHOULD NOT enable MPTCP. 1175 8.1.6. Listen Backlog options 1177 1 2 3 1178 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 1179 +-------------------------------+-------------------------------+ 1180 | Kind = 1 | Length = 8 | 1181 +---+-----------+---------------+-------------------------------+ 1182 | 2 | Level = 4 | Code = 3 | Backlog | 1183 +---+-----------+---------------+-------------------------------+ 1185 Figure 18: Listen Backlog Option 1187 o Backlog: The length of the listen backlog. 1189 The default behavior of the BIND does not allow a client to 1190 simultaneously handle multiple connections to the same bind address. 1191 A client can alter BIND's behavior by adding a TCP Listen Backlog 1192 Option to a BIND Request, provided that the Request is part of a 1193 Session. 1195 In response, the proxy sends a TCP Listen Backlog Option as part of 1196 the Operation Reply, with the Backlog field signalling the actual 1197 backlog used. The proxy SHOULD NOT use a backlog longer than 1198 requested. 1200 Following the successful negotiation of a backlog, the proxy listens 1201 for incoming connections for as long as the initial connection stays 1202 open. The initial connection is not used to relay data between the 1203 client and a remote host. 1205 To accept connections, the client issues further BIND Requests using 1206 the bind address and port supplied by the proxy in the initial 1207 Operation Reply. Said BIND requests must belong to the same Session 1208 as the original Request. 1210 If no backlog is issued, the proxy signals a backlog length of 0, and 1211 BIND's behavior remains unaffected. 1213 8.1.7. UDP Error options 1215 1 2 3 1216 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 1217 +-------------------------------+-------------------------------+ 1218 | Kind = 1 | Length = 8 | 1219 +---+-----------+---------------+-------------------------------+ 1220 | 2 | Level = 5 | Code = 1 | Padding = 0 | 1221 +---+-----------+---------------+-------------------------------+ 1223 Figure 19: UDP Error Option 1225 Clients can use this option to turn on error reporting for a 1226 particular UDP association. See Section 7.3.3. 1228 8.2. Authentication Method options 1230 A client that is willing to go through the authentication phase MUST 1231 include an Authentication Method Advertisement option in its Request. 1232 In case of a CONNECT Request, the option is also used to specify the 1233 amount of initial data supplied before any method-specific 1234 authentication negotiations take place. 1236 1 2 3 1237 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 1238 +-------------------------------+-------------------------------+ 1239 | Kind = 2 | Length | 1240 +-------------------------------+-------------------------------+ 1241 | Initial Data Length | ... 1242 +-------------------------------+ ... 1243 ... ... 1244 ... Methods (variable length) ... 1245 ... ... 1246 ... +-----------------------------------------------+ 1247 ... | Padding = 0 (variable length, 0-3 bytes) | 1248 +---------------+-----------------------------------------------+ 1250 Figure 20: Authentication Method Advertisement Option 1252 o Initial Data Size: A two-byte number in network byte order. In 1253 case of CONNECT, this is the number of bytes of initial data that 1254 are supplied by the client immediately following the Request. 1255 This number MUST NOT be larger than 2^14. 1257 o Methods: One byte per advertised method. Method numbers are 1258 assigned by IANA. 1260 o Padding: A minimally-sized sequence of zeroes, such that the 1261 option length is a multiple of 4. Note that 0 coincides with the 1262 value for "No Authentication Required". 1264 Clients MUST support the "No authentication required" method. 1265 Clients SHOULD omit advertising the "No authentication required" 1266 option. 1268 The proxy indicates which authentication method must proceed by 1269 sending an Authentication Method Selection option in the 1270 corresponding Authentication Reply: 1272 1 2 3 1273 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 1274 +-------------------------------+-------------------------------+ 1275 | Kind = 3 | Length = 8 | 1276 +---------------+---------------+-------------------------------+ 1277 | Method | Padding = 0 | 1278 +---------------+-----------------------------------------------+ 1280 Figure 21: Authentication Method Selection Option 1282 o Method: The selected method. 1284 If the proxy selects "No Acceptable Methods", the client MUST close 1285 the connection. 1287 If authentication is successful via some other means, or not required 1288 at all, the proxy silently ignores the Authentication Method 1289 Advertisement option. 1291 8.3. Authentication Data options 1293 Authentication Data options carry method-specific authentication 1294 data. They can be part of SOCKS Requests and Authentication Replies. 1296 Authentication Data options have the following format: 1298 1 2 3 1299 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 1300 +-------------------------------+-------------------------------+ 1301 | Kind = 4 | Length | 1302 +---------------+---------------+-------------------------------+ 1303 | Method | ... 1304 +---------------+ ... 1305 ... ... 1306 ... Authentication Data (variable length) ... 1307 ... | 1308 +---------------------------------------------------------------+ 1310 Figure 22: Authentication Data Option 1312 o Method: The number of the authentication method. These numbers 1313 are assigned by IANA. 1315 o Authentication Data: The contents are specific to each method. 1317 Clients MUST only place one Authentication Data option per 1318 authentication method. 1320 8.4. Session options 1322 Clients and proxies can establish SOCKS sessions, which span one or 1323 more Requests. All session-related negotiations are done via Session 1324 Options, which are placed in Requests and Authentication Replies by 1325 the client and, respectively, by the proxy. 1327 Client and proxy implementations MUST either support all Session 1328 Option Types, or none. 1330 8.4.1. Session initiation 1332 A client can initiate a session by sending a Session Request Option: 1334 1 2 3 1335 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 1336 +-------------------------------+-------------------------------+ 1337 | Kind = 5 | Length = 4 | 1338 +-------------------------------+-------------------------------+ 1340 Figure 23: Session Request Option 1342 The proxy then replies with a Session ID Option in the successful 1343 Operation Reply: 1345 1 2 3 1346 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 1347 +-------------------------------+-------------------------------+ 1348 | Kind = 6 | Length | 1349 +-------------------------------+-------------------------------+ 1350 | ... 1351 ... Session ID (variable length) ... 1352 ... | 1353 +---------------------------------------------------------------+ 1355 Figure 24: Session ID Option 1357 o Session ID: An opaque sequence of bytes specific to the session. 1358 The size MUST be a multiple of 4. MUST NOT be empty. 1360 The Session ID serves to identify the session and is opaque to the 1361 client. 1363 The credentials, or lack thereof, used to initiate the session are 1364 tied to the session. If authentication is to be performed for 1365 further Requests, the session is deemed "untrusted", and the proxy 1366 also places a Session Untrusted option in the Authentication Reply: 1368 1 2 3 1369 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 1370 +-------------------------------+-------------------------------+ 1371 | Kind = 7 | Length = 4 | 1372 +-------------------------------+-------------------------------+ 1374 Figure 25: Session Untrusted Option 1376 The SOCKS Request that initiated the session is considered part of 1377 the session. A client MUST NOT attempt to initiate a session from 1378 within a different session. 1380 If the proxy can not or will not honor the Session Request, it does 1381 so silently. 1383 8.4.2. Further SOCKS Requests 1385 Any further SOCKS Requests that are part of the session MUST include 1386 a Session ID Option (as seen in Figure 24). 1388 The authentication procedure is altered based on the Session ID's 1389 validity and whether or not the Session is untrusted. 1391 For valid Session IDs: 1393 o If the session is untrusted, the proxy MUST reject clients that do 1394 not authenticate using the same method and credentials that were 1395 used to initiate the session. 1397 o Otherwise, the proxy MUST silently ignore any authentication 1398 attempt in the Request, and MUST NOT require any authentication. 1400 The proxy then replies by placing a Session OK option in the 1401 successful Authentication Reply: 1403 1 2 3 1404 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 1405 +-------------------------------+-------------------------------+ 1406 | Kind = 8 | Length = 4 | 1407 +-------------------------------+-------------------------------+ 1409 Figure 26: Session OK Option 1411 If the ticket is invalid, the first Authentication Reply MUST signal 1412 that authentication failed and can not continue (by setting the Type 1413 field to 0x01). Further, it SHALL contain a Session Invalid option: 1415 1 2 3 1416 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 1417 +-------------------------------+-------------------------------+ 1418 | Kind = 9 | Length = 4 | 1419 +-------------------------------+-------------------------------+ 1421 Figure 27: Session Invalid Option 1423 8.4.3. Tearing down the session 1425 Proxies can, at their discretion, tear down a session and free all 1426 associated state. Proxy implementations SHOULD feature a timeout 1427 mechanism that destroys sessions after a period of inactivity. When 1428 a session is terminated, the proxy MAY close all connections 1429 associated with said session. 1431 Clients can signal that a session is no longer needed, and can be 1432 torn down, by sending a Session Teardown option in addition to the 1433 Session ID option: 1435 1 2 3 1436 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 1437 +-------------------------------+-------------------------------+ 1438 | Kind = 10 | Length = 4 | 1439 +-------------------------------+-------------------------------+ 1441 Figure 28: Session Teardown Option 1443 After sending such an option, the client MUST assume that the session 1444 is no longer valid. The proxy MUST treat the connection-terminating 1445 request as if it were not part of any session. 1447 8.5. Idempotence options 1449 To protect against duplicate SOCKS Requests, clients can request, and 1450 then spend, idempotence tokens. A token can only be spent on a 1451 single SOCKS request. 1453 Tokens are 4-byte unsigned integers in a modular 4-byte space. 1454 Therefore, if x and y are tokens, x is less than y if 0 < (y - x) < 1455 2^31 in unsigned 32-bit arithmetic. 1457 Proxies grant contiguous ranges of tokens called token windows. 1458 Token windows are defined by their base (the first token in the 1459 range) and size. 1461 All token-related operations are done via Idempotence options. 1463 Idempotence options are only valid in the context of a SOCKS Session. 1464 If a SOCKS Request is not part of a Session (either by supplying a 1465 valid Session ID or successfully initiating one via a Session 1466 Request), the proxy MUST silently ignore any Idempotence options. 1468 Token windows are tracked by the proxy on a per-session basis. There 1469 can be at most one token window for every session and its tokens can 1470 only be spent from within said session. 1472 Client and proxy implementations MUST either support all Idempotence 1473 Option Types, or none. 1475 8.5.1. Requesting a token window 1477 A client can obtain a window of tokens by sending an Idempotence 1478 Request option as part of a SOCKS Request: 1480 1 2 3 1481 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 1482 +-------------------------------+-------------------------------+ 1483 | Kind = 11 | Length = 8 | 1484 +-------------------------------+-------------------------------+ 1485 | Window Size | 1486 +---------------------------------------------------------------+ 1488 Figure 29: Token Request 1490 o Window Size: The requested window size. 1492 Once a token window is issued, the proxy MUST include an Idempotence 1493 Window option in all subsequent successful Authentication Replies: 1495 1 2 3 1496 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 1497 +-------------------------------+-------------------------------+ 1498 | Kind = 12 | Length = 12 | 1499 +-------------------------------+-------------------------------+ 1500 | Window Base | 1501 +---------------------------------------------------------------+ 1502 | Window Size | 1503 +---------------------------------------------------------------+ 1505 Figure 30: Idempotence Window 1507 o Window Base: The first token in the window. 1509 o Window Size: The window size. This value MAY differ from the 1510 requested window size. Window sizes MUST be less than 2^31. 1511 Window sizes MUST NOT be 0. 1513 If no token window is issued, the proxy MUST silently ignore the 1514 Token Request. If there is already a token window associated with 1515 the session, the proxy MUST NOT issue a new window. 1517 8.5.2. Spending a token 1519 The client can attempt to spend a token by including a Idempotence 1520 Expenditure option in its SOCKS request: 1522 1 2 3 1523 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 1524 +-------------------------------+-------------------------------+ 1525 | Kind = 13 | Length = 4 | 1526 +-------------------------------+-------------------------------+ 1527 | Token | 1528 +---------------------------------------------------------------+ 1530 Figure 31: Idempotence Expenditure 1532 o Kind: 13 (Idempotence Expenditure option) 1534 o Length: 8 1536 o Token: The token being spent. 1538 Clients SHOULD prioritize spending the smaller tokens. 1540 The proxy responds by sending either an Idempotence Accepted or 1541 Rejected option as part of the Authentication Reply: 1543 1 2 3 1544 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 1545 +-------------------------------+-------------------------------+ 1546 | Kind = 14 | Length = 4 | 1547 +-------------------------------+-------------------------------+ 1549 Figure 32: Idempotence Accepted 1551 1 2 3 1552 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 1553 +-------------------------------+-------------------------------+ 1554 | Kind = 15 | Length = 4 | 1555 +-------------------------------+-------------------------------+ 1557 Figure 33: Idempotence Rejected 1559 If eligible, the token is spent before attempting to honor the 1560 Request. If the token is not eligible for spending, the 1561 Authentication Reply MUST indicate failure. 1563 8.5.3. Shifting windows 1565 Windows can be shifted (i. e. have their base increased, while 1566 retaining their size) unilaterally by the proxy. 1568 Proxy implementations SHOULD shift the window: * as soon as the 1569 lowest-order token in the window is spent and * when a sufficiently 1570 high-order token is spent. 1572 Proxy implementations SHOULD NOT shift the window's base beyond the 1573 highest unspent token. 1575 8.5.4. Out-of-order Window Advertisements 1577 Even though the proxy increases the window's base monotonically, 1578 there is no mechanism whereby a SOCKS client can receive the Token 1579 Window Advertisements in order. As such, clients SHOULD disregard 1580 Token Window Advertisements with a Window Base less than the 1581 previously known value. 1583 9. Username/Password Authentication 1585 Username/Password authentication is carried out as in [RFC1929]. 1587 Clients can also attempt to authenticate by placing the Username/ 1588 Password request in an Authentication Data Option. 1590 1 2 3 1591 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 1592 +-------------------------------+-------------------------------+ 1593 | Kind = 4 | Length | 1594 +---------------+---------------+---------------+---------------+ 1595 | Method = 2 | ... 1596 +---------------+ ... 1597 ... ... 1598 ... Username/Password Request ... 1599 ... ... 1600 ... +-----------------------------------------------+ 1601 ... | Padding = 0 (variable length, 0-3 bytes) | 1602 +---------------+-----------------------------------------------+ 1604 Figure 34: Password authentication via a SOCKS Option 1606 o Username/Password Request: The Username/Password Request, as 1607 described in [RFC1929]. 1609 Proxies reply by including a Authentication Data Option in the next 1610 Authentication Reply which contains the Username/Password reply: 1612 1 2 3 1613 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 1614 +-------------------------------+-------------------------------+ 1615 | Kind = 4 | Length = 8 | 1616 +---------------+---------------+---------------+---------------+ 1617 | Method = 2 | Username/Password Reply | Padding = 0 | 1618 +---------------+-------------------------------+---------------+ 1620 Figure 35: Reply to password authentication via a SOCKS Option 1622 o Username/Password Reply: The Username/Password Reply, as described 1623 in [RFC1929]. 1625 10. TCP Fast Open on the Client-Proxy Leg 1627 TFO breaks TCP semantics, causing replays of the data in the SYN's 1628 payload under certain rare circumstances [RFC7413]. A replayed SOCKS 1629 Request could itself result in a replayed connection on behalf of the 1630 client. 1632 As such, client implementations SHOULD NOT use TFO on the client- 1633 proxy leg unless: 1635 o The protocol running on top of SOCKS tolerates the risks of TFO, 1636 or 1638 o The SYN's payload does not contain any application data (so that 1639 no data is replayed to the server, even though duplicate 1640 connections are still possible), or 1642 o The client uses Idempotence Options, making replays very unlikely, 1643 or 1645 o SOCKS is running on top of TLS and Early Data is not used. 1647 11. False Starts 1649 In case of CONNECT Requests, the client MAY start sending application 1650 data as soon as possible, as long as doing so does not incur the risk 1651 of breaking the SOCKS protocol. 1653 Clients must work around the authentication phase by doing any of the 1654 following: 1656 o If the Request does not contain an Authentication Method 1657 Advertisement option, the authentication phase is guaranteed not 1658 to happen. In this case, application data MAY be sent immediately 1659 after the Request. 1661 o Application data MAY be sent immediately after receiving an 1662 Authentication Reply indicating success. 1664 o When performing a method-specific authentication sequence, 1665 application data MAY be sent immediately after the last client 1666 message. 1668 12. DNS provided by SOCKS 1670 Clients may require information typically obtained from DNS servers, 1671 albeit from the proxy's vantage point. 1673 While the CONNECT command can work with domain names, some clients' 1674 workflows require that addresses be resolved as a separate step prior 1675 to connecting. Moreover, the SOCKS Datagram Header, as described in 1676 Section 7.3, can be reduced in size by providing the resolved 1677 destination IP address, rather than the FQDN. 1679 Emerging techniques may also make use of DNS to deliver server- 1680 specific information to clients. For example, Encrypted SNI 1681 [I-D.ietf-tls-esni] relies on DNS to publish encryption keys. 1683 Proxy implementations MAY provide a default plaintext DNS service. A 1684 client looking to make use of it issues a CONNECT Request to IP 1685 address 0.0.0.0 or 0:0:0:0:0:0:0:0 on port 53. Following successful 1686 authentication, the Operation Reply MAY indicate an unspecified bind 1687 address (0.0.0.0 or ::) and port (0). The client and proxy then 1688 behave as per [RFC7766]. 1690 The service itself can be provided directly by the proxy daemon, or 1691 by proxying the client's request to a pre-configured DNS server. 1693 If the proxy does not implement such functionality, it MAY return an 1694 error code signalling "Connection refused". 1696 13. Security Considerations 1697 13.1. Large requests 1699 Given the format of the request message, a malicious client could 1700 craft a request that is in excess of 16 KB and proxies could be prone 1701 to DDoS attacks. 1703 To mitigate such attacks, proxy implementations SHOULD be able to 1704 incrementally parse the requests. Proxies MAY close the connection 1705 to the client if: 1707 o the request is not fully received after a certain timeout, or 1709 o the number of options or their size exceeds an imposed hard cap. 1711 13.2. Replay attacks 1713 In TLS 1.3, early data (which is likely to contain a full SOCKS 1714 request) is prone to replay attacks. 1716 While Token Expenditure options can be used to mitigate replay 1717 attacks, anything prior to the initial Token Request is still 1718 vulnerable. As such, client implementations SHOULD NOT make use of 1719 TLS early data unless the Request attempts to spend a token. 1721 13.3. Resource exhaustion 1723 Malicious clients can issue a large number of Session Requests, 1724 forcing the proxy to keep large amounts of state. 1726 To mitigate this, the proxy MAY implement policies restricting the 1727 number of concurrent sessions on a per-IP or per-user basis, or 1728 barring unauthenticated clients from establishing sessions. 1730 14. Privacy Considerations 1732 The timing of Operation Replies can reveal some information about a 1733 proxy's recent usage: 1735 o The DNS resolver used by the proxy may cache the answer to recent 1736 queries. As such, subsequent connection attempts to the same 1737 hostname are likely to be slightly faster, even if requested by 1738 different clients. 1740 o Likewise, the proxy's OS typically caches TFO cookies. Repeated 1741 TFO connection attempts tend to be sped up, regardless of the 1742 client. 1744 15. IANA Considerations 1746 This document requests that IANA allocate 2-byte option kinds for 1747 SOCKS 6 options. Further, this document requests the following 1748 option kinds: 1750 o Unassigned: 0 1752 o Stack: 1 1754 o Authentication Method Advertisement: 2 1756 o Authentication Method Selection: 3 1758 o Authentication Data: 4 1760 o Session Request: 5 1762 o Session ID: 6 1764 o Session Untrusted: 7 1766 o Session OK: 8 1768 o Session Invalid: 9 1770 o Session Teardown: 10 1772 o Idempotence Request: 11 1774 o Idempotence Window: 12 1776 o Idempotence Expenditure: 13 1778 o Idempotence Accepted: 14 1780 o Idempotence Rejected: 15 1782 o Resolution Request: 16 1784 o IPv4 Resolution: 17 1786 o IPv6 Resolution: 18 1788 o Vendor-specific: 64512-0xFFFF 1790 This document also requests that IANA allocate a TCP and UDP port for 1791 SOCKS over TLS and DTLS, respectively. 1793 16. Acknowledgements 1795 The protocol described in this draft builds upon and is a direct 1796 continuation of SOCKS 5 [RFC1928]. 1798 17. References 1800 17.1. Normative References 1802 [RFC1929] Leech, M., "Username/Password Authentication for SOCKS 1803 V5", RFC 1929, DOI 10.17487/RFC1929, March 1996, 1804 . 1806 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1807 Requirement Levels", BCP 14, RFC 2119, 1808 DOI 10.17487/RFC2119, March 1997, 1809 . 1811 [RFC7766] Dickinson, J., Dickinson, S., Bellis, R., Mankin, A., and 1812 D. Wessels, "DNS Transport over TCP - Implementation 1813 Requirements", RFC 7766, DOI 10.17487/RFC7766, March 2016, 1814 . 1816 [RFC8305] Schinazi, D. and T. Pauly, "Happy Eyeballs Version 2: 1817 Better Connectivity Using Concurrency", RFC 8305, 1818 DOI 10.17487/RFC8305, December 2017, 1819 . 1821 17.2. Informative References 1823 [I-D.ietf-tls-dtls-connection-id] 1824 Rescorla, E., Tschofenig, H., and T. Fossati, "Connection 1825 Identifiers for DTLS 1.2", draft-ietf-tls-dtls-connection- 1826 id-07 (work in progress), October 2019. 1828 [I-D.ietf-tls-esni] 1829 Rescorla, E., Oku, K., Sullivan, N., and C. Wood, 1830 "Encrypted Server Name Indication for TLS 1.3", draft- 1831 ietf-tls-esni-05 (work in progress), November 2019. 1833 [RFC1928] Leech, M., Ganis, M., Lee, Y., Kuris, R., Koblas, D., and 1834 L. Jones, "SOCKS Protocol Version 5", RFC 1928, 1835 DOI 10.17487/RFC1928, March 1996, 1836 . 1838 [RFC6824] Ford, A., Raiciu, C., Handley, M., and O. Bonaventure, 1839 "TCP Extensions for Multipath Operation with Multiple 1840 Addresses", RFC 6824, DOI 10.17487/RFC6824, January 2013, 1841 . 1843 [RFC7413] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP 1844 Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014, 1845 . 1847 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1848 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1849 . 1851 Authors' Addresses 1853 Vladimir Olteanu 1854 University Politehnica of Bucharest 1855 313 Splaiul Independentei, Sector 6 1856 Bucharest 1857 Romania 1859 Email: vladimir.olteanu@cs.pub.ro 1861 Dragos Niculescu 1862 University Politehnica of Bucharest 1863 313 Splaiul Independentei, Sector 6 1864 Bucharest 1865 Romania 1867 Email: dragos.niculescu@cs.pub.ro