Add comprehensive documentation for SSL/TLS key logging feature#5279
Add comprehensive documentation for SSL/TLS key logging feature#5279renecannao merged 2 commits intov3.0from
Conversation
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
Summary of ChangesHello @renecannao, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly improves the understanding and safe usage of ProxySQL's SSL/TLS key logging feature by introducing comprehensive documentation. It provides both a detailed developer guide for those extending or maintaining the code, and a practical user guide for administrators needing to debug encrypted traffic. The documentation emphasizes the security risks associated with key logging and offers clear instructions and best practices to mitigate them, ensuring that this powerful debugging tool can be utilized effectively and responsibly. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
There was a problem hiding this comment.
Code Review
This pull request introduces excellent and comprehensive documentation for the SSL/TLS key logging feature. The developer and user guides are well-structured, detailed, and will be a great resource. The Doxygen comments in the code also significantly enhance readability and maintainability. My review focuses on ensuring the accuracy of this new documentation and clarifying a few technical points in the code comments. I've identified a high-priority correction for the log rotation behavior described in the user guide, which currently misrepresents the feature's functionality. Other suggestions aim to improve clarity and correctness in the developer guide and code comments.
|
|
||
| This command: | ||
| 1. Closes the current key log file | ||
| 2. Reopens the file (truncating it if it exists) |
There was a problem hiding this comment.
The documentation incorrectly states that PROXYSQL FLUSH LOGS truncates the keylog file. The implementation uses fopen with the "a+" mode, which opens the file for appending, causing the file to grow continuously. This is a significant discrepancy that could lead to unexpected disk usage and data retention issues. The documentation should be corrected to state that the file is reopened for appending.
| 2. Reopens the file (truncating it if it exists) | |
| 2. Reopens the file for appending. |
| - `MySQL_Session::handler()` for MySQL admin connections | ||
| - `PgSQL_Session::handler()` for PostgreSQL admin connections |
There was a problem hiding this comment.
The documentation states that proxysql_keylog_attach_callback is called for "admin connections". This is misleading, as the callback is attached to the global SSL context used for all frontend (client-to-ProxySQL) connections, which is essential for debugging general application traffic, not just admin-related connections. To improve accuracy, I suggest clarifying that it applies to all frontend connections.
| - `MySQL_Session::handler()` for MySQL admin connections | |
| - `PgSQL_Session::handler()` for PostgreSQL admin connections | |
| - `MySQL_Session::handler()` for frontend MySQL connections | |
| - `PgSQL_Session::handler()` for frontend PostgreSQL connections |
| 2. **Attack scenarios if compromised:** | ||
| - Passive eavesdropping on all TLS traffic | ||
| - Decryption of captured packets | ||
| - Man-in-the-middle attacks with captured packets |
There was a problem hiding this comment.
The documentation lists "Man-in-the-middle attacks" as a direct risk. While the secrets could be leveraged in advanced attacks, the primary and immediate threat from a compromised keylog file is passive eavesdropping and offline decryption of captured traffic. Clarifying this would make the security warning more precise.
| - Man-in-the-middle attacks with captured packets | |
| - Decryption of captured network traffic, exposing all plaintext data, including credentials, queries, and results. |
| sudo tcpdump -i eth0 -w /tmp/proxysql_debug.pcap port 6033 | ||
|
|
||
| # Or capture traffic between specific hosts | ||
| sudo tcpdump -i eth0 -w /tmp/proxysql_debug.pcap host client_ip and host proxyql_ip |
There was a problem hiding this comment.
include/proxysql_sslkeylog.h
Outdated
| * | ||
| * @note Line length is validated (max 254 bytes) | ||
| * @note Lines are newline-terminated if not already present | ||
| * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/HPKP |
lib/proxysql_sslkeylog.cpp
Outdated
| #include "proxysql_sslkeylog.h" | ||
|
|
||
| // NSS Key Log Format reference: | ||
| // http://udn.realityripple.com/docs/Mozilla/Projects/NSS/Key_Log_Format |
There was a problem hiding this comment.
This comment uses an unofficial mirror URL for the NSS Key Log Format specification. For consistency and to ensure developers are referred to the canonical source, please use the official Mozilla Developer Network (MDN) URL, which is already referenced in the file-level Doxygen block.
// https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format
lib/proxysql_sslkeylog.cpp
Outdated
| if (!keylog_file_fp) return; | ||
|
|
||
| /* The current maximum valid keylog line length LF and NUL is 195. */ | ||
| /* The current maximum valid keylog line length including LF and NUL is 195. */ |
There was a problem hiding this comment.
The comment /* The current maximum valid keylog line length including LF and NUL is 195. */ is inconsistent with the implementation. The code uses a 256-byte buffer and validates that the line length does not exceed 254 bytes. The comment should be updated to accurately reflect the buffer size and validation logic.
/* The line is written to a 256-byte buffer. The maximum line length
* from OpenSSL is validated to not exceed 254 bytes to allow for a
* newline and null terminator.
*/
lib/proxysql_sslkeylog.cpp
Outdated
| buf[linelen] = '\0'; | ||
|
|
||
| /* as we are using rwlock, using fputs as it's thread-safe*/ | ||
| /* fputs is used because we're using rwlock (multiple readers allowed) */ |
There was a problem hiding this comment.
The comment /* fputs is used because we're using rwlock (multiple readers allowed) */ could be clearer. The thread safety is guaranteed by the read-write lock, which protects the file pointer and allows multiple threads to write concurrently. The comment should emphasize the role of the lock.
/* The read lock allows multiple threads to write to the file concurrently. */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
|
Thanks @gemini-code-assist for the thorough review! All feedback has been addressed in commit 8c90bda. |
|
That's great to hear, @renecannao! I appreciate you addressing the feedback so promptly. Excellent work on this pull request! |
|



Summary
This PR adds comprehensive documentation for the
ssl_keylog_filefeature (introduced in PR #4236), which enables TLS key logging for debugging encrypted traffic.Background
The
ssl_keylog_filevariable (exposed asadmin-ssl_keylog_filein 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)
include/proxysql_sslkeylog.h (+96 lines)
lib/proxysql_sslkeylog.cpp (+136 lines)
include/proxysql_admin.h (+19 lines)
ssl_keylog_fileDeveloper Documentation
File:
doc/ssl_keylog/ssl_keylog_developer_guide.md(~427 lines)Target audience: Developers working on ProxySQL codebase
Contents:
User Documentation
File:
doc/ssl_keylog/ssl_keylog_user_guide.md(~485 lines)Target audience: End users and system administrators
Contents:
admin-ssl_keylog_file(SQL) vsssl_keylog_file(config)Key Features Documented
Variable Naming Convention
admin-ssl_keylog_filessl_keylog_file(inadmin_variablessection)ssl_keylog_fileProduction Workflow
tshark Examples
Security Notes
The documentation emphasizes:
Files Modified
include/proxysql_admin.hinclude/proxysql_sslkeylog.hlib/proxysql_sslkeylog.cppFiles Added
doc/ssl_keylog/ssl_keylog_developer_guide.mddoc/ssl_keylog/ssl_keylog_user_guide.mdTest Plan