jcs.org
decrypting SOCKS proxy
1## sockhole
2
3`sockhole` is a decrypting
4[SOCKS](https://en.wikipedia.org/wiki/SOCKS)
5proxy.
6When it receives a request to make a connection to a port listed in its
7`TLS_PORTS` list, it will establish the encrypted connection itself, verify the
8TLS certificate, and then proxy decrypted data to the client as if the
9connection were made to a plaintext service.
10
11This is intended to support old software/equipment which supports SOCKS proxies
12but does not support SSL/TLS or modern ciphers.
13That software can establish a plaintext connection over a trusted LAN
14connection to a local machine running `sockhole`, and the `sockhole` proxy can
15establish a secure tunnel over the public internet.
16
17For example, a computer running a POP3 client with SOCKS proxy support but no
18SSL support can connect to a remote POP3 server over TLS just by switching the
19port configured in the POP3 client to 995 (POP3S).
20
21### Installation
22
23 server$ bundle install --path vendor/bundle
24
25### Use
26
27 server$ bundle exec ruby sockhole.rb
28
29Supported options:
30
31- `-a allowed range`: add the IP/mask to the list of allowed IPs; defaults to
32 the /24 of the listen IP
33- `-d`: enable debugging
34- `-p port`: set the listen port (defaults to 1080)
35- `-i ip`: set the listen IP (defaults to the first non-loopback IP on all
36 interfaces)
37
38### Client Examples
39
40#### Curl
41
42`curl` should be instructed to use the `http` protocol on port 443, not
43`https`, or else it will expect encrypted data to come through the SOCKS proxy.
44However, when specifying a URL of `http://example.com:443/`, `curl` will send a
45header of `Host: example.com:443` which may cause problems on the server end
46with it not matching a configured virtual host.
47The `-H` option can be used to override the sent `Host` header to remove the
48port:
49
50 server$ bundle exec ruby sockhole.rb
51 [2020-11-12 08:47:24 -0600] [I] [server] listening on 192.168.1.1:1080
52
53 client$ curl -H "Host: example.com" --preproxy socks5h://192.168.1.1 http://example.com:443/
54 <!doctype html>
55 ...
56
57When connecting to a TLS host with an invalid certificate, `sockhole` will reject
58the client before it sends any data.
59
60 client$ curl -H "Host: wrong.host.badssl.com" --preproxy socks5h://192.168.1.1 http://wrong.host.badssl.com:443/
61 curl: (97) connection to proxy closed
62
63#### nc
64
65 client$ nc -x 192.168.1.1 imap.fastmail.com imaps
66 * OK IMAP4 ready