Skip to content

Commit dc258a2

Browse files
xiaokangwangxiaokangwang
committed
add tls mirror EN document
1 parent 4205a98 commit dc258a2

File tree

1 file changed

+191
-0
lines changed

1 file changed

+191
-0
lines changed

‎docs/en_US/v5/config/stream/tlsmirror.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# TLSMirror
2+
3+
::: danger
4+
This protocol is currently unreleased and is currently in developer preview phase. Please only use it with fully understanding of its risk.
5+
:::
6+
7+
TLSMirror is a looks like TLS protocol that designed to look like a port forwarder or SNI proxy while covertly transport payload traffic mixed with untouched carrier traffic. (unreleased)
8+
9+
10+
## TLSMirror Setting
11+
12+
* Name: `tlsmirror`
13+
* Type: Transport Protocol
14+
* ID: `stream.tlsmirror`
15+
16+
17+
> `primaryKey` : string
18+
19+
Primary key is a 32 bytes, base64 encoded key used for transform of payload traffic.
20+
Although AES-GCM encryption is used to transform the traffic, unless otherwise noted,
21+
the traffic is not securely encrypted and the payload protocol must complete its own
22+
encryption to protect traffic confidentiality.
23+
24+
This value must be same for both inbound and outbound.
25+
26+
You can generate this value with the following command:
27+
`cat /dev/urandom|head -c 32|base64`
28+
29+
30+
> `forwardTag` : string
31+
32+
The outbound tag for the traffic to the [Forwarded TLS Service](#forwarded-tls-service) for an inbound and to the covert server for outbound.
33+
34+
This is typically point to a `freedom` or direct outbound.
35+
36+
> `forwardPort` : number
37+
38+
::: tip
39+
This value is only used in inbound.
40+
:::
41+
42+
The port of the [Forwarded TLS Service](#forwarded-tls-service).
43+
44+
> `forwardAddress` : string
45+
::: tip
46+
This value is only used in inbound.
47+
:::
48+
49+
The network host address of the [Forwarded TLS Service](#forwarded-tls-service).
50+
51+
> `explicitNonceCiphersuites` : [ number ]
52+
53+
A list of cipher suites identifiers that uses an explicit nonce in its encrypted application data.
54+
55+
This value should be encoded in base 10 numbers, notwithstanding its typical notation of 2 hex encoded octets.
56+
57+
This value must be same for both inbound and outbound.
58+
59+
::: danger
60+
This `explicitNonceCiphersuites` value must be correctly configured or the traffic will either break down or become identifiable.
61+
:::
62+
63+
> `transportLayerPadding`: [TransportLayerPadding](#transport-layer-padding-setting)
64+
65+
The transport layer padding setting. This feature is currently not fully implemented, unset this field if forward compatibility is not required.
66+
67+
> `deferInstanceDerivedWriteTime`: [Time Spec](#time-spec)
68+
::: tip
69+
This value is typically only useful for inbound.
70+
:::
71+
72+
A randomized time to wait before writing data back, if response if generate by v2ray instance.
73+
74+
This is used to break timing attack that measure the time for each round trip to discover pattern, as instance generated reply is faster than proxied traffic.
75+
76+
77+
> `carrierConnectionTag`: string
78+
::: tip
79+
This value is only used in outbound.
80+
:::
81+
82+
The outbound tag to receive carrier connection on. The payload traffic will be then be overladed on this connection.
83+
84+
Please only route traffic that the [Forwarded TLS Service](#forwarded-tls-service) is willing to process to this outbound.
85+
86+
Be aware that presently this outbound port does not exist until the first client connection to server was made.
87+
88+
> `embeddedTrafficGenerator`: [Traffic Generator Setting](#traffic-generator-setting)
89+
90+
The embedded traffic generator to produce tls traffic on demand. This setting is required if there is no external traffic being routed to `carrierConnectionTag` outbound.
91+
92+
An embedded traffic generator is currently recommended for most setup.
93+
94+
## Traffic Generator Setting
95+
96+
> `securitySettings`: special
97+
98+
Traffic generator will use the security settings of TLSMirror transport if this value is unset.
99+
100+
Please unset this field and configure Traffic Generator's TLS setting with TLSMirror transport's security settings, as this is an engineering option.
101+
102+
> `steps`: [ [Traffic Generator Step Specification](#traffic-generator-step-specification) ]
103+
104+
The steps to take in order to generate the traffic.
105+
106+
The traffic generate walk through these steps starting with step 0 over a markov-like process.
107+
108+
## Traffic Generator Step Specification
109+
110+
> `host`: string
111+
112+
The hostname to be sent in the http host header.
113+
114+
> `path`: string
115+
116+
The path of the http request generated, like `/robots.txt`.
117+
118+
> `method`: string
119+
120+
the method name of the http request generated.
121+
122+
> `headers`: [ [Header](#header) ]
123+
124+
The headers to be sent in HTTP request.
125+
126+
> `nextStep`: [Next Step Specification](#next-step-specification)
127+
128+
The probabilistic jump table executed after this step.
129+
130+
> `connectionReady`: bool
131+
132+
If set to true, once this step is completed, the payload traffic can start being relayed on this carrier connection.
133+
134+
> `waitTime`: [Time Spec](#time-spec)
135+
The time to wait before sending next request.
136+
137+
The traffic generator will always finish the current request unless otherwise specified.
138+
139+
> `h2DoNotWaitForDownloadFinish`: bool
140+
If set to true and http2 connection was negotiated, do not wait for response to be fully downloaded before moving to next step once wait time has passed.
141+
142+
## Next Step Specification
143+
144+
> `weight`: number
145+
146+
An integer weight of possibility of this jump happening.
147+
148+
> `gotoLocation`: number
149+
150+
The location to jump to in the step specification array.
151+
152+
## Forwarded TLS Service
153+
154+
Forwarded TLS Service can be any TLS endpoints, so long as it serves either TLS1.2 or TLS1.3 traffic. When used together with embedded traffic generator, HTTPS sites are recommended.
155+
156+
Unlike other similar protocols, TLSMirror can process TLS1.2 correctly,
157+
including AEAD cipher suites with explicit nonces(so long as it is an increasing int64 counter,
158+
and transport is correctly configured of the identifiers of these cipher suites).
159+
160+
## Time Spec
161+
162+
::: tip
163+
One second is 1000000000 nano seconds.
164+
:::
165+
166+
The final wait time is
167+
168+
`baseNanoseconds` + `uniformRandomMultiplierNanoseconds` * `uniformRandom`,
169+
where `uniformRandom` is a variable `∈ [0,1)` and subject to uniform random distribution.
170+
171+
> `baseNanoseconds`: number
172+
173+
> `uniformRandomMultiplierNanoseconds`: number
174+
175+
## Header
176+
177+
> 'key' : string
178+
179+
The HTTP header key.
180+
181+
> 'value' : string
182+
183+
The HTTP header value.
184+
185+
## Transport Layer Padding Setting
186+
187+
> `enabled`: bool
188+
189+
Whether transport layer padding is enabled.
190+
191+
This value must be same for both inbound and outbound.

0 commit comments

Comments
 (0)