idnits 2.17.1 draft-olteanu-intarea-socks-6-07.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 08, 2019) is 1754 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-06 -- Obsolete informational reference (is this intentional?): RFC 6824 (Obsoleted by RFC 8684) Summary: 0 errors (**), 0 flaws (~~), 2 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 9, 2020 July 08, 2019 7 SOCKS Protocol Version 6 8 draft-olteanu-intarea-socks-6-07 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 9, 2020. 39 Copyright Notice 41 Copyright (c) 2019 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 . . . . . . . . . . . . . . . . . . . . 9 59 3. Mode of operation . . . . . . . . . . . . . . . . . . . . . . 9 60 4. Requests . . . . . . . . . . . . . . . . . . . . . . . . . . 11 61 5. Version Mismatch Replies . . . . . . . . . . . . . . . . . . 13 62 6. Authentication Replies . . . . . . . . . . . . . . . . . . . 13 63 7. Operation Replies . . . . . . . . . . . . . . . . . . . . . . 14 64 7.1. Handling CONNECT . . . . . . . . . . . . . . . . . . . . 16 65 7.2. Handling BIND . . . . . . . . . . . . . . . . . . . . . . 16 66 7.3. Handling UDP ASSOCIATE . . . . . . . . . . . . . . . . . 16 67 7.3.1. Proxying UDP servers . . . . . . . . . . . . . . . . 18 68 7.3.2. Proxying multicast traffic . . . . . . . . . . . . . 18 69 8. SOCKS Options . . . . . . . . . . . . . . . . . . . . . . . . 18 70 8.1. Stack options . . . . . . . . . . . . . . . . . . . . . . 19 71 8.1.1. IP TOS options . . . . . . . . . . . . . . . . . . . 20 72 8.1.2. TFO options . . . . . . . . . . . . . . . . . . . . . 21 73 8.1.3. Multipath options . . . . . . . . . . . . . . . . . . 22 74 8.1.4. Listen Backlog options . . . . . . . . . . . . . . . 22 75 8.2. Authentication Method options . . . . . . . . . . . . . . 23 76 8.3. Authentication Data options . . . . . . . . . . . . . . . 25 77 8.4. Session options . . . . . . . . . . . . . . . . . . . . . 25 78 8.4.1. Session initiation . . . . . . . . . . . . . . . . . 26 79 8.4.2. Further SOCKS Requests . . . . . . . . . . . . . . . 27 80 8.4.3. Tearing down the session . . . . . . . . . . . . . . 28 81 8.5. Idempotence options . . . . . . . . . . . . . . . . . . . 28 82 8.5.1. Requesting a token window . . . . . . . . . . . . . . 29 83 8.5.2. Spending a token . . . . . . . . . . . . . . . . . . 30 84 8.5.3. Shifting windows . . . . . . . . . . . . . . . . . . 31 85 8.5.4. Out-of-order Window Advertisements . . . . . . . . . 31 86 8.6. Address Resolution Options . . . . . . . . . . . . . . . 31 87 8.6.1. Forward resolution . . . . . . . . . . . . . . . . . 31 88 8.6.2. Reverse resolution . . . . . . . . . . . . . . . . . 32 89 9. Username/Password Authentication . . . . . . . . . . . . . . 33 90 10. TCP Fast Open on the Client-Proxy Leg . . . . . . . . . . . . 34 91 11. False Starts . . . . . . . . . . . . . . . . . . . . . . . . 34 92 12. Security Considerations . . . . . . . . . . . . . . . . . . . 35 93 12.1. Large requests . . . . . . . . . . . . . . . . . . . . . 35 94 12.2. Replay attacks . . . . . . . . . . . . . . . . . . . . . 35 95 12.3. Resource exhaustion . . . . . . . . . . . . . . . . . . 35 96 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 97 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 37 98 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 37 99 15.1. Normative References . . . . . . . . . . . . . . . . . . 37 100 15.2. Informative References . . . . . . . . . . . . . . . . . 37 101 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 38 103 1. Introduction 105 Versions 4 and 5 [RFC1928] of the SOCKS protocol were developed two 106 decades ago and are in widespread use for circuit level gateways or 107 as circumvention tools, and enjoy wide support and usage from various 108 software, such as web browsers, SSH clients, and proxifiers. 109 However, their design needs an update in order to take advantage of 110 the new features of transport protocols, such as TCP Fast Open 111 [RFC7413], or to better assist newer transport protocols, such as 112 MPTCP [RFC6824]. 114 One of the main issues faced by SOCKS version 5 is that, when taking 115 into account the TCP handshake, method negotiation, authentication, 116 connection request and grant, it may take up to 5 RTTs for a data 117 exchange to take place at the application layer. This is especially 118 costly in networks with a large delay at the access layer, such as 119 3G, 4G, or satelite. 121 The desire to reduce the number of RTTs manifests itself in the 122 design of newer security protocols. TLS version 1.3 [RFC8446] 123 defines a zero round trip (0-RTT) handshake mode for connections if 124 the client and server had previously communicated. 126 TCP Fast Open [RFC7413] is a TCP option that allows TCP to send data 127 in the SYN and receive a response in the first ACK, and aims at 128 obtaining a data response in one RTT. The SOCKS protocol needs to 129 concern itself with at least two TFO deployment scenarios: First, 130 when TFO is available end-to-end (at the client, at the proxy, and at 131 the server); second, when TFO is active between the client and the 132 proxy, but not at the server. 134 This document describes the SOCKS protocol version 6. The key 135 improvements over SOCKS version 5 are: 137 o The client sends as much information upfront as possible, and does 138 not wait for the authentication process to conclude before 139 requesting the creation of a socket. 141 o The connection request also mimics the semantics of TCP Fast Open 142 [RFC7413]. As part of the connection request, the client can 143 supply the potential payload for the initial SYN that is sent out 144 to the server. 146 o The protocol can be extended via options without breaking 147 backward-compatibility. 149 o The protocol can leverage the aforementioned options to support 150 0-RTT authentication schemes. 152 1.1. Revision log 154 Typos and minor clarifications are not listed. 156 draft-07 158 o All fields are now alignned. 160 o Eliminated version minors 162 o Lots of changes to options 164 * 2-byte option kinds 166 * Flattened option kinds/types/reply codes; also renamed some 167 options 169 * Socket options 171 + Proxies MUST always answer them (Clients can probe for 172 support) 174 + MPTCP Options: expanded functionality ("please do/don't do 175 MPTCP on my behalf") 177 + MPTCP Scheduler options removed 179 + Listen Backlog options: code changed to 0x03 181 * Revamped Idempotence options 183 * Auth data options limited to one per method 185 o Authentication Reply: all authentication-related information is 186 now in the options 188 * Authentication replies no longer have a field indicating the 189 chosen auth. method 191 * Method that must proceed (or whereby authentication succeeded) 192 indicated in options 194 * Username/password authentication: proxy now sends reply in 195 option 197 o Removed requirements w.r.t. caching authentication methods by 198 multihomed clients 200 o UDP: 8-byte association IDs 202 o Sessions 204 * The proxy is now free to terminate ongoing connections along 205 with the session. 207 * The session-terminating request is not part of the session that 208 it terminated. 210 o Address Resolution options 212 draft-06 214 o Session options 216 o Options now have a 2-byte length field. 218 o Stack options 220 * Stack options can no longer contain duplicate information. 222 * TFO: Better payload size semantics 224 * TOS: Added missing code field. 226 * MPTCP Scheduler options: 228 + Removed support for round-robin 230 + "Default" renamed to "Lowest latency first" 232 * Listen Backlog options: now tied to sessions, instead of an 233 authenticated user 235 o Idempotence options 237 * Now used in the context of a session (no longer tied to an 238 authenticated user) 240 * Idempotence options have a different codepoint: 0x05. (Was 241 0x04.) 243 * Clarified that implementations that support Idempotence Options 244 must support all Idempotence Option Types. 246 * Shifted Idempotence Option Types by 1. (Makes implementation 247 easier.) 249 o Shrunk vendor-specific option range to 32 (down from 64). 251 o Removed reference to dropping initial data. (It could no longer 252 be done as of -05.) 254 o Initial data size capped at 16KB. 256 o Application data is never encrypted by SOCKS 6. (It can still be 257 encrypted by the TLS layer under SOCKS.) 259 o Messages now carry the total length of the options, rather than 260 the number of options. Limited options length to 16KB. 262 o Security Considerations 264 * Updated the section to reflect the smaller maximum message 265 size. 267 * Added a subsection on resource exhaustion. 269 draft-05 271 o Limited the "slow" authentication negociations to one (and 272 Authentication Replies to 2) 274 o Revamped the handling of the first bytes in the application data 275 stream 277 * False starts are now recommended. (Added the "False Start" 278 section.) 280 * Initial data is only available to clients willing to do "slow" 281 authentication. Moved the "Initial data size" field from 282 Requests to Authentication Method options. 284 * Initial data size capped at 2^13. Initial data can no longer 285 be dropped by the proxy. 287 * The TFO option can hint at the desired SYN payload size. 289 o Request: clarified the meaning of the Address and Port fields. 291 o Better reverse TCP proxy support: optional listen backlog for TCP 292 BIND 294 o TFO options can no longer be placed inside Operation Replies. 296 o IP TOS stack option 298 o Suggested a range for vendor-specific options. 300 o Revamped UDP functionality 302 * Now using fixed UDP ports 304 * DTLS support 306 o Stack options: renamed Proxy-Server leg to Proxy-Remote leg 308 draft-04 310 o Moved Token Expenditure Replies to the Authentication Reply. 312 o Shifted the Initial Data Size field in the Request, in order to 313 make it easier to parse. 315 draft-03 317 o Shifted some fields in the Operation Reply to make it easier to 318 parse. 320 o Added connection attempt timeout response code to Operation 321 Replies. 323 o Proxies send an additional Authentication Reply after the 324 authentication phase. (Useful for token window advertisements.) 326 o Renamed the section "Connection Requests" to "Requests" 328 o Clarified the fact that proxies don't need to support any command 329 in particular. 331 o Added the section "TCP Fast Open on the Client-Proxy Leg" 333 o Options: 335 * Added constants for option kinds 337 * Salt options removed, along with the relevant section from 338 Security Considerations. (TLS 1.3 Makes AEAD mandatory.) 340 * Limited Authentication Data options to one per method. 342 * Relaxed proxy requirements with regard to handling multiple 343 Authentication Data options. (When the client violates the 344 above bullet point.) 346 * Removed interdependence between Authentication Method and 347 Authentication Data options. 349 * Clients SHOULD omit advertising the "No authentication 350 required" option. (Was MAY.) 352 * Idempotence options: 354 + Token Window Advertisements are now part of successful 355 Authentication Replies (so that the proxy-server RTT has no 356 impact on their timeliness). 358 + Proxies can't advetise token windows of size 0. 360 + Tweaked token expenditure response codes. 362 + Support no longer mandatory on the proxy side. 364 * Revamped Socket options 366 + Renamed Socket options to Stack options. 368 + Banned contradictory socket options. 370 + Added socket level for generic IP. Removed the "socket" 371 socket level. 373 + Stack options no longer use option codes from setsockopt(). 375 + Changed MPTCP Scheduler constants. 377 draft-02 379 o Made support for Idempotence options mandatory for proxies. 381 o Clarified what happens when proxies can not or will not issue 382 tokens. 384 o Limited token windows to 2^31 - 1. 386 o Fixed definition of "less than" for tokens. 388 o NOOP commands now trigger Operation Replies. 390 o Renamed Authentication options to Authentication Data options. 392 o Authentication Data options are no longer mandatory. 394 o Authentication methods are now advertised via options. 396 o Shifted some Request fields. 398 o Option range for vendor-specific options. 400 o Socket options. 402 o Password authentication. 404 o Salt options. 406 draft-01 408 o Added this section. 410 o Support for idempotent commands. 412 o Removed version numbers from operation replies. 414 o Request port number for SOCKS over TLS. Deprecate encryption/ 415 encapsulation within SOCKS. 417 o Added Version Mismatch Replies. 419 o Renamed the AUTH command to NOOP. 421 o Shifted some fields to make requests and operation replies easier 422 to parse. 424 2. Requirements language 426 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 427 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 428 document are to be interpreted as described in [RFC2119]. 430 3. Mode of operation 431 CLIENT PROXY 433 +------------------------+ 434 | Authentication methods | Request 435 --------> Command code +------------------------------> 436 | Address | 437 | Port | 438 | Options | 439 +------------------------+ 441 +------------------------+ 442 --------> Initial data +------------------------------> 443 +------------------------+ 445 +-----------------------+ 446 Authentication Reply | Type | 447 <----------------------------------+ Options <----- 448 +-----------------------+ 450 <-------------------(Authentication protocol)------------------> 452 +-----------------------+ 453 Authentication Reply | Type = Success | 454 <----------------------------------+ Options <----- 455 +-----------------------+ 457 +-----------------------+ 458 Operation Reply | Reply code | 459 <--------------------+ Bind address <------------------ 460 | Bind port | 461 | Options | 462 +-----------------------+ 464 Figure 1: The SOCKS version 6 protocol message exchange 466 When a TCP-based client wishes to establish a connection to a server, 467 it must open a TCP connection to the appropriate SOCKS port on the 468 SOCKS proxy. The client then enters a negotiation phase, by sending 469 the request in Figure 1, that contains, in addition to fields present 470 in SOCKS 5 [RFC1928], fields that facilitate low RTT usage and faster 471 authentication negotiation. 473 Next, the server sends an authentication reply. If the request did 474 not contain the necessary authentication information, the proxy 475 indicates an authentication method that must proceed. This may 476 trigger a longer authentication sequence that could include tokens 477 for ulterior faster authentications. The part labeled 478 "Authentication protocol" is specific to the authentication method 479 employed and is not expected to be employed for every connection 480 between a client and its proxy server. The authentication protocol 481 typically takes up 1 RTT or more. 483 If the authentication is successful, an operation reply is generated 484 by the proxy. It indicates whether the proxy was successful in 485 creating the requested socket or not. 487 In the fast case, when authentication is properly set up, the proxy 488 attempts to create the socket immediately after the receipt of the 489 request, thus achieving an operational conection in one RTT (provided 490 TFO functionality is available at the client, proxy, and server). 492 4. Requests 494 The client starts by sending a request to the proxy. 496 1 2 3 497 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 498 +---------------+---------------+-------------------------------+ 499 | Version = 6 | Command Code | Options Length | 500 +---------------+---------------+---------------+---------------+ 501 | Port | Padding = 0 | Address Type | 502 +-------------------------------+---------------+---------------+ 503 | ... 504 ... Address (variable length) ... 505 ... | 506 +---------------------------------------------------------------+ 507 | ... 508 ... Options (variable length) ... 509 ... | 510 +---------------------------------------------------------------+ 512 Figure 2: SOCKS 6 Request 514 o Version: 6 516 o Command Code: 518 * 0x00 NOOP: does nothing. 520 * 0x01 CONNECT: requests the establishment of a TCP connection. 521 TFO MUST NOT be used unless explicitly requested. 523 * 0x02 BIND: requests the establishment of a TCP port binding. 525 * 0x03 UDP ASSOCIATE: requests a UDP port association. 527 o Address Type: 529 * 0x01: IPv4 531 * 0x03: Domain Name 533 * 0x04: IPv6 535 o Address: this field's format depends on the address type: 537 * IPv4: a 4-byte IPv4 address 539 * Domain Name: one byte that contains the length of the FQDN, 540 followed by the FQDN itself. The string is not NUL-terminated, 541 but padded by NUL characters, if needed. 543 * IPv6: a 16-byte IPv6 address 545 o Port: the port in network byte order. 547 o Padding: set to 0 549 o Options Length: the total size of the SOCKS options that appear in 550 the Options field. MUST NOT exceed 16KB. 552 o Options: see Section 8. 554 The Address and Port fields have different meanings based on the 555 Command Code: 557 o NOOP: The fields have no meaning. The Address Type field MUST be 558 either 0x01 (IPv4) or 0x04 (IPv6). The Address and Port fields 559 MUST be 0. 561 o CONNECT: The fields signify the address and port to which the 562 client wishes to connect. 564 o BIND, UDP ASSOCIATE: The fields indicate the desired bind address 565 and port. If the client does not require a certain address, it 566 can set the Address Type field to 0x01 (IPv4) or 0x04 (IPv6), and 567 the Address field to 0. Likewise, if the client does not require 568 a certain port, it can set the Port field to 0. 570 Clients can advertise their supported authentication methods by 571 including an Authentication Method Advertisement option (see 572 Section 8.2). 574 5. Version Mismatch Replies 576 Upon receipt of a request starting with a version number other than 577 6, the proxy sends the following response: 579 0 1 2 3 4 5 6 7 580 +---------------+ 581 | Version = 6 | 582 +---------------+ 584 Figure 3: SOCKS 6 Version Mismatch Reply 586 o Version: 6 588 A client MUST close the connection after receiving such a reply. 590 6. Authentication Replies 592 Upon receipt of a valid request, the proxy sends an Authentication 593 Reply: 595 1 2 3 596 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 597 +---------------+---------------+-------------------------------+ 598 | Version = 6 | Type | Options Length | 599 +---------------+---------------+-------------------------------+ 600 | ... 601 ... Options (variable length) ... 602 ... | 603 +---------------------------------------------------------------+ 605 Figure 4: SOCKS 6 Authentication Reply 607 o Version: 6 609 o Type: 611 * 0x00: authentication successful. 613 * 0x01: authentication failed. 615 o Options Length: the total size of the SOCKS options that appear in 616 the Options field. MUST NOT exceed 16KB. 618 o Options: see Section 8. 620 If the server signals that the authentication has failed and does not 621 signal that any authentication negotiation can continue (via an 622 Authentication Method Selection option), the client MUST close the 623 connection. 625 The client and proxy begin a method-specific negotiation. During 626 such negotiations, the proxy MAY supply information that allows the 627 client to authenticate a future request using an Authentication Data 628 option. Application data is not subject to any encryption negotiated 629 during this phase. Descriptions of such negotiations are beyond the 630 scope of this memo. 632 When the negotiation is complete (either successfully or 633 unsuccessfully), the proxy sends a second Authentication Reply. The 634 second Authentication Reply MUST NOT allow for further negotiations. 636 7. Operation Replies 638 After the authentication negotiations are complete, the proxy sends 639 an Operation Reply: 641 1 2 3 642 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 643 +---------------+---------------+-------------------------------+ 644 | Version = 6 | Reply Code | Options Length | 645 +---------------+---------------+---------------+---------------+ 646 | Bind Port | Padding = 0 | Address Type | 647 +-------------------------------+---------------+---------------+ 648 | ... 649 ... Bind Address (variable length) ... 650 ... | 651 +---------------------------------------------------------------+ 652 | ... 653 ... Options (variable length) ... 654 ... | 655 +---------------------------------------------------------------+ 657 Figure 5: SOCKS 6 Operation Reply 659 o Version: 6 661 o Reply Code: 663 * 0x00: Succes 665 * 0x01: General SOCKS server failure 666 * 0x02: Connection not allowed by ruleset 668 * 0x03: Network unreachable 670 * 0x04: Host unreachable 672 * 0x05: Connection refused 674 * 0x06: TTL expired 676 * 0x07: Command not supported 678 * 0x08: Address type not supported 680 * 0x09: Connection attempt timed out 682 o Bind Port: the proxy bound port in network byte order. 684 o Padding: set to 0 686 o Address Type: 688 * 0x01: IPv4 690 * 0x03: Domain Name 692 * 0x04: IPv6 694 o Bind Address: the proxy bound address in the following format: 696 * IPv4: a 4-byte IPv4 address 698 * Domain Name: one byte that contains the length of the FQDN, 699 followed by the FQDN itself. The string is not NUL-terminated, 700 but padded by NUL characters, if needed. 702 * IPv6: a 16-byte IPv6 address 704 o Options Length: the total size of the SOCKS options that appear in 705 the Options field. MUST NOT exceed 16KB. 707 o Options: see Section 8. 709 Proxy implementations MAY support any subset of the client commands 710 listed in Section 4. 712 If the proxy returns a reply code other than "Success", the client 713 MUST close the connection. 715 If the client issued an NOOP command, the client MUST close the 716 connection after receiving the Operation Reply. 718 7.1. Handling CONNECT 720 In case the client has issued a CONNECT request, data can now pass. 722 7.2. Handling BIND 724 In case the client has issued a BIND request, it must wait for a 725 second Operation reply from the proxy, which signifies that a host 726 has connected to the bound port. The Bind Address and Bind Port 727 fields contain the address and port of the connecting host. 728 Afterwards, application data may pass. 730 7.3. Handling UDP ASSOCIATE 732 Proxies offering UDP functionality must be configured with a UDP port 733 used for relaying UDP datagrams to and from the client, and/or a port 734 used for relaying datagrams over DTLS. 736 Following a successful Operation Reply, the proxy sends a UDP 737 Association Initialization message: 739 1 2 3 740 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 741 +---------------------------------------------------------------+ 742 | Association ID | 743 | (8 bytes) | 744 +---------------------------------------------------------------+ 746 Figure 6: UDP Association Initialization 748 o Association ID: the identifier of the UDP association 750 Proxy implementations SHOULD generate Association IDs randomly or 751 pseudo-randomly. 753 Clients may start sending UDP datagrams to the proxy either in 754 plaintext, or over an established DTLS session, using the proxy's 755 configured UDP ports. A client's datagrams are prefixed by a SOCKS 756 Datagram Header, indicating the remote host's address and port: 758 1 2 3 759 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 760 +---------------+---------------+-------------------------------+ 761 | Version = 6 | Address Type | Port | 762 +---------------+---------------+-------------------------------+ 763 | Association ID | 764 | (8 bytes) | 765 +---------------------------------------------------------------+ 766 | ... 767 ... Address (variable length) ... 768 ... | 769 +---------------------------------------------------------------+ 771 Figure 7: SOCKS 6 Datagram Header 773 o Version: 0x06 775 o Association ID: the identifier of the UDP association 777 o Address Type: 779 * 0x01: IPv4 781 * 0x03: Domain Name 783 * 0x04: IPv6 785 o Address: this field's format depends on the address type: 787 * IPv4: a 4-byte IPv4 address 789 * Domain Name: one byte that contains the length of the FQDN, 790 followed by the FQDN itself. The string is not NUL-terminated. 792 * IPv6: a 16-byte IPv6 address 794 o Port: the port in network byte order. 796 Following the receipt of the first datagram from the client, the 797 proxy makes a one-way mapping between the Association ID and: 799 o the 5-tuple of the UDP conversation, if the datagram was received 800 over plain UDP, or 802 o the DTLS connection, if the datagram was received over DTLS. The 803 DTLS connection is identified either by its 5-tuple, or some other 804 mechanism, like [I-D.ietf-tls-dtls-connection-id]. 806 Further datagrams carrying the same Association ID, but not matching 807 the established mapping, are silently dropped. 809 The proxy then sends an UDP Association Confirmation message over the 810 TCP connection with the client: 812 0 1 2 3 4 5 6 7 813 +---------------+ 814 | Status = 0 | 815 +---------------+ 817 Figure 8: UDP Association Confirmation 819 o Status: MUST be 0x00 821 Following the confirmation message, UDP packets bound for the proxy's 822 bind address and port are relayed to the client, also prefixed by a 823 Datagram Header. 825 The UDP association remains active for as long as the TCP connection 826 between the client and the proxy is kept open. 828 7.3.1. Proxying UDP servers 830 Under some circumstances (e.g. when hosting a server), the SOCKS 831 client expects the remote host to send UDP datagrams first. As such, 832 the SOCKS client must trigger a UDP Association Confirmation without 833 having the proxy relay any datagrams on its behalf. 835 To that end, it sends an empty datagram prefixed by a Datagram Header 836 with an IP address and port consisting of zeroes. The client SHOULD 837 resend the empty datagram if an UDP Association Confirmation is not 838 received after a timeout. 840 7.3.2. Proxying multicast traffic 842 The use of multicast addessses is permitted for UDP traffic only. 844 8. SOCKS Options 846 SOCKS options have the following format: 848 1 2 3 849 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 850 +-------------------------------+-------------------------------+ 851 | Kind | Length | 852 +-------------------------------+-------------------------------+ 853 | ... 854 ... Option Data (variable length) ... 855 ... | 856 +---------------------------------------------------------------+ 858 Figure 9: SOCKS 6 Option 860 o Kind: Allocated by IANA. (See Section 13.) 862 o Length: The total length of the option. MUST be a multiple of 4. 864 o Option Data: The contents are specific to each option kind. 866 Unless otherwise noted, client and proxy implementations MAY omit 867 supporting any of the options described in this document. Upon 868 encountering an unsupported option, a SOCKS endpoint MUST silently 869 ignore it. 871 8.1. Stack options 873 Stack options can be used by clients to alter the behavior of the 874 protocols on top of which SOCKS is running, as well the protcols used 875 by the proxy to communicate with the remote host (i.e. IP, TCP, 876 UDP). A Stack option can affect either the proxy's protocol on the 877 client-proxy leg or on the proxy-remote leg. Clients can only place 878 Stack options inside SOCKS Requests. 880 Proxies MAY choose not to honor any Stack options sent by the client. 882 Proxies include Stack options in their Operation Replies to signal 883 their behavior, and MUST do so for every supported Stack option sent 884 by the client. Said options MAY also be unsolicited, i. e. the proxy 885 MAY send them to signal behaviour that was not explicitly requested 886 by the client. 888 If a particular Stack option is unsupported, the proxy MUST silently 889 ignore it. 891 In case of UDP ASSOCIATE, the stack options refer to the UDP traffic 892 relayed by the proxy. 894 Stack options that are part of the same message MUST NOT contradict 895 one another or contain duplicate information. 897 1 2 3 898 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 899 +-------------------------------+-------------------------------+ 900 | Kind = 1 | Length | 901 +---+-----------+---------------+-------------------------------+ 902 |Leg| Level | Code | ... 903 +---+-----------+---------------+ ... 904 ... ... 905 ... Option Data (variable length) ... 906 ... | 907 +---------------------------------------------------------------+ 909 Figure 10: Stack Option 911 o Leg: 913 * 1: Client-Proxy Leg 915 * 2: Proxy-Remote Leg 917 * 3: Both Legs 919 o Level: 921 * 1: IP: options that apply to either IPv4 or IPv6 923 * 2: IPv4 925 * 3: IPv6 927 * 4: TCP 929 * 5: UDP 931 o Code: Option code 933 o Option Data: Option-specific data 935 8.1.1. IP TOS options 936 1 2 3 937 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 938 +-------------------------------+-------------------------------+ 939 | Kind = 1 | Length = 8 | 940 +---+-----------+---------------+---------------+---------------+ 941 |Leg| Level = 1 | Code = 1 | TOS | Padding = 0 | 942 +---+-----------+---------------+---------------+---------------+ 944 Figure 11: IP TOS Option 946 o TOS: The IP TOS code 948 The client can use IP TOS options to request that the proxy use a 949 certain value for the IP TOS field. Likewise, the proxy can use IP 950 TOS options to advertise the TOS values being used. 952 8.1.2. TFO options 954 1 2 3 955 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 956 +-------------------------------+-------------------------------+ 957 | Kind = 1 | Length = 8 | 958 +---+-----------+---------------+-------------------------------+ 959 |Leg| Level = 4 | Code = 1 | Payload Size | 960 +---+-----------+---------------+-------------------------------+ 962 Figure 12: TFO Option 964 o Leg: 0x02 (Proxy-Remote leg). 966 o Payload Size: The desired payload size of the TFO SYN. Ignored in 967 case of a BIND command. 969 If a SOCKS Request contains a TFO option, the proxy SHOULD attempt to 970 use TFO in case of a CONNECT command, or accept TFO in case of a BIND 971 command. Otherwise, the proxy MUST NOT attempt to use TFO in case of 972 a CONNECT command, or accept TFO in case of a BIND command. 974 In case of a CONNECT command, the client can indicate the desired 975 payload size of the SYN. If the field is 0, the proxy can use an 976 arbitrary payload size. If the field is non-zero, the proxy MUST NOT 977 use a payload size larger than the one indicated. The proxy MAY use 978 a smaller payload size than the one indicated. 980 8.1.3. Multipath options 982 In case of a CONNECT or BIND command, the client can inform the proxy 983 whether MPTCP is desired on the proxy-remote leg by sending a 984 Multipath option. 986 Conversely, the proxy can use a Multipath option to convey the 987 following information: * whether or not the connection uses MPTCP or 988 not, when replying to a CONNECT command, or in the second Operation 989 reply to a BIND command, or * whether an MPTCP connection will be 990 accepted, when first replying to a BIND command. 992 1 2 3 993 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 994 +-------------------------------+-------------------------------+ 995 | Kind = 1 | Length = 8 | 996 +---+-----------+---------------+---------------+---------------+ 997 |Leg| Level = 4 | Code = 2 | Availability | Padding = 0 | 998 +---+-----------+---------------+---------------+---------------+ 1000 Figure 13: Multipath Option 1002 o Leg: 0x02 (Proxy-Remote leg) 1004 o Availability: 1006 * 0x01: MPTCP is not desired or available 1008 * 0x02: MPTCP is desired or available 1010 In the absence of such an option, the proxy SHOULD NOT enable MPTCP. 1012 8.1.4. Listen Backlog options 1014 1 2 3 1015 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 1016 +-------------------------------+-------------------------------+ 1017 | Kind = 1 | Length = 8 | 1018 +---+-----------+---------------+-------------------------------+ 1019 |Leg| Level = 4 | Code = 3 | Backlog | 1020 +---+-----------+---------------+-------------------------------+ 1022 Figure 14: Listen Backlog Option 1024 o Leg: 0x02 (Proxy-Remote leg) 1025 o Backlog: The length of the listen backlog. 1027 The default behavior of the BIND does not allow a client to 1028 simultaneously handle multiple connections to the same bind address. 1029 A client can alter BIND's behavior by adding a TCP Listen Backlog 1030 Option to a BIND Request, provided that the Request is part of a 1031 Session. 1033 In response, the proxy sends a TCP Listen Backlog Option as part of 1034 the Operation Reply, with the Backlog field signalling the actual 1035 backlog used. The proxy SHOULD NOT use a backlog longer than 1036 requested. 1038 Following the successful negotiation of a backlog, the proxy listens 1039 for incoming connections for as long as the initial connection stays 1040 open. The initial connection is not used to relay data between the 1041 client and a remote host. 1043 To accept connections, the client issues further BIND Requests using 1044 the bind address and port supplied by the proxy in the initial 1045 Operation Reply. Said BIND requests must belong to the same Session 1046 as the original Request. 1048 If no backlog is issued, the proxy signals a backlog length of 0, and 1049 BIND's behavior remains unaffected. 1051 8.2. Authentication Method options 1053 A client that is willing to go through the authentication phase MUST 1054 include an Authentication Method Advertisement option in its Request. 1055 In case of a CONNECT Request, the option is also used to specify the 1056 amount of initial data supplied before any method-specific 1057 authentication negotiations take place. 1059 1 2 3 1060 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 1061 +-------------------------------+-------------------------------+ 1062 | Kind = 2 | Length | 1063 +-------------------------------+-------------------------------+ 1064 | Initial Data Length | ... 1065 +-------------------------------+ ... 1066 ... ... 1067 ... Methods (variable length) ... 1068 ... ... 1069 ... +-----------------------------------------------+ 1070 ... | Padding = 0 (variable length, 0-3 bytes) | 1071 +---------------+-----------------------------------------------+ 1073 Figure 15: Authentication Method Advertisement Option 1075 o Initial Data Size: A two-byte number in network byte order. In 1076 case of CONNECT, this is the number of bytes of initial data that 1077 are supplied by the client immediately following the Request. 1078 This number MUST NOT be larger than 2^14. 1080 o Methods: One byte per advertised method. Method numbers are 1081 assigned by IANA. 1083 o Padding: A minimally-sized sequence of zeroes, such that the 1084 option length is a multiple of 4. Note that 0 coincides with the 1085 value for "No Authentication Required". 1087 Clients MUST support the "No authentication required" method. 1088 Clients SHOULD omit advertising the "No authentication required" 1089 option. 1091 The proxy indicates which authentication method must proceed by 1092 sending an Authentication Method Selection option in the 1093 corresponding Authentication Reply: 1095 1 2 3 1096 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 1097 +-------------------------------+-------------------------------+ 1098 | Kind = 3 | Length = 8 | 1099 +---------------+---------------+-------------------------------+ 1100 | Method | Padding = 0 | 1101 +---------------+-----------------------------------------------+ 1103 Figure 16: Authentication Method Selection Option 1105 o Method: The selected method. 1107 If the proxy selects "No Acceptable Methods", the client MUST close 1108 the connection. 1110 If authentication is successful via some other means, or not required 1111 at all, the proxy silently ignores the Authentication Method 1112 Advertisement option. 1114 8.3. Authentication Data options 1116 Authentication Data options carry method-specific authentication 1117 data. They can be part of SOCKS Requests and Authentication Replies. 1119 Authentication Data options have the following format: 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 = 4 | Length | 1125 +---------------+---------------+-------------------------------+ 1126 | Method | ... 1127 +---------------+ ... 1128 ... ... 1129 ... Authentication Data (variable length) ... 1130 ... | 1131 +---------------------------------------------------------------+ 1133 Figure 17: Authentication Data Option 1135 o Method: The number of the authentication method. These numbers 1136 are assigned by IANA. 1138 o Authentication Data: The contents are specific to each method. 1140 Clients MUST only place one Authentication Data option per 1141 authentication method. 1143 8.4. Session options 1145 Clients and proxies can establish SOCKS sessions, which span one or 1146 more Requests. All session-related negotiations are done via Session 1147 Options, which are placed in Requests and Authentication Replies by 1148 the client and, respectively, by the proxy. 1150 Client and proxy implementations MUST either support all Session 1151 Option Types, or none. 1153 8.4.1. Session initiation 1155 A client can initiate a session by sending a Session Request Option: 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 = 5 | Length = 4 | 1161 +-------------------------------+-------------------------------+ 1163 Figure 18: Session Request Option 1165 The proxy then replies with a Session ID Option in the successful 1166 Operation Reply: 1168 1 2 3 1169 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 1170 +-------------------------------+-------------------------------+ 1171 | Kind = 6 | Length | 1172 +-------------------------------+-------------------------------+ 1173 | ... 1174 ... Session ID (variable length) ... 1175 ... | 1176 +---------------------------------------------------------------+ 1178 Figure 19: Session ID Option 1180 o Session ID: An opaque sequence of bytes specific to the session. 1181 The size MUST be a multiple of 4. MUST NOT be empty. 1183 The Session ID serves to identify the session and is opaque to the 1184 client. 1186 The credentials, or lack thereof, used to initiate the session are 1187 tied to the session. If authentication is to be performed for 1188 further Requests, the session is deemed "untrusted", and the proxy 1189 also places a Session Untrusted option in the Authentication Reply: 1191 1 2 3 1192 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 1193 +-------------------------------+-------------------------------+ 1194 | Kind = 7 | Length = 4 | 1195 +-------------------------------+-------------------------------+ 1197 Figure 20: Session Untrusted Option 1199 The SOCKS Request that initiated the session is considered part of 1200 the session. A client MUST NOT attempt to initiate a session from 1201 within a different session. 1203 If the proxy can not or will not honor the Session Request, it does 1204 so silently. 1206 8.4.2. Further SOCKS Requests 1208 Any further SOCKS Requests that are part of the session MUST include 1209 a Session ID Option (as seen in Figure 19). 1211 The authentication procedure is altered based on the Session ID's 1212 validity and whether or not the Session is untrusted. 1214 For valid Session IDs: 1216 o If the session is untrusted, the proxy MUST reject clients that do 1217 not authenticate using the same method and credentials that were 1218 used to initiate the session. 1220 o Otherwise, the proxy MUST silently ignore any authentication 1221 attempt in the Request, and MUST NOT require any authentication. 1223 The proxy then replies by placing a Session OK option in the 1224 successful Authentication Reply: 1226 1 2 3 1227 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 1228 +-------------------------------+-------------------------------+ 1229 | Kind = 8 | Length = 4 | 1230 +-------------------------------+-------------------------------+ 1232 Figure 21: Session OK Option 1234 If the ticket is invalid, the first Authentication Reply MUST signal 1235 that authentication failed and can not continue (by setting the Type 1236 field to 0x01). Further, it SHALL contain a Session Invalid option: 1238 1 2 3 1239 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 1240 +-------------------------------+-------------------------------+ 1241 | Kind = 9 | Length = 4 | 1242 +-------------------------------+-------------------------------+ 1244 Figure 22: Session Invalid Option 1246 8.4.3. Tearing down the session 1248 Proxies can, at their discretion, tear down a session and free all 1249 associated state. Proxy implementations SHOULD feature a timeout 1250 mechanism that destroys sessions after a period of inactivity. When 1251 a session is terminated, the proxy MAY close all connections 1252 associated with said session. 1254 Clients can signal that a session is no longer needed, and can be 1255 torn down, by sending a Session Teardown option in addition to the 1256 Session ID option: 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 = 10 | Length = 4 | 1262 +-------------------------------+-------------------------------+ 1264 Figure 23: Session Teardown Option 1266 After sending such an option, the client MUST assume that the session 1267 is no longer valid. The proxy MUST treat the connection-terminating 1268 request as if it were not part of any session. 1270 8.5. Idempotence options 1272 To protect against duplicate SOCKS Requests, clients can request, and 1273 then spend, idempotence tokens. A token can only be spent on a 1274 single SOCKS request. 1276 Tokens are 4-byte unsigned integers in a modular 4-byte space. 1277 Therefore, if x and y are tokens, x is less than y if 0 < (y - x) < 1278 2^31 in unsigned 32-bit arithmetic. 1280 Proxies grant contiguous ranges of tokens called token windows. 1281 Token windows are defined by their base (the first token in the 1282 range) and size. 1284 All token-related operations are done via Idempotence options. 1286 Idempotence options are only valid in the context of a SOCKS Session. 1287 If a SOCKS Request is not part of a Session (either by supplying a 1288 valid Session ID or successfully initiating one via a Session 1289 Request), the proxy MUST silently ignore any Idempotence options. 1291 Token windows are tracked by the proxy on a per-session basis. There 1292 can be at most one token window for every session and its tokens can 1293 only be spent from within said session. 1295 Client and proxy implementations MUST either support all Idempotence 1296 Option Types, or none. 1298 8.5.1. Requesting a token window 1300 A client can obtain a window of tokens by sending an Idempotence 1301 Request option as part of a SOCKS Request: 1303 1 2 3 1304 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 1305 +-------------------------------+-------------------------------+ 1306 | Kind = 11 | Length = 8 | 1307 +-------------------------------+-------------------------------+ 1308 | Window Size | 1309 +---------------------------------------------------------------+ 1311 Figure 24: Token Request 1313 o Window Size: The requested window size. 1315 Once a token window is issued, the proxy MUST include an Idempotence 1316 Window option in all subsequent successful Authentication Replies: 1318 1 2 3 1319 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 1320 +-------------------------------+-------------------------------+ 1321 | Kind = 12 | Length = 12 | 1322 +-------------------------------+-------------------------------+ 1323 | Window Base | 1324 +---------------------------------------------------------------+ 1325 | Window Size | 1326 +---------------------------------------------------------------+ 1328 Figure 25: Idempotence Window 1330 o Window Base: The first token in the window. 1332 o Window Size: The window size. This value MAY differ from the 1333 requested window size. Window sizes MUST be less than 2^31. 1334 Window sizes MUST NOT be 0. 1336 If no token window is issued, the proxy MUST silently ignore the 1337 Token Request. If there is already a token window associated with 1338 the session, the proxy MUST NOT issue a new window. 1340 8.5.2. Spending a token 1342 The client can attempt to spend a token by including a Idempotence 1343 Expenditure option in its SOCKS request: 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 = 13 | Length = 8 | 1349 +-------------------------------+-------------------------------+ 1350 | Token | 1351 +---------------------------------------------------------------+ 1353 Figure 26: Idempotence Expenditure 1355 o Kind: 13 (Idempotence Expenditure option) 1357 o Length: 8 1359 o Token: The token being spent. 1361 Clients SHOULD prioritize spending the smaller tokens. 1363 The proxy responds by sending either an Idempotence Accepted or 1364 Rejected option as part of the Authentication Reply: 1366 1 2 3 1367 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 1368 +-------------------------------+-------------------------------+ 1369 | Kind = 14 | Length = 8 | 1370 +-------------------------------+-------------------------------+ 1372 Figure 27: Idempotence Accepted 1374 1 2 3 1375 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 1376 +-------------------------------+-------------------------------+ 1377 | Kind = 15 | Length = 8 | 1378 +-------------------------------+-------------------------------+ 1380 Figure 28: Idempotence Rejected 1382 If eligible, the token is spent before attempting to honor the 1383 Request. If the token is not eligible for spending, the 1384 Authentication Reply MUST indicate failure. 1386 8.5.3. Shifting windows 1388 Windows can be shifted (i. e. have their base increased, while 1389 retaining their size) unilaterally by the proxy. 1391 Proxy implementations SHOULD shift the window: * as soon as the 1392 lowest-order token in the window is spent and * when a sufficiently 1393 high-order token is spent. 1395 Proxy implementations SHOULD NOT shift the window's base beyond the 1396 highest unspent token. 1398 8.5.4. Out-of-order Window Advertisements 1400 Even though the proxy increases the window's base monotonically, 1401 there is no mechanism whereby a SOCKS client can receive the Token 1402 Window Advertisements in order. As such, clients SHOULD disregard 1403 Token Window Advertisements with a Window Base less than the 1404 previously known value. 1406 8.6. Address Resolution Options 1408 Clients wishing to resolve an address from the proxy's vantage point 1409 can do so by sending a Resolution Request option: 1411 1 2 3 1412 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 1413 +-------------------------------+-------------------------------+ 1414 | Kind = 16 | Length = 4 | 1415 +-------------------------------+-------------------------------+ 1417 Figure 29: Resolution Request 1419 The proxy's reply is included in the Operation Reply. 1421 8.6.1. Forward resolution 1423 If the address supplied by the client is a Domain Name, the proxy 1424 sends a Resolution option for each supported address type: 1426 1 2 3 1427 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 1428 +-------------------------------+-------------------------------+ 1429 | Kind = 17 | Length | 1430 +-------------------------------+-------------------------------+ 1431 | ... 1432 ... IPv4 Addresses (variable length) ... 1433 ... | 1434 +---------------------------------------------------------------+ 1436 Figure 30: IPv4 Resolution 1438 o IPv4 Addresses: The resolved IPv4 addresses. 1440 1 2 3 1441 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 1442 +-------------------------------+-------------------------------+ 1443 | Kind = 18 | Length | 1444 +-------------------------------+-------------------------------+ 1445 | ... 1446 ... IPv6 Addresses (variable length) ... 1447 ... | 1448 +---------------------------------------------------------------+ 1450 Figure 31: IPv6 Resolution 1452 o IPv6 Addresses: The resolved IPv6 addresses. 1454 If resolving a given address type is supported, but no addresses were 1455 found, the proxy MUST send an empty option, rather than none at all. 1456 If the proxy does not support resolving either one of the address 1457 types, it MUST omit sending the corrresponding option. 1459 8.6.2. Reverse resolution 1461 If the client supplies either an IPv4 or IPv6 address, the proxy 1462 performs a reverse lookup and replies with a list of domain names: 1464 1 2 3 1465 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 1466 +-------------------------------+-------------------------------+ 1467 | Kind = 18 | Length | 1468 +-------------------------------+-------------------------------+ 1469 | ... 1470 ... Domain Names (variable length) ... 1471 ... | 1472 +---------------------------------------------------------------+ 1474 Figure 32: Domain Name Resolution 1476 o Domain Names: The resolved domain names. Their format is the same 1477 as the one used in Requests and Operation Replies, with each 1478 string being individially padded. (See Section 4.) 1480 If no domain names could be found, the proxy MUST send an empty 1481 option. If reverse resolution is unsupported, the proxy MUST NOT 1482 send any such option. 1484 9. Username/Password Authentication 1486 Username/Password authentication is carried out as in [RFC1929]. 1488 Clients can also attempt to authenticate by placing the Username/ 1489 Password request in an Authentication Data Option. 1491 1 2 3 1492 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 1493 +-------------------------------+-------------------------------+ 1494 | Kind = 4 | Length | 1495 +---------------+---------------+---------------+---------------+ 1496 | Method = 2 | ... 1497 +---------------+ ... 1498 ... ... 1499 ... Username/Password Request ... 1500 ... ... 1501 ... +-----------------------------------------------+ 1502 ... | Padding = 0 (variable length, 0-3 bytes) | 1503 +---------------+-----------------------------------------------+ 1505 Figure 33: Password authentication via a SOCKS Option 1507 o Username/Password Request: The Username/Password Request, as 1508 described in [RFC1929]. 1510 Proxies reply by including a Authentication Data Option in the next 1511 Authentication Reply which contains the Username/Password reply: 1513 1 2 3 1514 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 1515 +-------------------------------+-------------------------------+ 1516 | Kind = 4 | Length = 8 | 1517 +---------------+---------------+---------------+---------------+ 1518 | Method = 2 | Username/Password Reply | Padding = 0 | 1519 +---------------+-------------------------------+---------------+ 1521 Figure 34: Reply to password authentication via a SOCKS Option 1523 o Username/Password Reply: The Username/Password Reply, as described 1524 in [RFC1929]. 1526 10. TCP Fast Open on the Client-Proxy Leg 1528 TFO breaks TCP semantics, causing replays of the data in the SYN's 1529 payload under certain rare circumstances [RFC7413]. A replayed SOCKS 1530 Request could itself result in a replayed connection on behalf of the 1531 client. 1533 As such, client implementations SHOULD NOT use TFO on the client- 1534 proxy leg unless: 1536 o The protocol running on top of SOCKS tolerates the risks of TFO, 1537 or 1539 o The SYN's payload does not contain any application data (so that 1540 no data is replayed to the server, even though duplicate 1541 connections are still possible), or 1543 o The client uses Idempotence Options, making replays very unlikely, 1544 or 1546 o SOCKS is running on top of TLS and Early Data is not used. 1548 11. False Starts 1550 In case of CONNECT Requests, the client MAY start sending application 1551 data as soon as possible, as long as doing so does not incur the risk 1552 of breaking the SOCKS protocol. 1554 Clients must work around the authentication phase by doing any of the 1555 following: 1557 o If the Request does not contain an Authentication Method 1558 Advertisement option, the authentication phase is guaranteed not 1559 to happen. In this case, application data MAY be sent immediately 1560 after the Request. 1562 o Application data MAY be sent immediately after receiving an 1563 Authentication Reply indicating success. 1565 o When performing a method-specific authentication sequence, 1566 application data MAY be sent immediately after the last client 1567 message. 1569 12. Security Considerations 1571 12.1. Large requests 1573 Given the format of the request message, a malicious client could 1574 craft a request that is in excess of 16 KB and proxies could be prone 1575 to DDoS attacks. 1577 To mitigate such attacks, proxy implementations SHOULD be able to 1578 incrementally parse the requests. Proxies MAY close the connection 1579 to the client if: 1581 o the request is not fully received after a certain timeout, or 1583 o the number of options or their size exceeds an imposed hard cap. 1585 12.2. Replay attacks 1587 In TLS 1.3, early data (which is likely to contain a full SOCKS 1588 request) is prone to replay attacks. 1590 While Token Expenditure options can be used to mitigate replay 1591 attacks, anything prior to the initial Token Request is still 1592 vulnerable. As such, client implementations SHOULD NOT make use of 1593 TLS early data unless the Request attempts to spend a token. 1595 12.3. Resource exhaustion 1597 Malicious clients can issue a large number of Session Requests, 1598 forcing the proxy to keep large amounts of state. 1600 To mitigate this, the proxy MAY implement policies restricting the 1601 number of concurrent sessions on a per-IP or per-user basis, or 1602 barring unauthenticated clients from establishing sessions. 1604 13. IANA Considerations 1606 This document requests that IANA allocate 2-byte option kinds for 1607 SOCKS 6 options. Further, this document requests the following 1608 option kinds: 1610 o Unassigned: 0 1612 o Stack: 1 1614 o Authentication Method Advertisement: 2 1616 o Authentication Method Selection: 3 1618 o Authentication Data: 4 1620 o Session Request: 5 1622 o Session ID: 6 1624 o Session Untrusted: 7 1626 o Session OK: 8 1628 o Session Invalid: 9 1630 o Session Teardown: 10 1632 o Idempotence Request: 11 1634 o Idempotence Window: 12 1636 o Idempotence Expenditure: 13 1638 o Idempotence Accepted: 14 1640 o Idempotence Rejected: 15 1642 o Resolution Request: 16 1644 o IPv4 Resolution: 17 1646 o IPv6 Resolution: 18 1648 o Domain Name Resolution: 19 1650 o Vendor-specific: 64512-0xFFFF 1651 This document also requests that IANA allocate a TCP and UDP port for 1652 SOCKS over TLS and DTLS, respectively. 1654 14. Acknowledgements 1656 The protocol described in this draft builds upon and is a direct 1657 continuation of SOCKS 5 [RFC1928]. 1659 15. References 1661 15.1. Normative References 1663 [RFC1929] Leech, M., "Username/Password Authentication for SOCKS 1664 V5", RFC 1929, DOI 10.17487/RFC1929, March 1996, 1665 . 1667 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1668 Requirement Levels", BCP 14, RFC 2119, 1669 DOI 10.17487/RFC2119, March 1997, 1670 . 1672 15.2. Informative References 1674 [I-D.ietf-tls-dtls-connection-id] 1675 Rescorla, E., Tschofenig, H., and T. Fossati, "Connection 1676 Identifiers for DTLS 1.2", draft-ietf-tls-dtls-connection- 1677 id-06 (work in progress), July 2019. 1679 [RFC1928] Leech, M., Ganis, M., Lee, Y., Kuris, R., Koblas, D., and 1680 L. Jones, "SOCKS Protocol Version 5", RFC 1928, 1681 DOI 10.17487/RFC1928, March 1996, 1682 . 1684 [RFC6824] Ford, A., Raiciu, C., Handley, M., and O. Bonaventure, 1685 "TCP Extensions for Multipath Operation with Multiple 1686 Addresses", RFC 6824, DOI 10.17487/RFC6824, January 2013, 1687 . 1689 [RFC7413] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP 1690 Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014, 1691 . 1693 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1694 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1695 . 1697 Authors' Addresses 1699 Vladimir Olteanu 1700 University Politehnica of Bucharest 1701 313 Splaiul Independentei, Sector 6 1702 Bucharest 1703 Romania 1705 Email: vladimir.olteanu@cs.pub.ro 1707 Dragos Niculescu 1708 University Politehnica of Bucharest 1709 313 Splaiul Independentei, Sector 6 1710 Bucharest 1711 Romania 1713 Email: dragos.niculescu@cs.pub.ro