diff --git a/pt-spec.txt b/pt-spec.txt index 05421c1da5abd3c3471cdeb2a0326dec550c9562..63e22cf15de99ec0bfc3f13cdebc9406be0460c7 100644 --- a/pt-spec.txt +++ b/pt-spec.txt @@ -668,22 +668,47 @@ Table of Contents The format of the message: - STATUS TRANSPORT=Transport = [=, ...] + STATUS TYPE=Type [= [= ...]] - The TRANSPORT value indicates a hint on what the PT is such has the name or - the protocol used for instance. As an example, obfs4proxy would use - "obfs4". Thus, the Transport value can be anything the PT itself defines - and it can be a String or CString (see section 2 in control-spec.txt). + The TYPE value indicates the status message type. Each Type has its own set + of associated = values. Type can be a String or CString. The + following are the known types: - The = values are specific to the PT and there has to be at least - one. They are messages that reflects the status that the PT wants to - report. can be a String or CString. + Following the TYPE specification are zero or more key=value pairs separated + by spaces. Each TYPE has its own set of known keys. Each can be a + String or CString. To avoid confusion with the TYPE=Type specification, no + may be "TYPE". TYPE and the different K_n values may appear in any + order. - Examples (fictional): + The parent process should ignore STATUS messages that have a TYPE it does not + understand. The parent process should ignore STATUS messages that do not have + a TYPE set, or that have two or more TYPE=Type specifications. - STATUS TRANSPORT=obfs4 ADDRESS=198.51.100.123:1234 CONNECT=Success - STATUS TRANSPORT=obfs4 ADDRESS=198.51.100.222:2222 CONNECT=Failed FINGERPRINT= ERRSTR="Connection refused" - STATUS TRANSPORT=trebuchet ADDRESS=198.51.100.15:443 PERCENT=42 + Known TYPEs and the keys that are understood for them: + + TYPE=version + Required keys: IMPLEMENTATION, VERSION + + The VERSION type reports the name of the PT implementation and its + version number. One of the uses of this message is to enable contacting + bridge operators that are running an out-of-date pluggable transport + implementation. + + IMPLEMENTATION is the name of the software package implementing the + pluggable transport (because different implementations may have different + version numbering schemes). + + VERSION is the version number of the software package implementing the + pluggable transport. + + A single STATUS message of the VERSION type may be sent any time before + "CMETHODS DONE" or "SMETHODS DONE". If sent after that, the parent + process should ignore the message. If a VERSION message is sent more + than once, only the first one counts. + + Examples: + STATUS TYPE=version VERSION=0.0.13 IMPLEMENTATION=obfs4proxy + STATUS IMPLEMENTATION=snowflake-client VERSION=2.1.0 TYPE=version 3.4. Pluggable Transport Shutdown