Add opt-in printable TCP salt experiment for ss-local (#3063)

Add `ss-local --printable-salt` / `"printable_salt": true`, disabled by
default. For each outgoing TCP salt it picks a prefix length uniformly
from 6-12 bytes and samples those bytes as printable ASCII (0x20-0x7e)
immediately before key derivation. The salt stays 32 bytes with no
framing or markers, so the wire format is unchanged and any stock
server interoperates. Only chacha20-ietf-poly1305 and aes-256-gcm are
accepted; other ciphers fail at startup. UDP, server responses, and
AEAD-2022 are untouched.

Crypto unit tests cover length distribution, empty first writes, exact
framing overhead, salt-tail preservation, byte-at-a-time decryption,
tampering and replay rejection. CLI tests check local-only exposure and
cipher rejection via flag, config key and bad config type. interop.py
gains --printable-salt and --server-bin for independent stock servers.

docs/printable-salt.md records the design, entropy bound, fingerprint
caveats and route-experiment procedure; docs/encoding-experiments.md
and tests/experiments/ hold the Base85/lowpop85/TLS outer-transport
prototypes. docs/measurements/printable-salt-2026-09-23/ archives the
sanitized results of the aborted field trials.

Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Max Lv
2026-10-13 09:09:51 +08:00
committed by GitHub
co-authored by Claude
parent d52ddf2bce
commit 553cdc7945
36 changed files with 3389 additions and 1 deletions
+103
View File
@@ -0,0 +1,103 @@
#!/usr/bin/env python3
"""Summarize transport screening and captured first TCP payloads."""
import argparse
from collections import Counter, defaultdict
from datetime import datetime
import json
import hashlib
from pathlib import Path
import statistics
import sys
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from check_printable_pcap import initial_payloads # noqa: E402
from benchmark import exemptions # noqa: E402
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('directory')
args = parser.parse_args()
root = Path(args.directory)
protocol = json.loads((root / 'protocol.json').read_text())
events = [json.loads(line) for line in (root / 'events.jsonl').read_text().splitlines()]
phases = [(datetime.fromisoformat(e['utc'].replace('Z', '+00:00')).timestamp(), e)
for e in events if e['event'] == 'phase_start']
summary = dict(protocol=protocol, complete=any(e['event'] == 'complete' for e in events),
aborts=[e for e in events if e['event'] == 'aborted'],
completed_phases=sum(e['event'] == 'phase_complete' for e in events),
outcome_logging_limit='Runs before the durable-outcome fix can omit in-flight outcomes at abort.',
health_checks=sum(e['event'] in ('health', 'phase_start') for e in events),
health_failures=sum(e.get('healthy') is False for e in events), modes={})
for mode in protocol['modes']:
records = [e for e in events if e.get('mode') == mode and e['event'] == 'transfer']
small = [e['seconds'] * 1000 for e in records if e['size'] == 1024 and e['success']]
large = [e['mbps'] for e in records if e['size'] > 1024 and e['success']]
summary['modes'][mode] = dict(recorded_outcomes=len(records), success=sum(e['success'] for e in records),
errors=[e for e in records if not e['success']],
small_median_ms=statistics.median(small) if small else None,
small_p95_ms=sorted(small)[min(len(small) - 1, int(len(small) * .95))] if small else None,
large_median_mbps=statistics.median(large) if large else None)
expected_source = next((e.get('client_address') for e in events if e['event'] == 'start'), None)
for filename in ('client.pcap', 'remote-server.pcap'):
counts = defaultdict(Counter)
flows = list(initial_payloads(root / filename, protocol['ports']))
external = [f for f in flows if not f['source'].startswith('127.')]
source = expected_source if filename.startswith('remote-') else None
if source is None and external:
source = Counter(f['source'] for f in external).most_common(1)[0][0]
unexpected = [f for f in external if f['source'] != source]
replays = []
for probe in unexpected:
matches = [f for f in external if f['source'] == source and f['time'] < probe['time']
and f['port'] == probe['port'] and f['payload_hex'] == probe['payload_hex']
and f['payload_complete'] and probe['payload_complete']]
if matches:
original_phase = [event for stamp, event in phases if stamp <= matches[-1]['time']][-1]
replay_mode = original_phase['port_modes'][protocol['ports'].index(probe['port'])]
replays.append(dict(mode=replay_mode, phase=original_phase['phase'], port=probe['port'], delay_seconds=probe['time'] - matches[-1]['time'],
payload_bytes=len(bytes.fromhex(probe['payload_hex'])),
payload_sha256=hashlib.sha256(bytes.fromhex(probe['payload_hex'])).hexdigest()))
summary[filename + '/unsolicited'] = dict(connections=len(unexpected), exact_replays=replays)
for flow in flows:
if flow['source'] != source:
continue
previous = [event for stamp, event in phases if stamp <= flow['time']]
if not previous:
continue
phase = previous[-1]
mode = phase['port_modes'][protocol['ports'].index(flow['port'])]
values = counts[mode]
values['connections'] += 1
values['sequence_ok'] += flow['sequence_ok']
values['complete_first_payload'] += flow['payload_complete']
payload = bytes.fromhex(flow['payload_hex'])
rules = exemptions(payload)
rules['tls_header'] = len(payload) >= 3 and payload[0] in (22, 23) and payload[1] == 3 and payload[2] <= 9
if flow['payload_complete']:
values['historical_exemption'] += any(rules.values())
for rule, passed in rules.items():
values[rule] += passed
summary[filename] = {mode: dict(values) for mode, values in counts.items()}
stream_counts = defaultdict(Counter)
for flow in initial_payloads(root / filename, protocol['ports'], require_sequence=True):
if flow['source'] != source:
continue
previous = [event for stamp, event in phases if stamp <= flow['time']]
if not previous:
continue
mode = previous[-1]['port_modes'][protocol['ports'].index(flow['port'])]
payload = bytes.fromhex(flow['payload_hex'])
rules = exemptions(payload)
tls = len(payload) >= 3 and payload[0] in (22, 23) and payload[1] == 3 and payload[2] <= 9
stream_counts[mode]['connections'] += 1
stream_counts[mode]['complete_first_payload'] += flow['payload_complete']
if flow['payload_complete']:
stream_counts[mode]['historical_exemption'] += any(rules.values()) or tls
summary[filename + '/stream_start'] = {mode: dict(values) for mode, values in stream_counts.items()}
(root / 'summary.json').write_text(json.dumps(summary, indent=2) + '\n')
print(json.dumps(summary, indent=2))
if __name__ == '__main__':
main()
+80
View File
@@ -0,0 +1,80 @@
#!/usr/bin/env python3
"""Synthetic uniform-ciphertext screening; not a live censorship measurement."""
import argparse
from collections import Counter
import json
import math
import os
import statistics
import time
from transport import BLOCK, decode, encode
def exemptions(data):
printable = [0x20 <= value <= 0x7e for value in data]
popcount = sum(value.bit_count() for value in data) / len(data)
longest = run = 0
for value in printable:
run = run + 1 if value else 0
longest = max(run, longest)
return dict(popcount=popcount <= 3.4 or popcount >= 4.6,
prefix=len(data) >= 6 and all(printable[:6]),
half=sum(printable) > len(data) / 2, run=longest > 20)
def statistics_for(data):
counts = Counter(data)
total = len(data)
return dict(byte_entropy=-sum(n / total * math.log2(n / total) for n in counts.values()),
alphabet_size=len(counts), printable_fraction=sum(0x20 <= b <= 0x7e for b in data) / total,
ones_per_byte=sum(b.bit_count() for b in data) / total)
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('--output', required=True)
args = parser.parse_args()
payload = os.urandom(1024 * 1024)
results = []
for mode in ('raw', 'printable_variable', 'base85', 'lowpop85'):
def transform(data):
if mode == 'printable_variable':
import secrets
length = 6 + secrets.randbelow(7)
return bytes(32 + secrets.randbelow(95) for _ in range(length)) + data[length:]
return encode(mode, data)
timings = []
for _ in range(5):
start = time.perf_counter()
if mode == 'printable_variable':
wire = transform(payload)
else:
frames = [transform(payload[i:i + BLOCK]) for i in range(0, len(payload), BLOCK)]
wire = b''.join(frames)
if mode != 'raw':
recovered = b''.join(decode(mode, frame[:-1]) for frame in frames)
assert recovered == payload
timings.append(time.perf_counter() - start)
passes = Counter()
for _ in range(2000):
sample = transform(os.urandom(100))
rules = exemptions(sample)
passes.update({key: int(value) for key, value in rules.items()})
passes['any'] += any(rules.values())
results.append(dict(mode=mode, synthetic=True, source_bytes=len(payload), wire_bytes=len(wire),
overhead_fraction=len(wire) / len(payload) - 1,
codec_roundtrip_mib_s=1 / statistics.median(timings) if mode not in ('raw', 'printable_variable') else None,
historical_exemption_samples=2000, historical_exemption_passes=dict(passes),
**statistics_for(wire)))
with open(args.output, 'w') as output:
json.dump(results, output, indent=2)
output.write('\n')
for row in results:
print(row['mode'], 'overhead', round(row['overhead_fraction'] * 100, 2),
'entropy', round(row['byte_entropy'], 3), 'ones/byte', round(row['ones_per_byte'], 3),
'historical exemptions', row['historical_exemption_passes']['any'], '/ 2000')
if __name__ == '__main__':
main()
+71
View File
@@ -0,0 +1,71 @@
#!/usr/bin/env python3
"""Exercise each outer transport around independently built stock Shadowsocks."""
import argparse
import concurrent.futures
import json
from pathlib import Path
import subprocess
import sys
import tempfile
import threading
import time
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from interop import TCPHandler, TCPOrigin, free_port, peers, tcp_case # noqa: E402
from transport import MODES # noqa: E402
def certificate(directory):
cert, key = directory / 'certificate.pem', directory / 'key.pem'
subprocess.run(['openssl', 'req', '-x509', '-newkey', 'rsa:2048', '-nodes', '-keyout', str(key),
'-out', str(cert), '-days', '1', '-subj', '/CN=experiment.invalid',
'-addext', 'subjectAltName=DNS:experiment.invalid'], check=True,
stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
key.chmod(0o600)
return cert, key
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('--bin', required=True)
parser.add_argument('--output', required=True)
args = parser.parse_args()
binary = Path(args.bin).resolve()
results = []
with tempfile.TemporaryDirectory(prefix='ss-encoding-') as temp, TCPOrigin(('127.0.0.1', 0), TCPHandler) as origin:
cert, key = certificate(Path(temp))
threading.Thread(target=origin.serve_forever, daemon=True).start()
try:
for method in ('chacha20-ietf-poly1305', 'aes-256-gcm'):
for mode in MODES:
server, remote, bridge, local = [free_port() for _ in range(4)]
common = [sys.executable, str(Path(__file__).with_name('transport.py')), '--mode', mode]
commands = [
[str(binary / 'ss-server'), '-s', '127.0.0.1', '-p', str(server), '-m', method, '-k', 'local-encoding-test'],
common + ['--role', 'server', '--listen-port', str(remote), '--target-port', str(server),
'--certificate', str(cert), '--key', str(key)],
common + ['--role', 'client', '--listen-port', str(bridge), '--target-port', str(remote),
'--certificate', str(cert)],
[str(binary / 'ss-local'), '-s', '127.0.0.1', '-p', str(bridge), '-l', str(local), '-m', method, '-k', 'local-encoding-test'],
]
with peers(commands, [server, remote, bridge, local]):
with concurrent.futures.ThreadPoolExecutor(max_workers=4) as pool:
pending = [pool.submit(tcp_case, local, origin.server_address[1], size)
for size in (1, 16383, 65536, 1048576)]
for task in pending:
task.result(timeout=30)
start = time.monotonic()
tcp_case(local, origin.server_address[1], 10 * 1024 * 1024)
duration = time.monotonic() - start
result = dict(mode=mode, cipher=method, concurrent_transfers=4, success=True,
large_bytes=10 * 1024 * 1024, large_seconds=duration,
echo_mbps=10 * 1024 * 1024 * 8 / duration / 1e6)
results.append(result)
print(json.dumps(result), flush=True)
finally:
origin.shutdown()
Path(args.output).write_text(json.dumps(results, indent=2) + '\n')
if __name__ == '__main__':
main()
+166
View File
@@ -0,0 +1,166 @@
#!/usr/bin/env python3
"""Eight-minute, four-port Latin-square screening of experimental outer transports.
Run after the original salt crossover completes, on unused high ports. This is
compatibility/performance screening, not evidence of lasting censorship resistance.
"""
import argparse
import base64
import concurrent.futures
import json
import os
from pathlib import Path
import select
import shlex
import subprocess
import sys
import tempfile
import time
import threading
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from interop import free_port, peers # noqa: E402
from printable_salt_experiment import transfer # noqa: E402
from local_interop import certificate # noqa: E402
from transport import MODES # noqa: E402
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('--host', required=True)
parser.add_argument('--host-key-alias', required=True)
parser.add_argument('--address', required=True)
parser.add_argument('--stock-bin', required=True)
parser.add_argument('--output', required=True)
parser.add_argument('--interface', default='en0')
parser.add_argument('--ports', nargs=len(MODES), type=int, default=list(range(32200, 32200 + len(MODES))))
parser.add_argument('--phase-seconds', type=int, default=120)
parser.add_argument('--large-bytes', type=int, default=10 * 1024 * 1024)
args = parser.parse_args()
out = Path(args.output).resolve()
out.mkdir(mode=0o700, parents=True, exist_ok=True)
if (out / 'events.jsonl').exists():
parser.error('use a fresh output directory')
env = {key: value for key, value in os.environ.items() if not key.lower().endswith('_proxy')}
ssh = ['ssh', '-o', 'BatchMode=yes', '-o', 'StrictHostKeyChecking=yes', '-o',
'HostKeyAlias=' + args.host_key_alias, '-o', 'ConnectTimeout=8', '-o',
'ServerAliveInterval=5', '-o', 'ServerAliveCountMax=2', args.host]
directory = subprocess.check_output(ssh + ['mktemp -d /tmp/ss-encoding.XXXXXXXX'], env=env, text=True).strip()
root = Path(__file__).parent
remote = capture = None
log_lock = threading.Lock()
def emit(record):
record['utc'] = time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime())
with log_lock, (out / 'events.jsonl').open('a') as output:
output.write(json.dumps(record) + '\n')
def measured_transfer(meta, proxy, origin, size):
emit(dict(meta, event='attempt', size=size))
result = transfer(proxy, origin, size)
emit(dict(**meta, **result))
return result
def upload(name, content):
subprocess.run(ssh + ['umask 077; cat > ' + shlex.quote(directory + '/' + name)],
input=content, check=True, env=env)
def exchange(record):
remote.stdin.write(json.dumps(record) + '\n')
remote.stdin.flush()
assert select.select([remote.stdout], [], [], 12)[0], 'management health timeout'
line = remote.stdout.readline()
assert line, 'remote supervisor stopped'
return json.loads(line)
# Persist the schedule before observing outcomes.
(out / 'protocol.json').write_text(json.dumps(dict(modes=MODES, ports=args.ports,
phases=len(MODES), phase_seconds=args.phase_seconds, small_interval_seconds=5,
small_bytes=1024, large_per_phase=1, large_bytes=args.large_bytes,
rotation=f'mode i uses port (i + phase_index) modulo {len(MODES)}',
acceptance='screening only; all-success is compatibility, not censorship resistance'), indent=2) + '\n')
with tempfile.TemporaryDirectory(prefix='ss-encoding-cert-') as temporary:
cert, key = certificate(Path(temporary))
password = base64.b64encode(os.urandom(32)).decode()
try:
for name in ('transport.py', 'route_server.py'):
upload(name, (root / name).read_bytes())
upload('certificate.pem', cert.read_bytes())
upload('key.pem', key.read_bytes())
with (out / 'remote.log').open('w') as remote_log, (out / 'capture.log').open('w') as capture_log:
remote = subprocess.Popen(ssh + ['python3 -u ' + shlex.quote(directory + '/route_server.py')],
stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=remote_log, text=True, env=env)
ready = exchange(dict(ports=args.ports, password=password))
assert ready['ready']
capture = subprocess.Popen(['sudo', '-n', 'tcpdump', '-i', args.interface,
'-U', '-s', '0', '-w', str(out / 'client.pcap'), 'host ' + args.address +
' and tcp and (' + ' or '.join('port ' + str(port) for port in args.ports) + ' or port 22)'],
stderr=capture_log, stdout=subprocess.DEVNULL, env=env, start_new_session=True)
time.sleep(1)
assert capture.poll() is None
emit(dict(event='start', **ready))
with concurrent.futures.ThreadPoolExecutor(max_workers=15) as pool:
for phase in range(len(MODES)):
mapping = [MODES[(index - phase) % len(MODES)] for index in range(len(MODES))]
health = exchange(dict(event='phase', modes=mapping))
emit(dict(event='phase_start', phase=phase + 1, port_modes=mapping, **health))
assert health['healthy'], 'server-local phase control failed'
commands, ports, proxies = [], [], []
for index, mode in enumerate(MODES):
bridge, proxy = free_port(), free_port()
port = args.ports[(index + phase) % len(MODES)]
commands.append([sys.executable, str(root / 'transport.py'), '--role', 'client',
'--mode', mode, '--listen-port', str(bridge), '--target-host', args.address,
'--target-port', str(port), '--certificate', str(cert)])
commands.append([str(Path(args.stock_bin).resolve()), '-s', '127.0.0.1',
'-p', str(bridge), '-b', '127.0.0.1', '-l', str(proxy), '-k', password,
'-m', 'chacha20-ietf-poly1305'])
ports.extend((bridge, proxy))
proxies.append((mode, proxy, port))
with peers(commands, ports, env):
start = time.monotonic()
pending = []
for tick in range((args.phase_seconds + 4) // 5):
time.sleep(max(0, start + tick * 5 - time.monotonic()))
if tick % 6 == 0:
health = exchange(dict(event='health'))
emit(dict(event='health', phase=phase + 1, **health))
assert health['healthy'], 'server-local/management health failed'
for mode, proxy, port in proxies:
for size in ([1024, args.large_bytes] if tick == 0 else [1024]):
meta = dict(event='transfer', phase=phase + 1, tick=tick, mode=mode, port=port)
pending.append((meta, pool.submit(measured_transfer, meta, proxy, ready['origin'], size)))
remaining = []
for meta, future in pending:
if future.done():
future.result()
else:
remaining.append((meta, future))
pending = remaining
for meta, future in pending:
future.result()
time.sleep(max(0, start + args.phase_seconds - time.monotonic()))
emit(dict(event='phase_complete', phase=phase + 1))
emit(dict(event='complete'))
except BaseException as error:
emit(dict(event='aborted', reason=type(error).__name__ + ': ' + str(error).replace(password, '<redacted>')))
raise
finally:
if remote is not None and remote.poll() is None:
try:
remote.stdin.write(json.dumps(dict(event='stop')) + '\n')
remote.stdin.flush()
remote.wait(timeout=15)
except (BrokenPipeError, subprocess.TimeoutExpired):
remote.terminate()
remote.wait(timeout=15)
if capture is not None and capture.poll() is None:
subprocess.run(['sudo', '-n', 'kill', '-INT', '--', '-' + str(capture.pid)], check=False)
capture.wait(timeout=10)
copied = True
for name in ('server.pcap', 'capture.log'):
with (out / ('remote-' + name)).open('wb') as output:
result = subprocess.run(ssh + ['cat ' + shlex.quote(directory + '/' + name)], stdout=output, env=env)
copied &= result.returncode == 0
if copied:
subprocess.run(ssh + ['rm -rf -- ' + shlex.quote(directory)], check=True, env=env)
emit(dict(event='cleanup', remote_exit=remote.returncode if remote else None, captures_retrieved=copied))
if __name__ == '__main__':
main()
+150
View File
@@ -0,0 +1,150 @@
#!/usr/bin/env python3
"""Private remote supervisor for route_screen.py; JSON commands on SSH stdin."""
import asyncio
import contextlib
import json
import os
from pathlib import Path
import signal
import socket
import subprocess
import sys
import tempfile
from transport import serve
def free_port():
with socket.socket() as sock:
sock.bind(('127.0.0.1', 0))
return sock.getsockname()[1]
async def echo(reader, writer):
try:
while data := await asyncio.wait_for(reader.read(65536), 30):
writer.write(data)
await writer.drain()
except (OSError, TimeoutError):
pass
finally:
writer.close()
with contextlib.suppress(OSError):
await writer.wait_closed()
def stop(processes):
for process in reversed(processes):
if process.poll() is None:
process.send_signal(signal.SIGINT)
for process in processes:
try:
process.wait(timeout=5)
except subprocess.TimeoutExpired:
process.kill()
process.wait()
async def check_control(port, origin_port):
writer = None
try:
reader, writer = await asyncio.open_connection('127.0.0.1', port)
writer.write(bytes([5, 1, 0]))
await writer.drain()
assert await reader.readexactly(2) == bytes([5, 0])
writer.write(bytes([5, 1, 0, 1, 127, 0, 0, 1]) + origin_port.to_bytes(2, 'big'))
await writer.drain()
header = await reader.readexactly(4)
assert header[:3] == bytes([5, 0, 0])
await reader.readexactly(6 if header[3] == 1 else 18)
data = os.urandom(1024)
writer.write(data)
await writer.drain()
assert await reader.readexactly(len(data)) == data
return True
except (OSError, AssertionError, asyncio.IncompleteReadError):
return False
finally:
if writer:
writer.close()
with contextlib.suppress(OSError):
await writer.wait_closed()
async def main():
reader = asyncio.StreamReader()
loop = asyncio.get_running_loop()
pipe, _ = await loop.connect_read_pipe(lambda: asyncio.StreamReaderProtocol(reader), sys.stdin)
cfg = json.loads(await asyncio.wait_for(reader.readline(), 30))
directory = Path(__file__).parent
processes, phase_processes, servers, controls = [], [], [], []
# A controller disconnect or a bounded lifetime closes all owned resources.
task = asyncio.current_task()
loop.call_later(1200, task.cancel)
loop.add_signal_handler(signal.SIGTERM, task.cancel)
with tempfile.TemporaryDirectory(prefix='ss-encoding-config-') as temp, contextlib.ExitStack() as stack:
def spawn(binary, config, name):
path = Path(temp) / (name + '.json')
path.write_text(json.dumps(config))
log = stack.enter_context((Path(temp) / (name + '.log')).open('wb'))
return subprocess.Popen([binary, '-c', str(path)], stdout=log, stderr=log)
origin = await asyncio.start_server(echo, '127.0.0.1', 0)
origin_port = origin.sockets[0].getsockname()[1]
backend = free_port()
common = dict(server='127.0.0.1', server_port=backend, password=cfg['password'],
method='chacha20-ietf-poly1305', mode='tcp_only')
try:
processes.append(spawn(cfg.get('server_binary', '/usr/local/bin/ssserver'), common, 'backend'))
capture_log = stack.enter_context((directory / 'capture.log').open('wb'))
if cfg.get('capture', True):
processes.append(subprocess.Popen(['tcpdump', '-i', 'any', '-U', '-s', '0', '-w',
str(directory / 'server.pcap'), 'tcp and (' + ' or '.join('port ' + str(p) for p in cfg['ports'])
+ ' or (host ' + os.environ['SSH_CONNECTION'].split()[0] + ' and port 22))'],
stdout=subprocess.DEVNULL, stderr=capture_log))
await asyncio.sleep(1)
assert all(p.poll() is None for p in processes)
print(json.dumps(dict(ready=True, origin=origin_port, backend=backend, client_address=os.environ['SSH_CONNECTION'].split()[0])), flush=True)
# Missing control commands also stop the service if the SSH
# connection is blackholed and never delivers EOF.
while line := await asyncio.wait_for(reader.readline(), cfg.get('control_timeout', 60)):
command = json.loads(line)
if command['event'] == 'stop':
break
if command['event'] == 'phase':
stop(phase_processes)
phase_processes.clear()
for server in servers:
server.close()
await server.wait_closed()
servers.clear()
controls.clear()
for index, mode in enumerate(command['modes']):
port = cfg['ports'][index]
server = await serve('server', mode, ('0.0.0.0', port), ('127.0.0.1', backend),
str(directory / 'certificate.pem'), str(directory / 'key.pem'))
servers.append(server)
client = await serve('client', mode, ('127.0.0.1', 0), ('127.0.0.1', port),
str(directory / 'certificate.pem'))
servers.append(client)
control_port = free_port()
config = dict(common, server_port=client.sockets[0].getsockname()[1],
local_address='127.0.0.1', local_port=control_port)
phase_processes.append(spawn('/usr/local/bin/sslocal', config, 'control-' + str(index)))
controls.append(control_port)
await asyncio.sleep(.4)
checks = await asyncio.gather(*(asyncio.wait_for(check_control(port, origin_port), 5)
for port in controls), return_exceptions=True)
healthy = all(p.poll() is None for p in processes + phase_processes)
values = [result is True for result in checks]
print(json.dumps(dict(healthy=healthy and all(values), local_transfers=values)), flush=True)
finally:
pipe.close()
stop(phase_processes)
stop(processes)
for server in servers + [origin]:
server.close()
await server.wait_closed()
if __name__ == '__main__':
asyncio.run(main())
+72
View File
@@ -0,0 +1,72 @@
#!/usr/bin/env python3
"""Run the real supervisor/backend and verify cleanup on lost control input."""
import argparse
import json
import os
from pathlib import Path
import shutil
import signal
import socket
import subprocess
import sys
import tempfile
import unittest
BINARY = None
class SupervisorTests(unittest.TestCase):
def check_cleanup(self, trigger):
with tempfile.TemporaryDirectory() as directory:
root = Path(directory)
for name in ('route_server.py', 'transport.py'):
shutil.copy(Path(__file__).with_name(name), root / name)
env = dict(os.environ, SSH_CONNECTION='127.0.0.1 1 127.0.0.1 22')
with (root / 'log').open('w+') as log:
process = subprocess.Popen([sys.executable, str(root / 'route_server.py')],
stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=log, text=True, env=env)
try:
process.stdin.write(json.dumps(dict(password='supervisor-test-only', ports=[],
capture=False, server_binary=str(BINARY), control_timeout=.3 if trigger == 'timeout' else 60)) + '\n')
process.stdin.flush()
import select
self.assertTrue(select.select([process.stdout], [], [], 5)[0], 'supervisor startup timeout')
ready = json.loads(process.stdout.readline())
self.assertTrue(ready['ready'])
for port in (ready['origin'], ready['backend']):
with socket.create_connection(('127.0.0.1', port), .5):
pass
if trigger == 'eof':
process.stdin.close()
elif trigger == 'signal':
process.send_signal(signal.SIGTERM)
process.wait(timeout=5)
if trigger == 'eof':
self.assertEqual(process.returncode, 0)
for port in (ready['origin'], ready['backend']):
with self.assertRaises(OSError):
socket.create_connection(('127.0.0.1', port), .2)
finally:
if process.poll() is None:
process.kill()
process.wait()
if not process.stdin.closed:
process.stdin.close()
process.stdout.close()
def test_control_eof(self):
self.check_cleanup('eof')
def test_control_silence(self):
self.check_cleanup('timeout')
def test_termination_signal(self):
self.check_cleanup('signal')
if __name__ == '__main__':
parser = argparse.ArgumentParser()
parser.add_argument('--bin', required=True)
args = parser.parse_args()
BINARY = Path(args.bin).resolve() / 'ss-server'
unittest.main(argv=[__file__])
+130
View File
@@ -0,0 +1,130 @@
#!/usr/bin/env python3
"""Codec boundaries, fragmentation, bad records and relay half-close tests."""
import asyncio
import os
from pathlib import Path
import shutil
import tempfile
import unittest
from transport import BLOCK, MODES, decode, encode, read_record, serve
class CodecTests(unittest.IsolatedAsyncioTestCase):
async def test_fragmented_records(self):
for mode in MODES[1:]:
for size in (0, 1, 2, 3, 4, 5, 31, 32, BLOCK):
with self.subTest(mode=mode, size=size):
data = os.urandom(size)
wire = encode(mode, data)
reader = asyncio.StreamReader()
task = asyncio.create_task(read_record(reader, mode))
for index in range(0, len(wire), 7):
reader.feed_data(wire[index:index + 7])
await asyncio.sleep(0)
reader.feed_eof()
self.assertEqual(await task, data)
async def test_coalesced_records(self):
for mode in MODES[1:]:
reader = asyncio.StreamReader()
reader.feed_data(encode(mode, b'one') + encode(mode, b'two') + encode(mode, b''))
for expected in (b'one', b'two', b''):
self.assertEqual(await read_record(reader, mode), expected)
async def test_invalid_and_truncated(self):
for mode in MODES[1:]:
reader = asyncio.StreamReader()
reader.feed_data(encode(mode, b'something')[:-1])
reader.feed_eof()
with self.assertRaises(asyncio.IncompleteReadError):
await read_record(reader, mode)
for mode, invalid in [('base85', b'/'), ('lowpop85', b'\xff')]:
with self.assertRaises(ValueError):
decode(mode, invalid)
reader = asyncio.StreamReader()
reader.feed_data((BLOCK + 1).to_bytes(2, 'big'))
with self.assertRaises(ValueError):
await read_record(reader, 'tls')
async def test_empty_client_does_not_connect_upstream(self):
calls = []
async def connected(reader, writer):
calls.append(True)
writer.close()
await writer.wait_closed()
target = await asyncio.start_server(connected, '127.0.0.1', 0)
async with target:
for mode in MODES[:-1]:
client = await serve('client', mode, ('127.0.0.1', 0), target.sockets[0].getsockname()[:2])
async with client:
_, writer = await asyncio.open_connection(*client.sockets[0].getsockname()[:2])
writer.close()
await writer.wait_closed()
await asyncio.sleep(.03)
self.assertEqual(calls, [])
async def test_tls_half_close_and_certificate_verification(self):
if not shutil.which('openssl'):
self.skipTest('openssl CLI is needed for temporary test certificates')
from local_interop import certificate
calls = []
async def reverse(reader, writer):
calls.append(True)
data = await reader.read()
writer.write(data[::-1])
await writer.drain()
writer.close()
await writer.wait_closed()
with tempfile.TemporaryDirectory() as temp:
good, bad = Path(temp) / 'good', Path(temp) / 'bad'
good.mkdir()
bad.mkdir()
cert, key = certificate(good)
wrong, _ = certificate(bad)
origin = await asyncio.start_server(reverse, '127.0.0.1', 0)
server = await serve('server', 'tls', ('127.0.0.1', 0),
origin.sockets[0].getsockname()[:2], str(cert), str(key))
async with origin, server:
for trusted, succeeds in ((cert, True), (wrong, False)):
client = await serve('client', 'tls', ('127.0.0.1', 0),
server.sockets[0].getsockname()[:2], str(trusted))
async with client:
reader, writer = await asyncio.open_connection(*client.sockets[0].getsockname()[:2])
writer.write(b'certificate-and-half-close-test')
writer.write_eof()
result = await asyncio.wait_for(reader.read(), 5)
self.assertEqual(result, b'tset-esolc-flah-dna-etacifitrec' if succeeds else b'')
writer.close()
await writer.wait_closed()
self.assertEqual(len(calls), 1, 'bad certificate must not reach the backend')
async def test_half_close_and_concurrent_relay(self):
async def reverse(reader, writer):
data = await reader.read()
writer.write(data[::-1])
await writer.drain()
writer.close()
await writer.wait_closed()
origin = await asyncio.start_server(reverse, '127.0.0.1', 0)
target = origin.sockets[0].getsockname()[:2]
async with origin:
for mode in MODES[:-1]:
server = await serve('server', mode, ('127.0.0.1', 0), target)
remote = server.sockets[0].getsockname()[:2]
client = await serve('client', mode, ('127.0.0.1', 0), remote)
address = client.sockets[0].getsockname()[:2]
async def check():
reader, writer = await asyncio.open_connection(*address)
data = os.urandom(BLOCK * 3 + 7)
writer.write(data)
writer.write_eof()
self.assertEqual(await asyncio.wait_for(reader.read(), 5), data[::-1])
writer.close()
await writer.wait_closed()
async with server, client:
await asyncio.gather(*(check() for _ in range(4)))
if __name__ == '__main__':
unittest.main()
+138
View File
@@ -0,0 +1,138 @@
#!/usr/bin/env python3
"""Experimental TCP outer transports. Not a production plugin or crypto scheme.
Run a client relay in front of stock ss-local's remote connection and a server
relay in front of an unchanged ss-server. TLS uses a verified experiment CA.
"""
import argparse
import asyncio
from base64 import b85decode, b85encode
import contextlib
import ssl
MODES = ('raw', 'base85', 'lowpop85', 'tls')
B85 = b'0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz!#$%&()*+-;<=>?@^_`{|}~'
LOW = bytes(sorted(range(256), key=lambda value: (value.bit_count(), value))[:85])
TO_LOW = bytes.maketrans(B85, LOW)
FROM_LOW = bytes.maketrans(LOW, B85)
BLOCK = 16384
def encode(mode, data):
if mode == 'raw':
return data
if mode == 'tls':
return len(data).to_bytes(2, 'big') + data
result = b85encode(data)
return result.translate(TO_LOW) + b'\xff' if mode == 'lowpop85' else result + b'\n'
def decode(mode, data):
if mode == 'lowpop85':
if any(value not in LOW for value in data):
raise ValueError('invalid low-popcount symbol')
data = data.translate(FROM_LOW)
return b85decode(data)
async def read_record(reader, mode):
if mode == 'raw':
return await reader.read(BLOCK)
if mode == 'tls':
length = int.from_bytes(await reader.readexactly(2), 'big')
if length > BLOCK:
raise ValueError('oversized TLS record')
return await reader.readexactly(length)
delimiter = b'\xff' if mode == 'lowpop85' else b'\n'
frame = await reader.readuntil(delimiter)
if len(frame) > (BLOCK * 5 + 3) // 4 + 1:
raise ValueError('oversized encoded record')
return decode(mode, frame[:-1])
async def pump(reader, writer, mode, encoding, initial=None):
while True:
if initial is not None:
data, initial = initial, None
else:
data = await asyncio.wait_for(reader.read(BLOCK) if encoding else read_record(reader, mode), 30)
if encoding:
writer.write(encode(mode, data))
elif data:
writer.write(data)
await writer.drain()
if not data:
if (not encoding or mode == 'raw') and writer.can_write_eof():
writer.write_eof()
return
def tls_context(role, certificate, key=None):
if role == 'server':
context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
context.load_cert_chain(certificate, key)
else:
context = ssl.create_default_context(cafile=certificate)
context.minimum_version = ssl.TLSVersion.TLSv1_3
return context
async def relay(reader, writer, role, mode, target, context=None):
upstream = None
tasks = []
try:
initial = None
if role == 'client':
# Readiness probes and idle connections must not emit empty outer
# records or TLS handshakes that contaminate the route experiment.
initial = await asyncio.wait_for(reader.read(BLOCK), 30)
if not initial:
return
kwargs = {}
if mode == 'tls' and role == 'client':
kwargs = dict(ssl=context, server_hostname='experiment.invalid', ssl_handshake_timeout=10)
remote_reader, upstream = await asyncio.wait_for(asyncio.open_connection(*target, **kwargs), 10)
tasks = [asyncio.create_task(pump(reader, upstream, mode, role == 'client', initial)),
asyncio.create_task(pump(remote_reader, writer, mode, role != 'client'))]
done, _ = await asyncio.wait(tasks, return_when=asyncio.FIRST_EXCEPTION)
for task in done:
task.result()
except (OSError, ValueError, asyncio.IncompleteReadError, asyncio.LimitOverrunError, TimeoutError):
pass
finally:
for task in tasks:
task.cancel()
if tasks:
await asyncio.gather(*tasks, return_exceptions=True)
for peer in (writer, upstream):
if peer is not None:
peer.close()
with contextlib.suppress(OSError, TimeoutError):
await asyncio.wait_for(peer.wait_closed(), 3)
async def serve(role, mode, listen, target, certificate=None, key=None):
context = tls_context(role, certificate, key) if mode == 'tls' else None
kwargs = dict(ssl=context, ssl_handshake_timeout=10) if mode == 'tls' and role == 'server' else {}
return await asyncio.start_server(
lambda reader, writer: relay(reader, writer, role, mode, target, context), *listen, **kwargs)
async def main(args):
server = await serve(args.role, args.mode, (args.listen_host, args.listen_port),
(args.target_host, args.target_port), args.certificate, args.key)
async with server:
await server.serve_forever()
if __name__ == '__main__':
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('--role', choices=('client', 'server'), required=True)
parser.add_argument('--mode', choices=MODES, required=True)
parser.add_argument('--listen-host', default='127.0.0.1')
parser.add_argument('--listen-port', type=int, required=True)
parser.add_argument('--target-host', default='127.0.0.1')
parser.add_argument('--target-port', type=int, required=True)
parser.add_argument('--certificate')
parser.add_argument('--key')
asyncio.run(main(parser.parse_args()))