From 858f361de104c26e0bffb632665a0cb057083e96 Mon Sep 17 00:00:00 2001 From: Vladimir Dubrovin <3proxy@3proxy.ru> Date: Sat, 4 Apr 2026 20:54:20 +0300 Subject: [PATCH] SSLPlugin documentation updated --- doc/html/plugins/SSLPlugin.html | 90 ++++++++++++++++++------- doc/html/plugins/SSLPlugin.ru.html | 104 ++++++++++++++++++++--------- 2 files changed, 137 insertions(+), 57 deletions(-) diff --git a/doc/html/plugins/SSLPlugin.html b/doc/html/plugins/SSLPlugin.html index 634c4bd..24f25f6 100644 --- a/doc/html/plugins/SSLPlugin.html +++ b/doc/html/plugins/SSLPlugin.html @@ -1,35 +1,51 @@

3proxy SSL/TLS Plugin

-This plugin can be used to transparently decrypt SSL/TLS data and provide TLS encryption for proxy traffic. +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:

+

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) - since version 0.9.5

-ssl_serv - require TLS connection for services below -
ssl_noserv - do not require TLS connection for services below +

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

-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_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 ciphersuites_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 ciphersuites_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) -
ssl_client_no_verify - do not verify the certificate for the upstream server in TLS client functionality (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_client_ca_file, ssl_client_ca_dir, ssl_client_ca_store - locations for root CAs used with ssl_client_verify for TLS client -
ssl_certcache /path/to/cache/ - location for the generated MITM certificates cache, optional if ssl_server_ca_file / ssl_server_ca_key are configured. +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 +
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 @@ -39,7 +55,7 @@ Generated certificates are placed in the same path.

MITM example:

-plugin /path/to/SslPlugin.dll ssl_plugin
+plugin /path/to/SSLPlugin.so ssl_plugin
 ssl_server_ca_file /path/to/cafile
 ssl_server_ca_key /path/to/cakey
 ssl_mitm
@@ -61,4 +77,28 @@ 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. + +

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
+
+Creates an https:// proxy that requires client certificate authentication. + © Vladimir Dubrovin, License: BSD style diff --git a/doc/html/plugins/SSLPlugin.ru.html b/doc/html/plugins/SSLPlugin.ru.html index 4aa292e..06e3790 100644 --- a/doc/html/plugins/SSLPlugin.ru.html +++ b/doc/html/plugins/SSLPlugin.ru.html @@ -1,41 +1,58 @@

3proxy SSL/TLS плагин

-Плагин можно использовать для перехвата и дешифровки SSL/TLS трафика и для шифрования трафика прокси-сервера +Плагин можно использовать для перехвата и дешифровки SSL/TLS трафика, для шифрования трафика прокси-сервера и аутентификации с помощью клиентских сертификатов. -

Для транспаретной перехватки трафика (mitm):

+

Для прозрачного перехвата трафика (MITM):

-
ssl_mitm - подменять сертификаты для сервисов стартованных ниже. Не безопасно использовать без ssl_client_verify. -
ssl_nomitm - не подменять сертификаты для сервисов стартованных ниже. +
ssl_mitm - подменять сертификаты для сервисов, запущенных ниже. Использование без ssl_client_verify небезопасно. +
ssl_nomitm - не подменять сертификаты для сервисов, запущенных ниже. +

Для защиты трафика прокси-сервера (https:// proxy):

-

Для защиты трафика прокси-сервера (например https:// proxy) - начиная с 0.9.5

-ssl_serv - включает TLS для соединений к сервисам ниже -
ssl_noserv - отключает TLS для соединений к сервисам ниже +ssl_serv (или ssl_server) - требовать TLS-соединение от клиентов для сервисов, запущенных ниже +
ssl_noserv (или ssl_noserver) - не требовать TLS-соединение от клиентов для сервисов, запущенных ниже -Параметры: -
ssl_server_cert /path/to/cert - сертификат сервера, не должен быть самоподписаным, имя CN должно содержаться в альтернативных именах - используется для ssl_serv -
ssl_server_key /path/to/key - ключ сертификата сервера для ssl_server_cert или сгенерированного сертификата ssl_mitm -
ssl_client_ciphersuites ciphersuites_list - наборы шифрова TLS для TLS 1.3, пример ssl_client_ciphersuites TLS_AES_128_GCM_SHA256 -
ssl_server_ciphersuites ciphersuites_list - наборы шифрова TLS для TLS 1.3 -
ssl_client_cipher_list ciphersuites_list - наборы шифрова TLS для TLS 1.2 и ниже, пример 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 ciphersuites_list - наборы шифрова TLS для TLS 1.2 и ниже -
ssl_client_min_proto_version tls_version - минимальная версия TLS клиента (например ssl_client_min_proto_version TLSv1.2) -
ssl_server_min_proto_version tls_version - минимальная версия TLS сервера -
ssl_client_max_proto_version tls_version - максимальная версия TLS клиента -
ssl_server_max_proto_version tls_version - максимальная версия TLS сервера -
ssl_client_verify - проверять сертификат сервера назначения (используется с ssl_mitm) -
ssl_client_no_verify - не проверять сертификат сервера назначения -
ssl_server_ca_file /path/to/cafile - CA сертификат для ssl_mitm -
ssl_server_ca_key /path/to/cakey - ключ CA сертификата ssl_server_ca_file mitm -
ssl_client_ca_file, ssl_client_ca_dir, ssl_client_ca_store - расположения корневых сертификатов ssl_client_verify -
ssl_certcache /path/to/cache/ - расположение кеша сгенерированных сертификатов ssl_mitm. Кеш может содержать -файлы 3proxy.pem, 3proxy.key server.key, которые используются как ssl_server_ca_file, -ssl_server_ca_key и ssl_server_key соответственно если они не заданы. Если server.key не задан, +

Для использования TLS при соединении к вышестоящему серверу:

+ +ssl_cli (или ssl_client) - устанавливать TLS-соединение к вышестоящему серверу для сервисов, запущенных ниже +
ssl_nocli (или ssl_noclient) - не устанавливать TLS-соединение к вышестоящему серверу для сервисов, запущенных ниже + +

Параметры:

+ +
ssl_server_cert /path/to/cert - сертификат сервера (не должен быть самоподписанным, должен содержать альтернативные имена) для ssl_serv +
ssl_server_key /path/to/key - ключ сертификата сервера для ssl_server_cert или сгенерированного MITM-сертификата +
ssl_client_cert /path/to/cert - клиентский сертификат для аутентификации на вышестоящем сервере (используется с ssl_cli) +
ssl_client_key /path/to/key - ключ клиентского сертификата для ssl_client_cert +
ssl_client_ciphersuites ciphersuites_list - наборы шифров TLS для TLS 1.3 (клиент), пример: ssl_client_ciphersuites TLS_AES_128_GCM_SHA256 +
ssl_server_ciphersuites ciphersuites_list - наборы шифров TLS для TLS 1.3 (сервер) +
ssl_client_cipher_list ciphers_list - наборы шифров TLS для TLS 1.2 и ниже (клиент), пример: 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 для TLS 1.2 и ниже (сервер) +
ssl_client_min_proto_version tls_version - минимальная версия TLS клиента (например, ssl_client_min_proto_version TLSv1.2) +
ssl_server_min_proto_version tls_version - минимальная версия TLS сервера +
ssl_client_max_proto_version tls_version - максимальная версия TLS клиента +
ssl_server_max_proto_version tls_version - максимальная версия TLS сервера +
ssl_client_verify - проверять сертификат вышестоящего сервера (используется с ssl_mitm или ssl_cli) +
ssl_client_no_verify - не проверять сертификат вышестоящего сервера (по умолчанию) +
ssl_server_verify - требовать клиентский сертификат (mTLS) для ssl_serv +
ssl_server_no_verify - не требовать клиентский сертификат (по умолчанию) +
ssl_server_ca_file /path/to/cafile - файл CA-сертификата для MITM +
ssl_server_ca_key /path/to/cakey - ключ CA-сертификата ssl_server_ca_file для MITM +
ssl_server_ca_dir /path/to/cadir - директория CA-сертификатов для ssl_server_verify +
ssl_server_ca_store /path/to/castore - хранилище CA-сертификатов для ssl_server_verify (OpenSSL 3.0+) +
ssl_client_ca_file /path/to/cafile - файл CA-сертификатов для ssl_client_verify +
ssl_client_ca_dir /path/to/cadir - директория CA-сертификатов для ssl_client_verify +
ssl_client_ca_store /path/to/castore - хранилище CA-сертификатов для ssl_client_verify (OpenSSL 3.0+) +
ssl_client_sni hostname - SNI-имя хоста для отправки вышестоящему серверу (переопределяет запрошенное имя хоста) +
ssl_client_alpn протокол1 протокол2 ... - ALPN-протоколы для согласования с вышестоящим сервером (например, ssl_client_alpn h2 http/1.1) +
ssl_client_mode режим - когда устанавливать TLS-соединение: 0 - при подключении (по умолчанию), 1 - после аутентификации, 2 - перед передачей данных +
ssl_certcache /path/to/cache/ - расположение кеша сгенерированных MITM-сертификатов. Кеш может содержать +файлы 3proxy.pem, 3proxy.key, server.key, которые используются как ssl_server_ca_file, +ssl_server_ca_key и ssl_server_key соответственно, если они не заданы. Если server.key не задан, 3proxy.key используется для генерации серверного сертификата. -

Пример mitm:

+

Пример MITM:

-plugin /path/to/SslPlugin.dll ssl_plugin
+plugin /path/to/SSLPlugin.so ssl_plugin
 ssl_server_ca_file /path/to/cafile
 ssl_server_ca_key /path/to/cakey
 ssl_mitm
@@ -43,9 +60,9 @@ proxy -p3128
 ssl_nomitm
 proxy -p3129
-Перехватывается трафик в прокси на порту 3128 +Перехватывается трафик в прокси на порту 3128. -

Пример конфигурации https:// прокси (curl -x https://...):

+

Пример конфигурации https:// прокси:

 plugin /path/to/SSLPlugin.so ssl_plugin
 ssl_server_cert path_to_cert
@@ -55,7 +72,30 @@ proxy -p33128
 ssl_noserv
 proxy -p3128
-На порту 33128 создается https:// прокси (не путать с CONNECT прокси aka HTTPS over HTTP прокси), на порту 3128 -создается http:// прокси (может пропуска в т.ч. и HTTPS коннекты) +На порту 33128 создается https:// прокси, на порту 3128 - http:// прокси. + +

Пример TLS-клиента (соединение к вышестоящему серверу через 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
+
+Создается HTTP-прокси, который соединяется с вышестоящими серверами через TLS с аутентификацией по клиентскому сертификату. + +

Пример mTLS (требование клиентского сертификата):

+
+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
+
+Создается https:// прокси, требующий аутентификацию по клиентскому сертификату. © Vladimir Dubrovin, License: BSD style