Opened 5 years ago

Last modified 17 months ago

#12614 new defect

Design a good way to pass transport options to child PTs

Reported by: infinity0 Owned by: RushingWookie
Priority: Medium Milestone:
Component: Obfuscation/Pluggable transport Version:
Severity: Normal Keywords: fog
Cc: Actual Points:
Parent ID: Points:
Reviewer: Sponsor:


Client transports get their k=v options from the SOCKS parameters, which is given in the Bridge line. Server transports get their k=v options from ServerTransportOptions.

We need to define ways for fog to pass these options down to the relevant child.

For example, one basic syntax would be, if fog receives an option of the form "fog-child-n-k=v", it passes "k=v" as the option (either SOCKS or ServerTransportOptions) down to the nth child PT in the chain. (This may not be the best idea; the consequences should be examine before we commit to this.)

This must be documented as a public API of fog.

Child Tickets

Change History (7)

comment:1 Changed 5 years ago by RushingWookie

Ok, heres a couple of syntaxes

This syntax attaches the name of each pt to the kv pairs individually.

  1. ptname1-key1=val1 ptname1-key2=val2 ptname2-key1=val1 ptname2-key2=val2

It looks alright, but I dont like to have to repeat the pt name before each key val. It does make each key-val pair completely separate so if tor needs to store them internally in a hash then this works. But I took a look at how tor parses the bridge lines and I think it uses a smartlist (Please correct me if I've got this wrong)

In this case, the syntax is

  1. pt=ptname1 key1=val1 key2=val2; pt=ptname2 key1=val1 key2=val2 etc

When transmitted in the SOCKS handshake, the semi colon separating the groups of options would be escaped so the SOCKS line would be pt1=trebuchet;key1=val1;key2=val2\;pt2=obfs3;key1=val1;key2=val2

This looks fairly clean and is easy to parse. If tor is using a hash internally to store key vals then this won't work.

This syntax is

  1. fog-child=n key1=val1 key2=val2; fog-child=n key1=val1 key2=val2;

This one doesn't need to have the pt named and this is an advantage and a disadvantage. For key vals that can be given to multiple transports and depend on their position in the chain, it works well. But it may be confusing if the chain is editted and the key vals are not updated accordingly.

comment:2 Changed 5 years ago by infinity0

With regards to whether the ordering of keywords is significant, I think it's more important to look at what the SOCKS protocol spec says, rather than what tor implements itself. I would guess it's unordered.

If you pick a new separator, you should use it as an internal separator rather than an external separator - since typical SOCKS protocol parsers won't recognise your custom separator. For example, fog-child=a&key1=val1&key2=val;fog-child=b&key1=val1&key2=val rather than your (2).

Specifying by the name instead of the index in the chain is more usable and readable, but watch out for things like b64|obfs3|b64.

comment:3 Changed 5 years ago by RushingWookie

The ptspec says that all client options are passed through the SOCKS username and password fields. So I don't think the SOCKS protocol will reorder it after tor inserts the field.

Ok, the & separator works nicely.

As for the pt chains with duplicates in them, we could have an additional -n attached to the name to specify which duplicate. so for b64|obfs3|b64, each ptname would be pt=b64-1&pt=64-2 etc. It is special casing the duplicates but we need some way of separating them.

comment:4 Changed 5 years ago by RushingWookie

Another thing we need to think about is that the ServerTransportOptions has to contain all the parameters for each chain instead of just the single chain that is getting the parameters like the fog client does. So having named parameters is probably too restrictive as it forces the server to have the same parameters for the same transport in any chain.

This also means we need another separator for the ServerTransportOptions to distinguish between chains. This actually solves the problem with the named chains as different parameters can be specified per chain now. But it still doesn't prevent the problem of having duplicates in a chain that need different parameters.

Heres an example server syntax
chain=pt1|pt2 pt1=trebuchet;key1=val1;key2=val2&pt2=obfs3;key1=val1;key2=val2, chain=pt2|pt1 pt1=trebuchet;key1=val1;key2=val2&pt2=obfs3;key1=val1;key2=val2
It uses commas to separate chains and &s to separate pts.

Last edited 5 years ago by RushingWookie (previous) (diff)

comment:5 Changed 5 years ago by infinity0

Instead of using ServerTransportOptions in torrc, we could have chain-specific ServerTransportOptions in fogrc instead. I believe fog-server already has some code that suggests this, e.g. the ServerTransportPlugin struct in config.go has an Options field.

Then, you can have the same options syntax in both the Bridge line in torrc (for the client) and the ServerTransportOptions line in fogrc (for the fog-server).

comment:6 Changed 5 years ago by RushingWookie

Thats a great idea. It'll make it much cleaner. Ok so we'll read the ServerTransportOptions from fogrc and parse them into the Options field in the ServerTransportOptions struct.

Now I'm not sure if the -n option like pt=b64-1&pt=64-2 etc works very well as pt names could have dashes and numbers in them. If we don't use a -n or some other duplicate specifier I think we should use the originally proposed syntax of "fog-child-n-k=v" as it works for everything. It is less readable than but the pt-name-kv options syntax but itll still work well.

comment:7 Changed 17 months ago by teor

Severity: Normal

Set all open tickets without a severity to "Normal"

Note: See TracTickets for help on using tickets.