click0/Example_microsocks_stunnel_freebsd_config.md

Socks5 proxy using Microsocks and Stunnel on FreeBSD

Configuration information for the Microsocks package on FreeBSD as the existing documentation does not give sufficient details to create a secure configuration flexible enough to use for various use cases. See https://github.com/rofl0r/microsocks for the latest source code and wiki documentation. Note: The user authentication method supported by Microsocks is only plaintext, and is not protected by any layer of encryption. Please be hyper aware and use other layers of protection to secure your socks5 endpoint. (Firewall + TLS encryption with client authentication using something like stunnel).

If you want an easy way of doing this, just look at ssh -D localhost:1080 <user@host> instead since SSH provides a native Socks5 tunnel with encryption.
You can also use stunnel in socks5 protocol mode without Microsocks since it has native support for protocol = socks. See stunnel documentation here: https://www.stunnel.org/static/stunnel.html#SERVICE-LEVEL-OPTIONS

Create a new secure socks5 user authentication password and unique socks5 authentication username for clients to authenticate to the socks5 microsocks proxy. You can use less secure strings, but the example here shows a 36-byte random value encoded into base64 so that it will not impact shell scripts with unusual characters.
- Save the random socks5 username in /root/socks5_user
- Save the random socks5 password in /root/socks5_psw
```
openssl rand -base64 36 >/root/socks5_user
openssl rand -base64 36 >/root/socks5_psw
chmod 600 /root/socks5_*
```
- Feel free to add these username/password values into your favorite password manager for safe keeping. These also can be rotated as needed, and additional authentication options can be configured or layered.
- Note: Unfortunately, Microsocks does not support a config file, so the username/password is visible in the process list
Pick an os user to run the process in a more restricted permission. I use the built-in FreeBSD nobody account.
Determine if your access method supports socks5 authentication (curl does, Firefox does not) to configure the command line arguments in the most secure functional way. If you plan to use Firefox, use the -1 argument as show in the example below to allow users to externally authenticate (I use curl) their origin ip address "one time", then then firefox will be allowed from the same ip address until Microsocks is restarted.

Install and enable Microsocks on FreeBSD server

Installs microsocks to /usr/local/bin/microsocks and init script to /usr/local/etc/rc.d/microsocks
Configures /etc/rc.conf variable to enable at system startup
```
pkg install microsocks
service microsocks enable
```

Configure Microsocks Server in FreeBSD `/etc/rc.conf`

Define the FreeBSD userid to run the process under using the daemon(8) command and assign to microsocks_user variable (Example shows the "nobody" os userid.
Configure the service parameters under microsocks_args variable
- 1-time auth (-1) if using Firefox or other non-authenticating Socks5 proxy client applications
- listen on loopback addresses (-i 127.0.0.1) You can omit if you are just running ipv4 and want to listen on 0.0.0.0 (default)
- username for socks5 auth (-u )
- password for socks5 auth (-P )
```
sysrc microsocks_user="nobody"
sysrc microsocks_args="-1 -i :: -u $(cat /root/socks5_user) -P $(cat /root/socks5_psw)"
```

Configure stunnel on Windows client (same box as web browser/sock5 client application)

Download the Stunnel Windows installer package.

PowerShell Download:

invoke-webrequest https://www.stunnel.org/archive/5.x/stunnel-5.69-win64-installer.exe -Outfile stunnel-5.69-win64-installer.exe

Curl Download:

curl -O https://www.stunnel.org/archive/5.x/stunnel-5.69-win64-installer.exe

Execute the Installer Follow the prompts, and allow the key/certificate to be generated at the end. You will use this as your encryption key/certificate pair.
```
stunnel-5.69-win64-installer.exe
```

Configure stunnel.conf with

notepad++ AppData\Local\Programs\stunnel\config\stunnel.conf

; Add the following lines to your stunnel.conf, and remove any other client/server listeners
[socks5-TLS-shim-client]
client = yes
accept = 127.0.0.1:1080
accept = ::1:1080
connect = host.domain.name:1084
; change to 1083 to test native stunnel socks5 support instead
;connect = host.domain.name:1083
verifypeer = yes
cafile = stunnel.pem

Copy the stunnel.pem file generated at install time from the Windows client. This files contains both the private key, and the certificate in the correct format. Or you can generate your own (as desired). The client will be setup to ONLY allow one certificate with the verifypeer = yes configuration line. Note: .pem contains dos line endings, but stunnel on FreeBSD will ignore as extraneous.
```
# From windows client to FreeBSD server.  (Example below assumes user install folder, adjust as required)
cd AppData\Local\Programs\stunnel\config
scp stunnel.pem [email protected]:
```

Configure stunnel on FreeBSD Server (same FreeBSD box as Microsocks)

Install stunnel

pkg install stunnel
service enable stunnel

Configure stunnel

vi /usr/local/etc/stunnel/stunnel.conf

; Add the following lines to your stunnel.conf, and remove any other client/server listeners

; Native stunnel socks5 server for comparison
[socks5-stunnel-server]
protocol = socks
accept = 1083
cert = /usr/local/etc/stunnel/stunnel.pem

; Redirect to the loopback interface of Microsocks listener
[microsocks-TLS-shim-server]
accept = 1084
connect = 127.0.0.1:1080
cert = /usr/local/etc/stunnel/stunnel.pem

Copy the stunnel.pem file that was scped to the /home/user/ folder during the Windows configuration steps into the correct location for FreeBSD.

# From FreeBSD server
mv /home/user/stunnel.pem /usr/local/etc/stunnel/
chmod 600 /usr/local/etc/stunnel/stunnel.pem
service stunnel start

Configure Firefox for Socks5 Proxy

Choose Firefox "Tools"(Menu)->"Settings"(option)->Type "proxy"(into search field)->Click "Settings"(button)
Configure the hostname (or ip address) of the listener for microsocks under "Manual Proxy Configuration" See Screenshot below
Configure the tcp port configured for Microsocks listener (defaults to 1080)
Configure any host names or ip address ranges to exclude from using the proxy (Example 192.168.0.0/16)
Configure Firefox to perform dns lookups using socks5 (helps with privacy and unusual endpoint firewall configurations)

Execute curl (from same box as firefox) to authenticate a new session before having firefox navigate to a url

# If you are unsure which ip address will be used in a dual-stack network, authenticate both ipv4 and ipv6 
# individually rather than letting your os/browser automatic address selection choose, as "happy eyeballs" can have
# unforseen side effects
curl -4 --socks5 <user>:<password>@localhost:1080 https://icanhazip.com
curl -6 --socks5 <user>:<password>@localhost:1080 https://icanhazip.com

The url of https://icanhazip.com can be any valid url. This is just to invoke a session through the socks5 microsocks proxy, and authenticate.

TODO:

Add documentation on stunnel native protocol = socks authentication options. - https://www.stunnel.org/static/stunnel.html#EXAMPLES
Add documentation on mTLS client authentication using private CA and user client certificates - Example CA setup: https://jamielinux.com/docs/openssl-certificate-authority/
Add documentation on mTLS client authentication using pkcs11 (Yubikey)