pt-spec.txt 26 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741
  1. Pluggable Transport Specification (Version 1)
  2. Abstract
  3. Pluggable Transports (PTs) are a generic mechanism for the rapid
  4. development and deployment of censorship circumvention,
  5. based around the idea of modular sub-processes that transform
  6. traffic to defeat censors.
  7. This document specifies the sub-process startup, shutdown,
  8. and inter-process communication mechanisms required to utilize
  9. PTs.
  10. Table of Contents
  11. 1. Introduction
  12. 1.1. Requirements Notation
  13. 2. Architecture Overview
  14. 3. Specification
  15. 3.1. Pluggable Transport Naming
  16. 3.2. Pluggable Transport Configuration Environment Variables
  17. 3.2.1. Common Environment Variables
  18. 3.2.2. Pluggable Transport Client Environment Variables
  19. 3.2.3. Pluggable Transport Server Environment Variables
  20. 3.3. Pluggable Transport To Parent Process Communication
  21. 3.3.1. Common Messages
  22. 3.3.2. Pluggable Transport Client Messages
  23. 3.3.3. Pluggable Transport Server Messages
  24. 3.4. Pluggable Transport Shutdown
  25. 3.5. Pluggable Transport Client Per-Connection Arguments
  26. 4. Anonymity Considerations
  27. 5 References
  28. 6. Acknowledgments
  29. Appendix A. Example Client Pluggable Transport Session
  30. Appendix B. Example Server Pluggable Transport Session
  31. 1. Introduction
  32. This specification describes a way to decouple protocol-level
  33. obfuscation from an application's client/server code, in a manner
  34. that promotes rapid development of obfuscation/circumvention
  35. tools and promotes reuse beyond the scope of the Tor Project's
  36. efforts in that area.
  37. This is accomplished by utilizing helper sub-processes that
  38. implement the necessary forward/reverse proxy servers that handle
  39. the censorship circumvention, with a well defined and
  40. standardized configuration and management interface.
  41. Any application code that implements the interfaces as specified
  42. in this document will be able to use all spec compliant Pluggable
  43. Transports.
  44. 1.1. Requirements Notation
  45. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
  46. NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
  47. "OPTIONAL" in this document are to be interpreted as described in
  48. [RFC2119].
  49. 2. Architecture Overview
  50. +------------+ +---------------------------+
  51. | Client App +-- Local Loopback --+ PT Client (SOCKS Proxy) +--+
  52. +------------+ +---------------------------+ |
  53. |
  54. Public Internet (Obfuscated/Transformed traffic) ==> |
  55. |
  56. +------------+ +---------------------------+ |
  57. | Server App +-- Local Loopback --+ PT Server (Reverse Proxy) +--+
  58. +------------+ +---------------------------+
  59. On the client's host, the PT Client software exposes a SOCKS proxy
  60. [RFC1928] to the client application, and obfuscates or otherwise
  61. transforms traffic before forwarding it to the server's host.
  62. On the server's host, the PT Server software exposes a reverse proxy
  63. that accepts connections from PT Clients, and handles reversing the
  64. obfuscation/transformation applied to traffic, before forwarding it
  65. to the actual server software. An optional lightweight protocol
  66. exists to facilitate communicating connection meta-data that would
  67. otherwise be lost such as the source IP address and port
  68. [EXTORPORT].
  69. All PT instances are configured by the respective parent process via
  70. a set of standardized environment variables (3.2) that are set at
  71. launch time, and report status information back to the parent via
  72. writing output in a standardized format to stdout (3.3).
  73. Each invocation of a PT MUST be either a client OR a server.
  74. All PT client forward proxies MUST support either SOCKS 4 or SOCKS 5,
  75. and SHOULD prefer SOCKS 5 over SOCKS 4.
  76. 3. Specification
  77. Pluggable Transport proxies follow the following workflow
  78. throughout their lifespan.
  79. 1) Parent process sets the required environment values (3.2)
  80. and launches the PT proxy as a sub-process (fork()/exec()).
  81. 2) The PT Proxy determines the versions of the PT specification
  82. supported by the parent"TOR_PT_MANAGED_TRANSPORT_VER" (3.2.1)
  83. 2.1) If there are no compatible versions, the PT proxy
  84. writes a "VERSION-ERROR" message (3.3.1) to stdout and
  85. terminates.
  86. 2.2) If there is a compatible version, the PT proxy writes
  87. a "VERSION" message (3.3.1) to stdout.
  88. 3) The PT Proxy parses the rest of the environment values.
  89. 3.1) If the environment values are malformed, or otherwise
  90. invalid, the PT proxy writes a "ENV-ERROR" message
  91. (3.3.1) to stdout and terminates.
  92. 3.2) Determining if it is a client side forward proxy or
  93. a server side reverse proxy can be done via examining
  94. the "TOR_PT_CLIENT_TRANSPORTS" and "TOR_PT_SERVER_TRANSPORTS"
  95. environment variables.
  96. 4) (Client only) If there is an upstream proxy specified via
  97. "TOR_PT_PROXY" (3.2.2), the PT proxy validates the URI
  98. provided.
  99. 4.1) If the upstream proxy is unusable, the PT proxy writes
  100. a "PROXY-ERROR" message (3.3.2) to stdout and
  101. terminates.
  102. 4.2) If there is a supported and well-formed upstream proxy
  103. the PT proxy writes a "PROXY DONE" message (3.3.2) to
  104. stdout.
  105. 5) The PT Proxy initializes the transports and reports the
  106. status via stdout (3.3.2, 3.3.3)
  107. 6) The PT Proxy forwards and transforms traffic as appropriate.
  108. 7) Upon being signaled to terminate by the parent process (3.4),
  109. the PT Proxy gracefully shuts down.
  110. 3.1. Pluggable Transport Naming
  111. Pluggable Transport names serve as unique identifiers, and every
  112. PT MUST have a unique name.
  113. PT names MUST be valid C identifiers. PT names MUST begin with
  114. a letter or underscore, and the remaining characters MUST be
  115. ASCII letters, numbers or underscores. No length limit is
  116. imposted.
  117. PT names MUST satisfy the regular expression "[a-zA-Z_][a-zA-Z0-9_]*".
  118. 3.2. Pluggable Transport Configuration Environment Variables
  119. All Pluggable Transport proxy instances are configured by their
  120. parent process at launch time via a set of well defined
  121. environment variables.
  122. The "TOR_PT_" prefix is used for namespacing reasons and does not
  123. indicate any relations to Tor, except for the origins of this
  124. specification.
  125. 3.2.1. Common Environment Variables
  126. When launching either a client or server Pluggable Transport proxy,
  127. the following common environment variables MUST be set.
  128. "TOR_PT_MANAGED_TRANSPORT_VER"
  129. Specifies the versions of the Pluggable Transport specification
  130. the parent process supports, delimited by commas. All PTs MUST
  131. accept any well-formed list, as long as a compatible version is
  132. present.
  133. Valid versions MUST consist entirely of non-whitespace,
  134. non-comma printable ASCII characters.
  135. The version of the Pluggable Transport specification as of this
  136. document is "1".
  137. Example:
  138. TOR_PT_MANAGED_TRANSPORT_VER=1,1a,2b,this_is_a_valid_ver
  139. "TOR_PT_STATE_LOCATION"
  140. Specifies an absolute path to a directory where the PT is
  141. allowed to store state that will be persisted across
  142. invocations. The directory is not required to exist when
  143. the PT is launched, however PT implementations SHOULD be
  144. able to create it as required.
  145. PTs MUST only store files in the path provided, and MUST NOT
  146. create or modify files elsewhere on the system.
  147. Example:
  148. TOR_PT_STATE_LOCATION=/var/lib/tor/pt_state/
  149. "TOR_PT_EXIT_ON_STDIN_CLOSE"
  150. Specifies that the parent process will close the PT proxy's
  151. standard input (stdin) stream to indicate that the PT proxy
  152. should gracefully exit.
  153. PTs MUST NOT treat a closed stdin as a signal to terminate
  154. unless this environment variable is set to "1".
  155. PTs SHOULD treat stdin being closed as a signal to gracefully
  156. terminate if this environment variable is set to "1".
  157. Example:
  158. TOR_PT_EXIT_ON_STDIN_CLOSE=1
  159. 3.2.2. Pluggable Transport Client Environment Variables
  160. Client-side Pluggable Transport forward proxies are configured
  161. via the following environment variables.
  162. "TOR_PT_CLIENT_TRANSPORTS"
  163. Specifies the PT protocols the client proxy should initialize,
  164. as a comma separated list of PT names.
  165. PTs SHOULD ignore PT names that it does not recognize.
  166. Parent processes MUST set this environment variable when
  167. launching a client-side PT proxy instance.
  168. Example:
  169. TOR_PT_CLIENT_TRANSPORTS=obfs2,obfs3,obfs4
  170. "TOR_PT_PROXY"
  171. Specifies an upstream proxy that the PT MUST use when making
  172. outgoing network connections. It is a URI [RFC3986] of the
  173. format:
  174. <proxy_type>://[<user_name>[:<password>][@]<ip>:<port>.
  175. The "TOR_PT_PROXY" environment variable is OPTIONAL and
  176. MUST be omitted if there is no need to connect via an
  177. upstream proxy.
  178. Examples:
  179. TOR_PT_PROXY=socks5://tor:test1234@198.51.100.1:8000
  180. TOR_PT_PROXY=socks4a://198.51.100.2:8001
  181. TOR_PT_PROXY=http://198.51.100.3:443
  182. 3.2.3. Pluggable Transport Server Environment Variables
  183. Server-side Pluggable Transport reverse proxies are configured
  184. via the following environment variables.
  185. "TOR_PT_SERVER_TRANSPORTS"
  186. Specifies the PT protocols the server proxy should initialize,
  187. as a comma separated list of PT names.
  188. PTs SHOULD ignore PT names that it does not recognize.
  189. Parent processes MUST set this environment variable when
  190. launching a server-side PT reverse proxy instance.
  191. Example:
  192. TOR_PT_SERVER_TRANSPORTS=obfs3,scramblesuit
  193. "TOR_PT_SERVER_TRANSPORT_OPTIONS"
  194. Specifies per-PT protocol configuration directives, as a
  195. semicolon-separated list of <key>:<value> pairs, where <key>
  196. is a PT name and <value> is a k=v string value with options
  197. that are to be passed to the transport.
  198. Colons, semicolons, equal signs and backslashes MUST be
  199. escaped with a backslash.
  200. If there are no arguments that need to be passed to any of
  201. PT transport protocols, "TOR_PT_SERVER_TRANSPORT_OPTIONS"
  202. MAY be omitted.
  203. Example:
  204. TOR_PT_SERVER_TRANSPORT_OPTIONS=scramblesuit:key=banana;automata:rule=110;automata:depth=3
  205. Will pass to 'scramblesuit' the parameter 'key=banana' and to
  206. 'automata' the arguments 'rule=110' and 'depth=3'.
  207. "TOR_PT_SERVER_BINDADDR"
  208. A comma separated list of <key>-<value> pairs, where <key> is
  209. a PT name and <value> is the <address>:<port> on which it
  210. should listen for incoming client connections.
  211. The keys holding transport names MUST be in the same order as
  212. they appear in "TOR_PT_SERVER_TRANSPORTS".
  213. The <address> MAY be a locally scoped address as long as port
  214. forwarding is done externally.
  215. The <address>:<port> combination MUST be an IP address
  216. supported by `bind()`, and MUST NOT be a host name.
  217. Applications MUST NOT set more than one <address>:<port> pair
  218. per PT name.
  219. If there is no specific <address>:<port> combination to be
  220. configured for any transports, "TOR_PT_SERVER_BINDADDR" MAY
  221. be omitted.
  222. Example:
  223. TOR_PT_SERVER_BINDADDR=obfs3-198.51.100.1:1984,scramblesuit-127.0.0.1:4891
  224. "TOR_PT_ORPORT"
  225. Specifies the destination that the PT reverse proxy should forward
  226. traffic to after transforming it as appropriate, as an
  227. <address>:<port>.
  228. Connections to the destination specified via "TOR_PT_ORPORT"
  229. MUST only contain application payload. If the parent process
  230. requires the actual source IP address of client connections
  231. (or other metadata), it should set "TOR_PT_EXTENDED_SERVER_PORT"
  232. instead.
  233. Example:
  234. TOR_PT_ORPORT=127.0.0.1:9001
  235. "TOR_PT_EXTENDED_SERVER_PORT"
  236. Specifies the destination that the PT reverse proxy should
  237. forward traffic to, via the Extended ORPort protocol [EXTORPORT]
  238. as an <address>:<port>.
  239. The Extended ORPort protocol allows the PT reverse proxy to
  240. communicate per-connection metadata such as the PT name and
  241. client IP address/port to the parent process.
  242. If the parent process does not support the ExtORPort protocol,
  243. it MUST set "TOR_PT_EXTENDED_SERVER_PORT" to an empty string.
  244. Example:
  245. TOR_PT_EXTENDED_SERVER_PORT=127.0.0.1:4200
  246. "TOR_PT_AUTH_COOKIE_FILE"
  247. Specifies an absolute filesystem path to the Extended ORPort
  248. authentication cookie, required to communicate with the
  249. Extended ORPort specified via "TOR_PT_EXTENDED_SERVER_PORT".
  250. If the parent process is not using the ExtORPort protocol for
  251. incoming traffic, "TOR_PT_AUTH_COOKIE_FILE" MUST be omitted.
  252. Example:
  253. TOR_PT_AUTH_COOKIE_FILE=/var/lib/tor/extended_orport_auth_cookie
  254. 3.3. Pluggable Transport To Parent Process Communication
  255. All Pluggable Transport Proxies communicate to the parent process
  256. via writing NL-terminated lines to stdout. The line metaformat is:
  257. <Line> ::= <Keyword> <OptArgs> <NL>
  258. <Keyword> ::= <KeywordChar> | <Keyword> <KeywordChar>
  259. <KeywordChar> ::= <any US-ASCII alphanumeric, dash, and underscore>
  260. <OptArgs> ::= <Args>*
  261. <Args> ::= <SP> <ArgChar> | <Args> <ArgChar>
  262. <ArgChar> ::= <any US-ASCII character but NUL or NL>
  263. <SP> ::= <US-ASCII whitespace symbol (32)>
  264. <NL> ::= <US-ASCII newline (line feed) character (10)>
  265. The parent process MUST ignore lines received from PT proxies with
  266. unknown keywords.
  267. 3.3.1. Common Messages
  268. When a PT proxy first starts up, it must determine which version
  269. of the Pluggable Transports Specification to use to configure
  270. itself.
  271. It does this via the "TOR_PT_MANAGED_TRANSPORT_VER" (3.2.1)
  272. environment variable which contains all of the versions supported
  273. by the application.
  274. Upon determining the version to use, or lack thereof, the PT
  275. proxy responds with one of two messages.
  276. VERSION-ERROR <ErrorMessage>
  277. The "VERSION-ERROR" message is used to signal that there was
  278. no compatible Pluggable Transport Specification version
  279. present in the "TOR_PT_MANAGED_TRANSPORT_VER" list.
  280. The <ErrorMessage> SHOULD be set to "no-version" for
  281. historical reasons but MAY be set to a useful error message
  282. instead.
  283. PT proxies MUST terminate after outputting a "VERSION-ERROR"
  284. message.
  285. Example:
  286. VERSION-ERROR no-version
  287. VERSION <ProtocolVersion>
  288. The "VERSION" message is used to signal the Pluggable Transport
  289. Specification version (as in "TOR_PT_MANAGED_TRANSPORT_VER")
  290. that the PT proxy will use to configure it's transports and
  291. communicate with the parent process.
  292. The version for the environment values and reply messages
  293. specified by this document is "1".
  294. PT proxies MUST either report an error and terminate, or output
  295. a "VERSION" message before moving on to client/server proxy
  296. initialization and configuration.
  297. Example:
  298. VERSION 1
  299. After version negotiation has been completed the PT proxy must
  300. then validate that all of the required environment variables are
  301. provided, and that all of the configuration values supplied are
  302. well formed.
  303. At any point, if there is an error encountered related to
  304. configuration supplied via the environment variables, it MAY
  305. respond with an error message and terminate.
  306. ENV-ERROR <ErrorMessage>
  307. The "ENV-ERROR" message is used to signal the PT proxy's
  308. failure to parse the configuration environment variables (3.2).
  309. The <ErrorMessage> SHOULD consist of a useful error message
  310. that can be used to diagnose and correct the root cause of
  311. the failure.
  312. PT proxies MUST terminate after outputting a "ENV-ERROR"
  313. message.
  314. Example:
  315. ENV-ERROR No TOR_PT_AUTH_COOKIE_FILE when TOR_PT_EXTENDED_SERVER_PORT set
  316. 3.3.2. Pluggable Transport Client Messages
  317. After negotiating the Pluggable Transport Specification version,
  318. PT client proxies MUST first validate "TOR_PT_PROXY" (3.2.2) if
  319. it is set, before initializing any transports.
  320. Assuming that an upstream proxy is provided, PT client proxies
  321. MUST respond with a message indicating that the proxy is valid,
  322. supported, and will be used OR a failure message.
  323. PROXY DONE
  324. The "PROXY DONE" message is used to signal the PT proxy's
  325. acceptance of the upstream proxy specified by "TOR_PT_PROXY".
  326. PROXY-ERROR <ErrorMessage>
  327. The "PROXY-ERROR" message is used to signal that the upstream
  328. proxy is malformed/unsupported or otherwise unusable.
  329. PT proxies MUST terminate immediately after outputting a
  330. "PROXY-ERROR" message.
  331. Example:
  332. PROXY-ERROR SOCKS 4 upstream proxies unsupported.
  333. After the upstream proxy (if any) is configured, PT clients then
  334. iterate over the requested transports in "TOR_PT_CLIENT_TRANSPORTS"
  335. and initialize the listeners.
  336. For each transport initialized, the PT proxy reports the listener
  337. status back to the parent via messages to stdout.
  338. CMETHOD <transport> <'socks4','socks5'> <address:port>
  339. The "CMETHOD" message is used to signal that a requested
  340. PT transport has been launched, the protocol which the parent
  341. should use to make outgoing connections, and the IP address
  342. and port that the PT transport's forward proxy is listening on.
  343. Example:
  344. CMETHOD trebuchet socks5 127.0.0.1:19999
  345. CMETHOD-ERROR <transport> <ErrorMessage>
  346. The "CMETHOD-ERROR" message is used to signal that
  347. requested PT transport was unable to be launched.
  348. Example:
  349. CMETHOD-ERROR trebuchet no rocks available
  350. Once all PT transports have been initialized (or have failed), the
  351. PT proxy MUST send a final message indicating that it has finished
  352. initializing.
  353. CMETHODS DONE
  354. The "CMETHODS DONE" message signals that the PT proxy has
  355. finished initializing all of the transports that it is capable
  356. of handling.
  357. Upon sending the "CMETHODS DONE" message, the PT proxy
  358. initialization is complete.
  359. Notes:
  360. - Unknown transports in "TOR_PT_CLIENT_TRANSPORTS" are ignored
  361. entirely, and MUST NOT result in a "CMETHOD-ERROR" message.
  362. Thus it is entirely possible for a given PT proxy to
  363. immediately output "CMETHODS DONE".
  364. - Parent processes MUST handle "CMETHOD"/"CMETHOD-ERROR"
  365. messages in any order, regardless of ordering in
  366. "TOR_PT_CLIENT_TRANSPORTS".
  367. 3.3.3. Pluggable Transport Server Messages
  368. PT server reverse proxies iterate over the requested transports
  369. in "TOR_PT_CLIENT_TRANSPORTS" and initialize the listeners.
  370. For each transport initialized, the PT proxy reports the listener
  371. status back to the parent via messages to stdout.
  372. SMETHOD <transport> <address:port> [options]
  373. The "SMETHOD" message is used to signal that a requested
  374. PT transport has been launched, the protocol which will be
  375. used to handle incoming connections, and the IP address and
  376. port that clients should use to reach the reverse-proxy.
  377. If there is a specific <address:port> provided for a given
  378. PT transport via "TOR_PT_SERVER_BINDADDR", the transport
  379. MUST be initialized using that as the server address.
  380. The OPTIONAL 'options' field is used to pass additional
  381. per-transport information back to the parent process.
  382. The currently recognized 'options' are:
  383. ARGS:[<Key>=<Value>,]+[<Key>=<Value>]
  384. The "ARGS" option is used to pass additional key/value
  385. formatted information that clients will require to use
  386. the reverse proxy.
  387. Equal signs and commas MUST be escaped with a backslash.
  388. Tor: The ARGS are included in the transport line of the
  389. Bridge's extra-info document.
  390. Examples:
  391. SMETHOD trebuchet 198.51.100.1:19999
  392. SMETHOD rot_by_N 198.51.100.1:2323 ARGS:N=13
  393. SMETHOD-ERROR <transport> <ErrorMessage>
  394. The "SMETHOD-ERROR" message is used to signal that
  395. requested PT transport reverse proxy was unable to be
  396. launched.
  397. Example:
  398. SMETHOD-ERROR trebuchet no cows available
  399. Once all PT transports have been initialized (or have failed), the
  400. PT proxy MUST send a final message indicating that it has finished
  401. initializing.
  402. SMETHODS DONE
  403. The "SMETHODS DONE" message signals that the PT proxy has
  404. finished initializing all of the transports that it is capable
  405. of handling.
  406. Upon sending the "SMETHODS DONE" message, the PT proxy
  407. initialization is complete.
  408. 3.4. Pluggable Transport Shutdown
  409. The recommended way for Pluggable Transport using applications and
  410. Pluggable Transports to handle graceful shutdown is as follows.
  411. - (Parent) Set "TOR_PT_EXIT_ON_STDIN_CLOSE" (3.2.1) when
  412. launching the PT proxy, to indicate that stdin will be used
  413. for graceful shutdown notification.
  414. - (Parent) When the time comes to terminate the PT proxy:
  415. 1. Close the PT proxy's stdin.
  416. 2. Wait for a "reasonable" amount of time for the PT to exit.
  417. 3. Attempt to use OS specific mechanisms to cause graceful
  418. PT shutdown (eg: 'SIGTERM')
  419. 4. Use OS specific mechanisms to force terminate the PT
  420. (eg: 'SIGKILL', 'ProccessTerminate()').
  421. - PT proxies SHOULD monitor stdin, and exit gracefully when
  422. it is closed, if the parent supports that behavior.
  423. - PT proxies SHOULD handle OS specific mechanisms to gracefully
  424. terminate (eg: Install a signal handler on 'SIGTERM' that
  425. causes cleanup and a graceful shutdown if able).
  426. - PT proxies SHOULD attempt to detect when the parent has
  427. terminated (eg: via detecting that it's parent process ID haso
  428. changed on U*IX systems), and gracefully terminate.
  429. 3.5. Pluggable Transport Client Per-Connection Arguments
  430. Certain PT transport protocols require that the client provides
  431. per-connection arguments when making outgoing connections. On
  432. the server side, this is handled by the "ARGS" optional argument
  433. as part of the "SMETHOD" message.
  434. On the client side, arguments are passed via the authentication
  435. fields that are part of the SOCKS protocol.
  436. First the "<Key>=<Value>" formatted arguments MUST be escaped,
  437. such that all backslash, equal sign, and semicolon characters
  438. are escaped with a backslash.
  439. Second, all of the escaped are concatenated together.
  440. Example:
  441. shared-secret=rahasia;secrets-file=/tmp/blob
  442. Lastly the arguments are transmitted when making the outgoing
  443. connection using the authentication mechanism specific to the
  444. SOCKS protocol version.
  445. - In the case of SOCKS 4, the concatenated argument list is
  446. transmitted in the "USERID" field of the "CONNECT" request.
  447. - In the case of SOCKS 5, the parent process must negotiate
  448. "Username/Password" authentication [RFC1929], and transmit
  449. the arguments encoded in the "UNAME" and "PASSWD" fields.
  450. If the encoded argument list is less than 255 bytes in
  451. length, the "PLEN" field must be set to "1" and the "PASSWD"
  452. field must contain a single NUL character.
  453. 4. Anonymity Considerations
  454. When designing and implementing a Pluggable Transport, care
  455. should be taken to preserve the privacy of clients and to avoid
  456. leaking personally identifying information.
  457. Examples of client related considerations are:
  458. - Not logging client IP addresses to disk.
  459. - Not leaking DNS addresses except when necessary.
  460. - Ensuring that "TOR_PT_PROXY"'s "fail closed" behavior is
  461. implemented correctly.
  462. Additionally, certain obfuscation mechanisms rely on information
  463. such as the server IP address/port being confidential, so clients
  464. also need to take care to preserve server side information
  465. confidential when applicable.
  466. 5. References
  467. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
  468. Requirement Levels", BCP 14, RFC 2119, March 1997.
  469. [RFC1928] Leech, M., Ganis, M., Lee, Y., Kuris, R.,
  470. Koblas, D., Jones, L., "SOCKS Protocol Version 5",
  471. RFC 1928, March 1996.
  472. [EXTORPORT] Kadianakis, G., Mathewson, N., "Extended ORPort and
  473. TransportControlPort", Tor Proposal 196, March 2012.
  474. [RFC3986] Berners-Lee, T., Fielding, R., Masinter, L., "Uniform
  475. Resource Identifier (URI): Generic Syntax", RFC 3986,
  476. January 2005.
  477. [RFC1929] Leech, M., "Username/Password Authentication for
  478. SOCKS V5", RFC 1929, March 1996.
  479. 6. Acknowledgments
  480. This specification draws heavily from prior versions done by Jacob
  481. Appelbaum, Nick Mathewson, and George Kadianakis.
  482. Appendix A. Example Client Pluggable Transport Session
  483. Environment variables:
  484. TOR_PT_MANAGED_TRANSPORT_VER=1
  485. TOR_PT_STATE_LOCATION=/var/lib/tor/pt_state/
  486. TOR_PT_EXIT_ON_STDIN_CLOSE=1
  487. TOR_PT_PROXY=socks5://127.0.0.1:8001
  488. TOR_PT_CLIENT_TRANSPORTS=obfs3,obfs4
  489. Messages the PT Proxy writes to stdin:
  490. VERSION 1
  491. PROXY DONE
  492. CMETHOD obfs3 socks5 127.0.0.1:32525
  493. CMETHOD obfs4 socks5 127.0.0.1:37347
  494. CMETHODS DONE
  495. Appendix B. Example Server Pluggable Transport Session
  496. Environment variables:
  497. TOR_PT_MANAGED_TRANSPORT_VER=1
  498. TOR_PT_STATE_LOCATION=/var/lib/tor/pt_state
  499. TOR_PT_EXIT_ON_STDIN_CLOSE=1
  500. TOR_PT_SERVER_TRANSPORTS=obfs3,obfs4
  501. TOR_PT_SERVER_BINDADDR=obfs3-198.51.100.1:1984
  502. Messages the PT Proxy writes to stdin:
  503. VERSION 1
  504. SMETHOD obfs3 198.51.100.1:1984
  505. SMETHOD obfs4 198.51.100.1:43734 ARGS:cert=HszPy3vWfjsESCEOo9ZBkRv6zQ/1mGHzc8arF0y2SpwFr3WhsMu8rK0zyaoyERfbz3ddFw,iat-mode=0
  506. SMETHODS DONE