attic/text_formats/pt-spec.txt

   1              Pluggable Transport Specification (Version 1)
   2
   3 Abstract
   4
   5    Pluggable Transports (PTs) are a generic mechanism for the rapid
   6    development and deployment of censorship circumvention,
   7    based around the idea of modular sub-processes that transform
   8    traffic to defeat censors.
   9
  10    This document specifies the sub-process startup, shutdown,
  11    and inter-process communication mechanisms required to utilize
  12    PTs.
  13
  14 Table of Contents
  15
  16    1. Introduction
  17       1.1. Requirements Notation
  18    2. Architecture Overview
  19    3. Specification
  20       3.1. Pluggable Transport Naming
  21       3.2. Pluggable Transport Configuration Environment Variables
  22            3.2.1. Common Environment Variables
  23            3.2.2. Pluggable Transport Client Environment Variables
  24            3.2.3. Pluggable Transport Server Environment Variables
  25       3.3. Pluggable Transport To Parent Process Communication
  26            3.3.1. Common Messages
  27            3.3.2. Pluggable Transport Client Messages
  28            3.3.3. Pluggable Transport Server Messages
  29       3.4. Pluggable Transport Shutdown
  30       3.5. Pluggable Transport Client Per-Connection Arguments
  31    4. Anonymity Considerations
  32    5 References
  33    6. Acknowledgments
  34    Appendix A. Example Client Pluggable Transport Session
  35    Appendix B. Example Server Pluggable Transport Session
  36
  37 1. Introduction
  38
  39    This specification describes a way to decouple protocol-level
  40    obfuscation from an application's client/server code, in a manner
  41    that promotes rapid development of obfuscation/circumvention
  42    tools and promotes reuse beyond the scope of the Tor Project's
  43    efforts in that area.
  44
  45    This is accomplished by utilizing helper sub-processes that
  46    implement the necessary forward/reverse proxy servers that handle
  47    the censorship circumvention, with a well defined and
  48    standardized configuration and management interface.
  49
  50    Any application code that implements the interfaces as specified
  51    in this document will be able to use all spec compliant Pluggable
  52    Transports.
  53
  54 1.1.  Requirements Notation
  55
  56    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
  57    NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
  58    "OPTIONAL" in this document are to be interpreted as described in
  59    [RFC2119].
  60
  61 2. Architecture Overview
  62
  63      +------------+                    +---------------------------+
  64      | Client App +-- Local Loopback --+ PT Client (SOCKS Proxy)   +--+
  65      +------------+                    +---------------------------+  |
  66                                                                       |
  67                  Public Internet (Obfuscated/Transformed traffic) ==> |
  68                                                                       |
  69      +------------+                    +---------------------------+  |
  70      | Server App +-- Local Loopback --+ PT Server (Reverse Proxy) +--+
  71      +------------+                    +---------------------------+
  72
  73    On the client's host, the PT Client software exposes a SOCKS proxy
  74    [RFC1928] to the client application, and obfuscates or otherwise
  75    transforms traffic before forwarding it to the server's host.
  76
  77    On the server's host, the PT Server software exposes a reverse proxy
  78    that accepts connections from PT Clients, and handles reversing the
  79    obfuscation/transformation applied to traffic, before forwarding it
  80    to the actual server software.  An optional lightweight protocol
  81    exists to facilitate communicating connection meta-data that would
  82    otherwise be lost such as the source IP address and port
  83    [EXTORPORT].
  84
  85    All PT instances are configured by the respective parent process via
  86    a set of standardized environment variables (3.2) that are set at
  87    launch time, and report status information back to the parent via
  88    writing output in a standardized format to stdout (3.3).
  89
  90    Each invocation of a PT MUST be either a client OR a server.
  91
  92    All PT client forward proxies MUST support either SOCKS 4 or SOCKS 5,
  93    and SHOULD prefer SOCKS 5 over SOCKS 4.
  94
  95 3. Specification
  96
  97    Pluggable Transport proxies follow the following workflow
  98    throughout their lifespan.
  99
 100      1) Parent process sets the required environment values (3.2)
 101         and launches the PT proxy as a sub-process (fork()/exec()).
 102
 103      2) The PT Proxy determines the versions of the PT specification
 104         supported by the parent"TOR_PT_MANAGED_TRANSPORT_VER" (3.2.1)
 105
 106         2.1) If there are no compatible versions, the PT proxy
 107              writes a "VERSION-ERROR" message (3.3.1) to stdout and
 108              terminates.
 109
 110         2.2) If there is a compatible version, the PT proxy writes
 111              a "VERSION" message (3.3.1) to stdout.
 112
 113      3) The PT Proxy parses the rest of the environment values.
 114
 115         3.1) If the environment values are malformed, or otherwise
 116              invalid, the PT proxy writes a "ENV-ERROR" message
 117              (3.3.1) to stdout and terminates.
 118
 119         3.2) Determining if it is a client side forward proxy or
 120              a server side reverse proxy can be done via examining
 121              the "TOR_PT_CLIENT_TRANSPORTS" and "TOR_PT_SERVER_TRANSPORTS"
 122              environment variables.
 123
 124      4) (Client only) If there is an upstream proxy specified via
 125         "TOR_PT_PROXY" (3.2.2), the PT proxy validates the URI
 126         provided.
 127
 128         4.1) If the upstream proxy is unusable, the PT proxy writes
 129              a "PROXY-ERROR" message (3.3.2) to stdout and
 130              terminates.
 131
 132         4.2) If there is a supported and well-formed upstream proxy
 133              the PT proxy writes a "PROXY DONE" message (3.3.2) to
 134              stdout.
 135
 136      5) The PT Proxy initializes the transports and reports the
 137         status via stdout (3.3.2, 3.3.3)
 138
 139      6) The PT Proxy forwards and transforms traffic as appropriate.
 140
 141      7) Upon being signaled to terminate by the parent process (3.4),
 142         the PT Proxy gracefully shuts down.
 143
 144 3.1. Pluggable Transport Naming
 145
 146    Pluggable Transport names serve as unique identifiers, and every
 147    PT MUST have a unique name.
 148
 149    PT names MUST be valid C identifiers.  PT names MUST begin with
 150    a letter or underscore, and the remaining characters MUST be
 151    ASCII letters, numbers or underscores.  No length limit is
 152    imposted.
 153
 154    PT names MUST satisfy the regular expression "[a-zA-Z_][a-zA-Z0-9_]*".
 155
 156 3.2. Pluggable Transport Configuration Environment Variables
 157
 158    All Pluggable Transport proxy instances are configured by their
 159    parent process at launch time via a set of well defined
 160    environment variables.
 161
 162    The "TOR_PT_" prefix is used for namespacing reasons and does not
 163    indicate any relations to Tor, except for the origins of this
 164    specification.
 165
 166 3.2.1. Common Environment Variables
 167
 168    When launching either a client or server Pluggable Transport proxy,
 169    the following common environment variables MUST be set.
 170
 171      "TOR_PT_MANAGED_TRANSPORT_VER"
 172
 173        Specifies the versions of the Pluggable Transport specification
 174        the parent process supports, delimited by commas.  All PTs MUST
 175        accept any well-formed list, as long as a compatible version is
 176        present.
 177
 178        Valid versions MUST consist entirely of non-whitespace,
 179        non-comma printable ASCII characters.
 180
 181        The version of the Pluggable Transport specification as of this
 182        document is "1".
 183
 184        Example:
 185
 186          TOR_PT_MANAGED_TRANSPORT_VER=1,1a,2b,this_is_a_valid_ver
 187
 188      "TOR_PT_STATE_LOCATION"
 189
 190        Specifies an absolute path to a directory where the PT is
 191        allowed to store state that will be persisted across
 192        invocations.  The directory is not required to exist when
 193        the PT is launched, however PT implementations SHOULD be
 194        able to create it as required.
 195
 196        PTs MUST only store files in the path provided, and MUST NOT
 197        create or modify files elsewhere on the system.
 198
 199        Example:
 200
 201          TOR_PT_STATE_LOCATION=/var/lib/tor/pt_state/
 202
 203      "TOR_PT_EXIT_ON_STDIN_CLOSE"
 204
 205        Specifies that the parent process will close the PT proxy's
 206        standard input (stdin) stream to indicate that the PT proxy
 207        should gracefully exit.
 208
 209        PTs MUST NOT treat a closed stdin as a signal to terminate
 210        unless this environment variable is set to "1".
 211
 212        PTs SHOULD treat stdin being closed as a signal to gracefully
 213        terminate if this environment variable is set to "1".
 214
 215        Example:
 216
 217          TOR_PT_EXIT_ON_STDIN_CLOSE=1
 218
 219      "TOR_PT_OUTBOUND_BIND_ADDRESS_V4"
 220
 221        Specifies an IPv4 IP address that the PT proxy SHOULD use as source address for
 222        outgoing IPv4 IP packets. This feature allows people with multiple network
 223        interfaces to specify explicitly which interface they prefer the PT proxy to
 224        use.
 225
 226        If this value is unset or empty, the PT proxy MUST use the default source
 227        address for outgoing connections.
 228
 229        This setting MUST be ignored for connections to
 230        loopback addresses (127.0.0.0/8).
 231
 232        Example:
 233
 234          TOR_PT_OUTBOUND_BIND_ADDRESS_V4=203.0.113.4
 235
 236      "TOR_PT_OUTBOUND_BIND_ADDRESS_V6"
 237
 238        Specifies an IPv6 IP address that the PT proxy SHOULD use as source address for
 239        outgoing IPv6 IP packets. This feature allows people with multiple network
 240        interfaces to specify explicitly which interface they prefer the PT proxy to
 241        use.
 242
 243        If this value is unset or empty, the PT proxy MUST use the default source
 244        address for outgoing connections.
 245
 246        This setting MUST be ignored for connections to the loopback address ([::1]).
 247
 248        IPv6 addresses MUST always be wrapped in square brackets.
 249
 250        Example::
 251
 252          TOR_PT_OUTBOUND_BIND_ADDRESS_V6=[2001:db8::4]
 253
 254 3.2.2. Pluggable Transport Client Environment Variables
 255
 256    Client-side Pluggable Transport forward proxies are configured
 257    via the following environment variables.
 258
 259      "TOR_PT_CLIENT_TRANSPORTS"
 260
 261        Specifies the PT protocols the client proxy should initialize,
 262        as a comma separated list of PT names.
 263
 264        PTs SHOULD ignore PT names that it does not recognize.
 265
 266        Parent processes MUST set this environment variable when
 267        launching a client-side PT proxy instance.
 268
 269        Example:
 270
 271          TOR_PT_CLIENT_TRANSPORTS=obfs2,obfs3,obfs4
 272
 273      "TOR_PT_PROXY"
 274
 275        Specifies an upstream proxy that the PT MUST use when making
 276        outgoing network connections.  It is a URI [RFC3986] of the
 277        format:
 278
 279          <proxy_type>://[<user_name>[:<password>][@]<ip>:<port>.
 280
 281        The "TOR_PT_PROXY" environment variable is OPTIONAL and
 282        MUST be omitted if there is no need to connect via an
 283        upstream proxy.
 284
 285          Examples:
 286
 287            TOR_PT_PROXY=socks5://tor:test1234@198.51.100.1:8000
 288            TOR_PT_PROXY=socks4a://198.51.100.2:8001
 289            TOR_PT_PROXY=http://198.51.100.3:443
 290
 291 3.2.3. Pluggable Transport Server Environment Variables
 292
 293    Server-side Pluggable Transport reverse proxies are configured
 294    via the following environment variables.
 295
 296      "TOR_PT_SERVER_TRANSPORTS"
 297
 298        Specifies the PT protocols the server proxy should initialize,
 299        as a comma separated list of PT names.
 300
 301        PTs SHOULD ignore PT names that it does not recognize.
 302
 303        Parent processes MUST set this environment variable when
 304        launching a server-side PT reverse proxy instance.
 305
 306        Example:
 307
 308          TOR_PT_SERVER_TRANSPORTS=obfs3,scramblesuit
 309
 310      "TOR_PT_SERVER_TRANSPORT_OPTIONS"
 311
 312        Specifies per-PT protocol configuration directives, as a
 313        semicolon-separated list of <key>:<value> pairs, where <key>
 314        is a PT name and <value> is a k=v string value with options
 315        that are to be passed to the transport.
 316
 317        Colons, semicolons, and backslashes MUST be
 318        escaped with a backslash.
 319
 320        If there are no arguments that need to be passed to any of
 321        PT transport protocols, "TOR_PT_SERVER_TRANSPORT_OPTIONS"
 322        MAY be omitted.
 323
 324        Example:
 325
 326          TOR_PT_SERVER_TRANSPORT_OPTIONS=scramblesuit:key=banana;automata:rule=110;automata:depth=3
 327
 328          Will pass to 'scramblesuit' the parameter 'key=banana' and to
 329          'automata' the arguments 'rule=110' and 'depth=3'.
 330
 331      "TOR_PT_SERVER_BINDADDR"
 332
 333        A comma separated list of <key>-<value> pairs, where <key> is
 334        a PT name and <value> is the <address>:<port> on which it
 335        should listen for incoming client connections.
 336
 337        The keys holding transport names MUST be in the same order as
 338        they appear in "TOR_PT_SERVER_TRANSPORTS".
 339
 340        The <address> MAY be a locally scoped address as long as port
 341        forwarding is done externally.
 342
 343        The <address>:<port> combination MUST be an IP address
 344        supported by `bind()`, and MUST NOT be a host name.
 345
 346        Applications MUST NOT set more than one <address>:<port> pair
 347        per PT name.
 348
 349        If there is no specific <address>:<port> combination to be
 350        configured for any transports, "TOR_PT_SERVER_BINDADDR" MAY
 351        be omitted.
 352
 353        Example:
 354
 355           TOR_PT_SERVER_BINDADDR=obfs3-198.51.100.1:1984,scramblesuit-127.0.0.1:4891
 356
 357      "TOR_PT_ORPORT"
 358
 359        Specifies the destination that the PT reverse proxy should forward
 360        traffic to after transforming it as appropriate, as an
 361        <address>:<port>.
 362
 363        Connections to the destination specified via "TOR_PT_ORPORT"
 364        MUST only contain application payload.  If the parent process
 365        requires the actual source IP address of client connections
 366        (or other metadata), it should set "TOR_PT_EXTENDED_SERVER_PORT"
 367        instead.
 368
 369        Example:
 370
 371          TOR_PT_ORPORT=127.0.0.1:9001
 372
 373      "TOR_PT_EXTENDED_SERVER_PORT"
 374
 375        Specifies the destination that the PT reverse proxy should
 376        forward traffic to, via the Extended ORPort protocol [EXTORPORT]
 377        as an <address>:<port>.
 378
 379        The Extended ORPort protocol allows the PT reverse proxy to
 380        communicate per-connection metadata such as the PT name and
 381        client IP address/port to the parent process.
 382
 383        If the parent process does not support the ExtORPort protocol,
 384        it MUST set "TOR_PT_EXTENDED_SERVER_PORT" to an empty string.
 385
 386        Example:
 387
 388          TOR_PT_EXTENDED_SERVER_PORT=127.0.0.1:4200
 389
 390      "TOR_PT_AUTH_COOKIE_FILE"
 391
 392        Specifies an absolute filesystem path to the Extended ORPort
 393        authentication cookie, required to communicate with the
 394        Extended ORPort specified via "TOR_PT_EXTENDED_SERVER_PORT".
 395
 396        If the parent process is not using the ExtORPort protocol for
 397        incoming traffic, "TOR_PT_AUTH_COOKIE_FILE" MUST be omitted.
 398
 399        Example:
 400
 401          TOR_PT_AUTH_COOKIE_FILE=/var/lib/tor/extended_orport_auth_cookie
 402
 403 3.3. Pluggable Transport To Parent Process Communication
 404
 405    All Pluggable Transport Proxies communicate to the parent process
 406    via writing NL-terminated lines to stdout.  The line metaformat is:
 407
 408      <Line> ::= <Keyword> <OptArgs> <NL>
 409      <Keyword> ::= <KeywordChar> | <Keyword> <KeywordChar>
 410      <KeywordChar> ::= <any US-ASCII alphanumeric, dash, and underscore>
 411      <OptArgs> ::= <Args>*
 412      <Args> ::= <SP> <ArgChar> | <Args> <ArgChar>
 413      <ArgChar> ::= <any US-ASCII character but NUL or NL>
 414      <SP> ::= <US-ASCII whitespace symbol (32)>
 415      <NL> ::= <US-ASCII newline (line feed) character (10)>
 416
 417    The parent process MUST ignore lines received from PT proxies with
 418    unknown keywords.
 419
 420 3.3.1. Common Messages
 421
 422    When a PT proxy first starts up, it must determine which version
 423    of the Pluggable Transports Specification to use to configure
 424    itself.
 425
 426    It does this via the "TOR_PT_MANAGED_TRANSPORT_VER" (3.2.1)
 427    environment variable which contains all of the versions supported
 428    by the application.
 429
 430    Upon determining the version to use, or lack thereof, the PT
 431    proxy responds with one of two messages.
 432
 433      VERSION-ERROR <ErrorMessage>
 434
 435        The "VERSION-ERROR" message is used to signal that there was
 436        no compatible Pluggable Transport Specification version
 437        present in the "TOR_PT_MANAGED_TRANSPORT_VER" list.
 438
 439        The <ErrorMessage> SHOULD be set to "no-version" for
 440        historical reasons but MAY be set to a useful error message
 441        instead.
 442
 443        PT proxies MUST terminate after outputting a "VERSION-ERROR"
 444        message.
 445
 446        Example:
 447
 448          VERSION-ERROR no-version
 449
 450      VERSION <ProtocolVersion>
 451
 452        The "VERSION" message is used to signal the Pluggable Transport
 453        Specification version (as in "TOR_PT_MANAGED_TRANSPORT_VER")
 454        that the PT proxy will use to configure its transports and
 455        communicate with the parent process.
 456
 457        The version for the environment values and reply messages
 458        specified by this document is "1".
 459
 460        PT proxies MUST either report an error and terminate, or output
 461        a "VERSION" message before moving on to client/server proxy
 462        initialization and configuration.
 463
 464        Example:
 465
 466          VERSION 1
 467
 468    After version negotiation has been completed the PT proxy must
 469    then validate that all of the required environment variables are
 470    provided, and that all of the configuration values supplied are
 471    well formed.
 472
 473    At any point, if there is an error encountered related to
 474    configuration supplied via the environment variables, it MAY
 475    respond with an error message and terminate.
 476
 477      ENV-ERROR <ErrorMessage>
 478
 479        The "ENV-ERROR" message is used to signal the PT proxy's
 480        failure to parse the configuration environment variables (3.2).
 481
 482        The <ErrorMessage> SHOULD consist of a useful error message
 483        that can be used to diagnose and correct the root cause of
 484        the failure.
 485
 486        PT proxies MUST terminate after outputting a "ENV-ERROR"
 487        message.
 488
 489        Example:
 490
 491          ENV-ERROR No TOR_PT_AUTH_COOKIE_FILE when TOR_PT_EXTENDED_SERVER_PORT set
 492
 493 3.3.2. Pluggable Transport Client Messages
 494
 495    After negotiating the Pluggable Transport Specification version,
 496    PT client proxies MUST first validate "TOR_PT_PROXY" (3.2.2) if
 497    it is set, before initializing any transports.
 498
 499    Assuming that an upstream proxy is provided, PT client proxies
 500    MUST respond with a message indicating that the proxy is valid,
 501    supported, and will be used OR a failure message.
 502
 503      PROXY DONE
 504
 505        The "PROXY DONE" message is used to signal the PT proxy's
 506        acceptance of the upstream proxy specified by "TOR_PT_PROXY".
 507
 508      PROXY-ERROR <ErrorMessage>
 509
 510        The "PROXY-ERROR" message is used to signal that the upstream
 511        proxy is malformed/unsupported or otherwise unusable.
 512
 513        PT proxies MUST terminate immediately after outputting a
 514        "PROXY-ERROR" message.
 515
 516        Example:
 517
 518          PROXY-ERROR SOCKS 4 upstream proxies unsupported.
 519
 520    After the upstream proxy (if any) is configured, PT clients then
 521    iterate over the requested transports in "TOR_PT_CLIENT_TRANSPORTS"
 522    and initialize the listeners.
 523
 524    For each transport initialized, the PT proxy reports the listener
 525    status back to the parent via messages to stdout.
 526
 527      CMETHOD <transport> <'socks4','socks5'> <address:port>
 528
 529        The "CMETHOD" message is used to signal that a requested
 530        PT transport has been launched, the protocol which the parent
 531        should use to make outgoing connections, and the IP address
 532        and port that the PT transport's forward proxy is listening on.
 533
 534        Example:
 535
 536          CMETHOD trebuchet socks5 127.0.0.1:19999
 537
 538      CMETHOD-ERROR <transport> <ErrorMessage>
 539
 540        The "CMETHOD-ERROR" message is used to signal that
 541        requested PT transport was unable to be launched.
 542
 543        Example:
 544
 545          CMETHOD-ERROR trebuchet no rocks available
 546
 547    Once all PT transports have been initialized (or have failed), the
 548    PT proxy MUST send a final message indicating that it has finished
 549    initializing.
 550
 551      CMETHODS DONE
 552
 553        The "CMETHODS DONE" message signals that the PT proxy has
 554        finished initializing all of the transports that it is capable
 555        of handling.
 556
 557    Upon sending the "CMETHODS DONE" message, the PT proxy
 558    initialization is complete.
 559
 560    Notes:
 561
 562     - Unknown transports in "TOR_PT_CLIENT_TRANSPORTS" are ignored
 563       entirely, and MUST NOT result in a "CMETHOD-ERROR" message.
 564       Thus it is entirely possible for a given PT proxy to
 565       immediately output "CMETHODS DONE".
 566
 567     - Parent processes MUST handle "CMETHOD"/"CMETHOD-ERROR"
 568       messages in any order, regardless of ordering in
 569       "TOR_PT_CLIENT_TRANSPORTS".
 570
 571 3.3.3. Pluggable Transport Server Messages
 572
 573    PT server reverse proxies iterate over the requested transports
 574    in "TOR_PT_CLIENT_TRANSPORTS" and initialize the listeners.
 575
 576    For each transport initialized, the PT proxy reports the listener
 577    status back to the parent via messages to stdout.
 578
 579      SMETHOD <transport> <address:port> [options]
 580
 581        The "SMETHOD" message is used to signal that a requested
 582        PT transport has been launched, the protocol which will be
 583        used to handle incoming connections, and the IP address and
 584        port that clients should use to reach the reverse-proxy.
 585
 586        If there is a specific <address:port> provided for a given
 587        PT transport via "TOR_PT_SERVER_BINDADDR", the transport
 588        MUST be initialized using that as the server address.
 589
 590        The OPTIONAL 'options' field is used to pass additional
 591        per-transport information back to the parent process.
 592
 593        The currently recognized 'options' are:
 594
 595          ARGS:[<Key>=<Value>,]+[<Key>=<Value>]
 596
 597            The "ARGS" option is used to pass additional key/value
 598            formatted information that clients will require to use
 599            the reverse proxy.
 600
 601            Equal signs and commas MUST be escaped with a backslash.
 602
 603            Tor: The ARGS are included in the transport line of the
 604            Bridge's extra-info document.
 605
 606        Examples:
 607
 608          SMETHOD trebuchet 198.51.100.1:19999
 609          SMETHOD rot_by_N 198.51.100.1:2323 ARGS:N=13
 610
 611      SMETHOD-ERROR <transport> <ErrorMessage>
 612
 613        The "SMETHOD-ERROR" message is used to signal that
 614        requested PT transport reverse proxy was unable to be
 615        launched.
 616
 617        Example:
 618
 619          SMETHOD-ERROR trebuchet no cows available
 620
 621    Once all PT transports have been initialized (or have failed), the
 622    PT proxy MUST send a final message indicating that it has finished
 623    initializing.
 624
 625      SMETHODS DONE
 626
 627        The "SMETHODS DONE" message signals that the PT proxy has
 628        finished initializing all of the transports that it is capable
 629        of handling.
 630
 631    Upon sending the "SMETHODS DONE" message, the PT proxy
 632    initialization is complete.
 633
 634 3.3.4. Pluggable Transport Log Message
 635
 636    This message is for a client or server PT to be able to signal back to the
 637    parent process via stdout or stderr any log messages.
 638
 639    A log message can be any kind of messages (human readable) that the PT
 640    sends back so the parent process can gather information about what is going
 641    on in the child process. It is not intended for the parent process to parse
 642    and act accordingly but rather a message used for plain logging.
 643
 644    For example, the tor daemon logs those messages at the Severity level and
 645    sends them onto the control port using the PT_LOG (see control-spec.txt)
 646    event so any third party can pick them up for debugging.
 647
 648    The format of the message:
 649
 650       LOG SEVERITY=Severity MESSAGE=Message
 651
 652    The SEVERITY value indicate at which logging level the message applies.
 653    The accepted values for <Severity> are: error, warning, notice, info, debug
 654
 655    The MESSAGE value is a human readable string formatted by the PT. The
 656    <Message> contains the log message which can be a String or CString (see
 657    section 2 in control-spec.txt).
 658
 659    Example:
 660
 661       LOG SEVERITY=debug MESSAGE="Connected to bridge A"
 662
 663 3.3.5. Pluggable Transport Status Message
 664
 665    This message is for a client or server PT to be able to signal back to the
 666    parent process via stdout or stderr any status messages.
 667
 668    The format of the message:
 669
 670       STATUS TYPE=Type [<K_1>=<V_1> [<K_2>=<V_2> ...]]
 671
 672    The TYPE value indicates the status message type. Each Type has its own set
 673    of associated <K_n>=<V_n> values. Type can be a String or CString.
 674
 675    Following the TYPE specification are zero or more key=value pairs separated
 676    by spaces. Each TYPE has its own set of known keys. Each <V_n> can be a
 677    String or CString. To avoid confusion with the TYPE=Type specification, no
 678    <K_n> may be "TYPE". TYPE and the different K_n values may appear in any
 679    order.
 680
 681    The parent process should ignore STATUS messages that have a TYPE it does not
 682    understand. The parent process should ignore STATUS messages that do not have
 683    a TYPE set, or that have two or more TYPE=Type specifications.
 684
 685    Known TYPEs and the keys that are understood for them:
 686
 687       TYPE=version
 688       Required keys: IMPLEMENTATION, VERSION
 689
 690         The VERSION type reports the name of the PT implementation and its
 691         version number. One of the uses of this message is to enable contacting
 692         bridge operators that are running an out-of-date pluggable transport
 693         implementation.
 694
 695         IMPLEMENTATION is the name of the software package implementing the
 696         pluggable transport (because different implementations may have different
 697         version numbering schemes).
 698
 699         VERSION is the version number of the software package implementing the
 700         pluggable transport.
 701
 702         A single STATUS message of the VERSION type may be sent any time before
 703         "CMETHODS DONE" or "SMETHODS DONE". If sent after that, the parent
 704         process should ignore the message. If a VERSION message is sent more
 705         than once, only the first one counts.
 706
 707         Examples:
 708           STATUS TYPE=version VERSION=0.0.13 IMPLEMENTATION=obfs4proxy
 709           STATUS IMPLEMENTATION=snowflake-client VERSION=2.1.0 TYPE=version
 710
 711 3.4. Pluggable Transport Shutdown
 712
 713    The recommended way for Pluggable Transport using applications and
 714    Pluggable Transports to handle graceful shutdown is as follows.
 715
 716      - (Parent) Set "TOR_PT_EXIT_ON_STDIN_CLOSE" (3.2.1) when
 717        launching the PT proxy, to indicate that stdin will be used
 718        for graceful shutdown notification.
 719
 720      - (Parent) When the time comes to terminate the PT proxy:
 721
 722        1. Close the PT proxy's stdin.
 723        2. Wait for a "reasonable" amount of time for the PT to exit.
 724        3. Attempt to use OS specific mechanisms to cause graceful
 725           PT shutdown (eg: 'SIGTERM')
 726        4. Use OS specific mechanisms to force terminate the PT
 727           (eg: 'SIGKILL', 'ProccessTerminate()').
 728
 729      - PT proxies SHOULD monitor stdin, and exit gracefully when
 730        it is closed, if the parent supports that behavior.
 731
 732      - PT proxies SHOULD handle OS specific mechanisms to gracefully
 733        terminate (eg: Install a signal handler on 'SIGTERM' that
 734        causes cleanup and a graceful shutdown if able).
 735
 736      - PT proxies SHOULD attempt to detect when the parent has
 737        terminated (eg: via detecting that its parent process ID has
 738        changed on U*IX systems), and gracefully terminate.
 739
 740 3.5. Pluggable Transport Client Per-Connection Arguments
 741
 742    Certain PT transport protocols require that the client provides
 743    per-connection arguments when making outgoing connections.  On
 744    the server side, this is handled by the "ARGS" optional argument
 745    as part of the "SMETHOD" message.
 746
 747    On the client side, arguments are passed via the authentication
 748    fields that are part of the SOCKS protocol.
 749
 750    First the "<Key>=<Value>" formatted arguments MUST be escaped,
 751    such that all backslash, equal sign, and semicolon characters
 752    are escaped with a backslash.
 753
 754    Second, all of the escaped are concatenated together.
 755
 756      Example:
 757
 758        shared-secret=rahasia;secrets-file=/tmp/blob
 759
 760    Lastly the arguments are transmitted when making the outgoing
 761    connection using the authentication mechanism specific to the
 762    SOCKS protocol version.
 763
 764     - In the case of SOCKS 4, the concatenated argument list is
 765       transmitted in the "USERID" field of the "CONNECT" request.
 766
 767     - In the case of SOCKS 5, the parent process must negotiate
 768       "Username/Password" authentication [RFC1929], and transmit
 769       the arguments encoded in the "UNAME" and "PASSWD" fields.
 770
 771       If the encoded argument list is less than 255 bytes in
 772       length, the "PLEN" field must be set to "1" and the "PASSWD"
 773       field must contain a single NUL character.
 774
 775 4. Anonymity Considerations
 776
 777    When designing and implementing a Pluggable Transport, care
 778    should be taken to preserve the privacy of clients and to avoid
 779    leaking personally identifying information.
 780
 781    Examples of client related considerations are:
 782
 783      - Not logging client IP addresses to disk.
 784
 785      - Not leaking DNS addresses except when necessary.
 786
 787      - Ensuring that "TOR_PT_PROXY"'s "fail closed" behavior is
 788        implemented correctly.
 789
 790    Additionally, certain obfuscation mechanisms rely on information
 791    such as the server IP address/port being confidential, so clients
 792    also need to take care to preserve server side information
 793    confidential when applicable.
 794
 795 5. References
 796
 797    [RFC2119]     Bradner, S., "Key words for use in RFCs to Indicate
 798                  Requirement Levels", BCP 14, RFC 2119, March 1997.
 799
 800    [RFC1928]     Leech, M., Ganis, M., Lee, Y., Kuris, R.,
 801                  Koblas, D., Jones, L., "SOCKS Protocol Version 5",
 802                  RFC 1928, March 1996.
 803
 804    [EXTORPORT]   Kadianakis, G., Mathewson, N., "Extended ORPort and
 805                  TransportControlPort", Tor Proposal 196, March 2012.
 806
 807    [RFC3986]     Berners-Lee, T., Fielding, R., Masinter, L., "Uniform
 808                  Resource Identifier (URI): Generic Syntax", RFC 3986,
 809                  January 2005.
 810
 811    [RFC1929]     Leech, M., "Username/Password Authentication for
 812                  SOCKS V5", RFC 1929, March 1996.
 813
 814 6. Acknowledgments
 815
 816    This specification draws heavily from prior versions done by Jacob
 817    Appelbaum, Nick Mathewson, and George Kadianakis.
 818
 819 Appendix A. Example Client Pluggable Transport Session
 820
 821    Environment variables:
 822
 823      TOR_PT_MANAGED_TRANSPORT_VER=1
 824      TOR_PT_STATE_LOCATION=/var/lib/tor/pt_state/
 825      TOR_PT_EXIT_ON_STDIN_CLOSE=1
 826      TOR_PT_PROXY=socks5://127.0.0.1:8001
 827      TOR_PT_CLIENT_TRANSPORTS=obfs3,obfs4
 828
 829    Messages the PT Proxy writes to stdin:
 830
 831      VERSION 1
 832      PROXY DONE
 833      CMETHOD obfs3 socks5 127.0.0.1:32525
 834      CMETHOD obfs4 socks5 127.0.0.1:37347
 835      CMETHODS DONE
 836
 837 Appendix B. Example Server Pluggable Transport Session
 838
 839    Environment variables:
 840
 841      TOR_PT_MANAGED_TRANSPORT_VER=1
 842      TOR_PT_STATE_LOCATION=/var/lib/tor/pt_state
 843      TOR_PT_EXIT_ON_STDIN_CLOSE=1
 844      TOR_PT_SERVER_TRANSPORTS=obfs3,obfs4
 845      TOR_PT_SERVER_BINDADDR=obfs3-198.51.100.1:1984
 846
 847    Messages the PT Proxy writes to stdin:
 848
 849      VERSION 1
 850      SMETHOD obfs3 198.51.100.1:1984
 851      SMETHOD obfs4 198.51.100.1:43734 ARGS:cert=HszPy3vWfjsESCEOo9ZBkRv6zQ/1mGHzc8arF0y2SpwFr3WhsMu8rK0zyaoyERfbz3ddFw,iat-mode=0
 852      SMETHODS DONE