Proposal: Config for split/disorder/tlsfrag

[fortuna]

We need to define a config for:

• TCP/stream split, which splits the writes to streams
• disorder, which, on a split, sets TTL=1 for the prefix and then resets is. This causes packets to be seen out of order
• TLS Record fragmentation
• fake, which injects fake data into the TCP stream to confuse DPI
• oob, which injects a OOB byte in the middle of the TCP stream.

(Kudos to byeDPI contributors for some of those strategies)

The urlconfig package has definitions for some of them:

split:[COUNT1]*[LENGTH1],[COUNT2]*[LENGTH2],...

disorder:[PACKET_NUMBER]

tlsfrag:[LENGTH]

We need:

• A structured version of that for the Outline Client Config
• Probably combine disorder and split somehow
• Add splitting and TLS record fragmentation at a hostname, string or SNI.

We could have a little language like:

tcp:
  $type: split
  dialer:
     # ...Dialer definition...
  splits:
    - {$type: multi, split: {$type: position, skip: 10}, times: 20}
    - {$type: position, skip: 100, disorder: true}   # TTL will be reset after the prefix write
    - {$type: hostname, offset: 3}  # Splits at the dialed hostname, in the given offset. E,g, [`exa`, `mple.com`].
    - {$type: string, string: "example.com", offset: 4, disorder: true}
    - {$type: position, skip: 20, oob: 0x45, disorder: true}

I'm not sure yet if TLS Record Fragmentation should have a different type, but use the same format, or be folded into it.

Please review and provider feedback.

Updates:

• Replaced position with skip, to clarify we are skipping that many bytes, and not confuse with the position from the beginning.

[fortuna]

Perhaps we can have a lower level language, with skips and splits:

tcp:
  $type: split
  dialer:
     # ...Dialer definition...
  splits:
    - {$type: skip, bytes: 10}
    - {$type: split}
    - {$type: repeat, times: 20, sequence: [{$type: skip, bytes: 10}, {$type: split}]}
    - {$type: skip, bytes: 100}
    - {$type: split, disorder: true}  # How do apply the TTL=1 to the prefix?
    - {$type: find-hostname}
    - {$type: skip, bytes: 3}
    - {$type: split}
    - {$type: find-string, string: example.com}
    - {$type: skip, bytes: 4}
    - {$type: split, oob: 0x45, disorder: true}

[murka]

1. Explicit Specification of the Obfuscation Chain as a YAML Sequence

Instead of using one long string or multiple separate fields, a structured list of transport steps can be introduced. For example:

transport:
  $type: tcp
  chain:
    - type: disorder
      packet: 1           # Apply disorder to the first packet
    - type: split
      position: 7         # Then split the stream at the 7th byte
    - type: tlsfrag
      length: 1           # Then fragment the TLS ClientHello into 1 byte + the rest
    - type: fake
      bytes: 7            # Replace the first 7 bytes with fake data
    - type: oob
      position: 3         # Insert an OOB byte after the 3rd byte
    - type: shadowsocks
      endpoint: myserver:443
      cipher: chacha20-ietf-poly1305
      secret: "PASSWORD"

Here, the chain field contains an ordered list of applied transport "wrappers." Each list item is a separate stage, specifying the type and its parameters. The order, from top to bottom, reflects the sequence in which the techniques are applied: first disorder, then split, and so on, ending with the base transport, shadowsocks.

This format intuitively shows both the sequence and the parameters. It is easily extensible to add a new technique, simply add another list item.

---

2. Hierarchical Nesting of Transports (in the Style of the Existing $type)

Alternatively, we can follow the Outline SDK's existing principle of nested objects. That is, use existing keys like endpoint or dialer to "wrap" one transport with another. For example:

tcp:
  $type: disorder
  packet: 0
  dialer:
    $type: split
    position: 7
    dialer:
      $type: tlsfrag
      length: 1
      dialer:
        $type: shadowsocks
        endpoint: myserver:443
        cipher: aes-256-gcm
        secret: "PASSWORD"

Here, the Shadowsocks driver is at the innermost layer, with tlsfrag, split, and disorder wrapped around it in sequence. This YAML reflects the connection structure each outer $type wraps an inner one. This matches how the Outline SDK actually builds connections through dialer calls.

[fortuna]

Chain format compatibility

The primary format we use is hierarchical, but that doesn't prevent the use of a chain format. We can define that as a subtype in the hierarchical format. But the items are no longer dialers. They would be connection wrappers instead, which will need their own factories. A connection wrapper goes from a connection (perhaps + dialed address) to another connection, as opposed to a dialer that goes from address to connection.

For example::

tcp:
    $type: wrapped
    dialer: 
        $type: shadowsocks
        endpoint: myserver:443
        cipher: aes-256-gcm
        secret: "PASSWORD"
    wrappers:
        - $type: disorder
          packet: 1           # Apply disorder to the first packet
        - $type: split
          position: 7         # Then split the stream at the 7th byte
        - $type: tlsfrag
          length: 1           # Then fragment the TLS ClientHello into 1 byte + the rest
        - $type: fake
          bytes: 7            # Replace the first 7 bytes with fake data
        - $type: oob
          position: 3   

This can remove some duplication in the code. For example, TLS could be implemented as a connection wrapper:

tcp:
    $type: wrapped
    dialer: {$type: direct}
    wrappers:
      - $type: tls

Shadowsocks transport could be a wrapper too:

tcp:
    $type: wrapped
    dialer:
        $type: shadowsocks-dial
        endpoint: ss.example.com
    wrappers:
        - $type: shadowsocks-transport
          cipher: aes-256-gcm
          secret: "PASSWORD"

[fortuna]

One nice thing about connection wrappers is that they can apply to both dialers and endpoints.

[fortuna]

On Wrappers

We need to be careful with wrappers. They hide the original implementation and can have harmful implications.

One of the most critical issues is hiding the io.ReaderFrom or io.WriterTo implementation, because they are not part of the StreamConn interface. We depend on those functions to remove a layer of buffering. For example, we can have something like ssDecoder.ReadFrom(tcpConn), and the reads can go straight to the shadowsocks buffer.

Without those functions we need a loop to read from tcpConn into an intermediary buffer and then write to ssDecoder in the example above. That results in potential chopped writes, which can add overhead in record-based protocols like Shadowsocks, TLS or Websockets. It also results in extra memory consumption and allocations, which can strain the device resources and garbage collector.

The other critical point is that Disorder depends on being able to set the TTL. So we need a "Set TTL" API to be preserved and exposed across wrapping if we were to wrap dialers. I believe it's a better approach to have a single dialer with a list of commands instead.

We should minimize wrapping if we can, and make sure we expose those interfaces when wrapping. Our transport.WrapConn illustrates how we can preserve the io functions, though not other interfaces.