2 Commits (db5f1ea498f736d4ff733bbd41ec649d073cf932)

Author	SHA1	Message	Date
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	3 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	3 months ago