proxysql

Commit Graph

Author	SHA1	Message	Date
Rahim Kanji	50221943a3	Fix numbering in ssl_keylog user guide troubleshooting section (#5281 )	3 months ago
Rahim Kanji	f2bd222145	Fixed compilation issue	3 months ago
Rahim Kanji	e7ee68dda5	Add SSL/TLS traffic decryption for PostgreSQL backend connections (#5281 ) Extends the existing NSS keylog-based SSL decryption to PostgreSQL backend connections by patching libpq with a global PQsetSSLKeyLogCallback() API. When admin-ssl_keylog_file is configured, TLS secrets from all PgSQL backend SSL handshakes are written to the keylog file in NSS Key Log Format, enabling traffic decryption with Wireshark/tshark. Approach: - Patch libpq with global callback following the PQsslKeyPassHook pattern - Single startup call covers all backend paths (regular, monitor, kill, harvester) - No new admin variables — existing admin-ssl_keylog_file covers PgSQL backends - Zero changes to ProxySQL PgSQL connection code Includes 9 integration tests (pgsql-ssl_keylog-t) and user guide updates.	3 months ago
Rene Cannao	8c90bda52a	Address gemini-code-assist review comments for SSL keylog documentation This commit addresses all review comments from gemini-code-assist on PR #5279: 1. Fixed FLUSH LOGS documentation - clarified that file is reopened for appending, not truncating, and updated the note about preserving contents 2. Fixed callback documentation - clarified that the callback attaches to all frontend connections, not just admin connections 3. Updated security warning - focused on passive eavesdropping and offline decryption as the primary threats 4. Fixed typo: proxyql_ip -> proxysql_ip in tcpdump example 5. Removed misleading @see HPKP link - HPKP is unrelated to NSS Key Log Format and is a deprecated feature 6. Updated NSS Key Log Format URL to use official MDN link instead of unofficial mirror 7. Fixed buffer size comment to accurately reflect 256-byte buffer and 254-byte line length validation 8. Clarified fputs comment to emphasize the read lock's role in allowing concurrent writes from multiple threads	6 months ago
Rene Cannao	442635b721	Add comprehensive documentation for SSL/TLS key logging feature This commit adds extensive documentation for the ssl_keylog_file feature (introduced in PR #4236), which enables TLS key logging for debugging encrypted traffic. ## Background The ssl_keylog_file variable (exposed as admin-ssl_keylog_file in SQL interface) allows ProxySQL to write TLS secrets to a file in NSS Key Log Format. These secrets can be used by tools like Wireshark and tshark to decrypt and analyze TLS traffic for debugging purposes. ## Changes ### Inline Documentation (Code) 1. include/proxysql_sslkeylog.h (+96 lines) - File-level documentation explaining the module purpose and security - Doxygen comments for all 5 public APIs - Thread-safety annotations - Parameter descriptions and return values 2. lib/proxysql_sslkeylog.cpp (+136 lines) - Implementation-level documentation - Algorithm explanations (double-checked locking, thread safety) - Reference to NSS Key Log Format specification 3. include/proxysql_admin.h (+19 lines) - Variable documentation for ssl_keylog_file - Path handling rules (absolute vs relative) - Security implications ### Developer Documentation (doc/ssl_keylog/ssl_keylog_developer_guide.md) Target audience: Developers working on ProxySQL codebase Contents: - Variable naming convention (SQL vs config file vs internal) - Architecture diagrams - Thread safety model (pthread rwlock) - NSS Key Log Format specification - Complete API reference for all public functions - Integration points in the codebase - Security considerations and code review checklist - Testing procedures ### User Documentation (doc/ssl_keylog/ssl_keylog_user_guide.md) Target audience: End users and system administrators Contents: - What is SSL key logging and when to use it - Variable naming: admin-ssl_keylog_file (SQL) vs ssl_keylog_file (config) - Step-by-step enable/disable instructions - Path resolution (absolute vs relative) - Log rotation procedures - Production workflow: tcpdump capture → offline analysis - Wireshark (GUI) integration tutorial - tshark (command-line) usage examples - Troubleshooting common issues - Security best practices - Quick reference card ## Key Features Documented 1. Variable Naming Convention - SQL interface: SET admin-ssl_keylog_file = '/path'; - Config file: ssl_keylog_file='/path' (in admin_variables section) - Internal code: ssl_keylog_file 2. Production Workflow - Capture traffic with tcpdump (no GUI on production server) - Transfer pcap + keylog to analysis system - Analyze offline with Wireshark (GUI) or tshark (CLI) 3. tshark Examples - Command-line analysis of encrypted traffic - Filter examples for debugging TLS issues - JSON export for automated analysis ## Security Notes The documentation emphasizes that: - Key log files contain cryptographic secrets that decrypt ALL TLS traffic - Access must be restricted (permissions 0600) - Only enable for debugging, never in production - Securely delete old key log files ## Files Modified - include/proxysql_admin.h - include/proxysql_sslkeylog.h - lib/proxysql_sslkeylog.cpp ## Files Added - doc/ssl_keylog/ssl_keylog_developer_guide.md - doc/ssl_keylog/ssl_keylog_user_guide.md	6 months ago

5 Commits (6cdd4e697eb86982e3dfd2ceab009ead5da0efcb)