3proxy SSL/TLS Plugin

This plugin can be used to transparently decrypt SSL/TLS data, provide TLS encryption for proxy traffic, and authenticate using client certificates.

For transparent certificate spoofing (MITM):

ssl_mitm - spoof certificates for services started below. Usage without ssl_client_verify is insecure.
ssl_nomitm - do not spoof certificates for services started below

To protect traffic to the server (https:// proxy):

ssl_serv (or ssl_server) - require TLS connection from clients for services below
ssl_noserv (or ssl_noserver) - do not require TLS connection from clients for services below

To use TLS for upstream connections:

ssl_cli (or ssl_client) - establish TLS connection to upstream server for services below
ssl_nocli (or ssl_noclient) - do not establish TLS connection to upstream server for services below

Parameters:

ssl_server_cert /path/to/cert - Server certificate (should not be self-signed and must contain an Alternative Name) for ssl_serv
ssl_server_key /path/to/key - Server certificate key for ssl_server_cert or generated MITM certificate
ssl_client_cert /path/to/cert - Client certificate for authentication on upstream server (used with ssl_cli)
ssl_client_key /path/to/key - Client certificate key for ssl_client_cert
ssl_client_ciphersuites ciphersuites_list - TLS client ciphers for TLS 1.3, e.g., ssl_client_ciphersuites TLS_AES_128_GCM_SHA256
ssl_server_ciphersuites ciphersuites_list - TLS server ciphers for TLS 1.3
ssl_client_cipher_list ciphers_list - TLS client ciphers for TLS 1.2 and below, e.g., ssl_client_cipher_list ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305
ssl_server_cipher_list ciphers_list - TLS server ciphers for TLS 1.2 and below
ssl_client_min_proto_version tls_version - TLS client minimum TLS version (e.g., TLSv1.2)
ssl_server_min_proto_version tls_version - TLS server minimum TLS version (e.g., TLSv1.2)
ssl_client_max_proto_version tls_version - TLS client maximum TLS version (e.g., TLSv1.2)
ssl_server_max_proto_version tls_version - TLS server maximum TLS version (e.g., TLSv1.2)
ssl_client_verify - verify the certificate for the upstream server in TLS client functionality (used with ssl_mitm or ssl_cli)
ssl_client_no_verify - do not verify the certificate for the upstream server in TLS client functionality (default)
ssl_server_verify - require client certificate authentication (mTLS) for ssl_serv
ssl_server_no_verify - do not require client certificate (default)
ssl_server_ca_file /path/to/cafile - CA certificate file for MITM
ssl_server_ca_key /path/to/cakey - key for ssl_server_ca_file MITM CA
ssl_server_ca_dir /path/to/cadir - CA directory for ssl_server_verify
ssl_server_ca_store /path/to/castore - CA store for ssl_server_verify (OpenSSL 3.0+)
ssl_client_ca_file /path/to/cafile - CA file for ssl_client_verify
ssl_client_ca_dir /path/to/cadir - CA directory for ssl_client_verify
ssl_client_ca_store /path/to/castore - CA store for ssl_client_verify (OpenSSL 3.0+)
ssl_client_sni hostname - SNI hostname to send to upstream server (overrides the requested hostname)
ssl_client_alpn protocol1 protocol2 ... - ALPN protocols to negotiate with upstream server (e.g., ssl_client_alpn h2 http/1.1)
ssl_client_mode mode - when to establish TLS connection: 0 - on connect (default), 1 - after authentication, 2 - before data, 3 - only for secure parent types (ending with 's')
ssl_certcache /path/to/cache/ - location for the generated MITM certificates cache, optional if ssl_server_ca_file / ssl_server_ca_key are configured. The cache may contain 3 files: 3proxy.pem - public self-signed certificates (used if ssl_server_ca_file is not configured), 3proxy.key - key for public certificates, used if ssl_server_ca_key is not configured, server.key - this key is used if ssl_server_key is not configured to generate spoofed certificates. If server.key is absent, 3proxy.key is used to generate certificates. Generated certificates are placed in the same path.

MITM example:

plugin /path/to/SSLPlugin.so ssl_plugin
ssl_server_ca_file /path/to/cafile
ssl_server_ca_key /path/to/cakey
ssl_mitm
proxy -p3128
ssl_nomitm
proxy -p3129

MITM's traffic with a spoofed certificate for the port 3128 proxy.

https:// proxy example:

plugin /path/to/SSLPlugin.so ssl_plugin
ssl_server_cert path_to_cert
ssl_server_key path_to_key
ssl_serv
proxy -p33128
ssl_noserv
proxy -p3128

Creates an https:// proxy on port 33128 and an http:// proxy on port 3128

TLS client example (connect to upstream via TLS):

plugin /path/to/SSLPlugin.so ssl_plugin
ssl_client_cert /path/to/client.crt
ssl_client_key /path/to/client.key
ssl_client_verify
ssl_client_ca_file /path/to/ca.crt
ssl_cli
proxy -p3128

Creates an HTTP proxy that connects to upstream servers via TLS with client certificate authentication.

Conditional TLS for parent proxy (ssl_client_mode 3):

plugin /path/to/SSLPlugin.so ssl_plugin
ssl_server_cert /path/to/server.crt
ssl_server_key /path/to/key
ssl_client_mode 3

auth strong
allow user1
parent 1000 https parent1.example.com 443
allow user2
parent 1000 socks5 parent2.example.com 1080
ssl_serv
ssl_cli
proxy -p3128
ssl_noserv
ssl_nocli

Creates an HTTP proxy on port 3128 that uses TLS for client connections (ssl_serv). With ssl_client_mode 3, TLS handshake to parent proxy is performed only if the parent type ends with 's' (secure types). In this example, user1's traffic goes through an https parent proxy with TLS encryption, while user2's traffic goes through a regular socks5 parent without TLS. Secure parent types include: tcps, https, connects, connect+s, socks4s, socks5s, socks4+s, socks5+s, pop3s, smtps, ftps.

mTLS example (require client certificate):

plugin /path/to/SSLPlugin.so ssl_plugin
ssl_server_cert /path/to/server.crt
ssl_server_key /path/to/server.key
ssl_server_ca_file /path/to/ca.crt
ssl_server_verify
ssl_serv
proxy -p3128