Skip to content

Add comprehensive documentation for SSL/TLS key logging feature#5279

Merged
renecannao merged 2 commits intov3.0from
v3.0-keylog_doc
Jan 7, 2026
Merged

Add comprehensive documentation for SSL/TLS key logging feature#5279
renecannao merged 2 commits intov3.0from
v3.0-keylog_doc

Conversation

@renecannao
Copy link
Contributor

Summary

This PR adds comprehensive 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

File: doc/ssl_keylog/ssl_keylog_developer_guide.md (~427 lines)

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

File: doc/ssl_keylog/ssl_keylog_user_guide.md (~485 lines)

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 with Wireshark/tshark
  • Wireshark (GUI) integration tutorial
  • tshark (command-line) usage with practical examples
  • Troubleshooting common issues
  • Security best practices
  • Quick reference card

Key Features Documented

Variable Naming Convention

Context Variable Name
SQL interface admin-ssl_keylog_file
Config file ssl_keylog_file (in admin_variables section)
Internal code ssl_keylog_file

Production Workflow

tcpdump capture → transfer files → offline analysis
     (on server)      (scp/sftp)         (Wireshark/tshark)

tshark Examples

# Decrypt TLS traffic from pcap with key log
tshark -r capture.pcap -o tls.keylog_file:sslkeys.txt -V

# Show only MySQL packets
tshark -r capture.pcap -o tls.keylog_file:sslkeys.txt -Y "mysql"

# Export decrypted payloads to JSON
tshark -r capture.pcap -o tls.keylog_file:sslkeys.txt -T json

Security Notes

The documentation emphasizes:

  • 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

Test Plan

  • Documentation builds successfully
  • Code compiles without errors
  • Variable naming follows ProxySQL conventions

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
@gemini-code-assist
Copy link

Summary of Changes

Hello @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

  • Comprehensive Documentation: Added extensive documentation for the ssl_keylog_file feature, covering both developer and user perspectives to ensure clear understanding and safe usage.
  • Developer Guide: Introduced a new developer guide (ssl_keylog_developer_guide.md) detailing variable naming conventions, architectural overview, thread safety model, API reference, integration points, and security considerations for the key logging module.
  • User Guide: Created a new user guide (ssl_keylog_user_guide.md) with practical instructions on enabling/disabling key logging, path resolution, log rotation, and step-by-step examples for analyzing encrypted traffic using Wireshark and tshark.
  • Inline Code Documentation: Enhanced inline Doxygen comments across proxysql_admin.h, proxysql_sslkeylog.h, and proxysql_sslkeylog.cpp to thoroughly explain the purpose, usage, thread-safety, and security implications of the ssl_keylog_file variable and related functions.
  • Security Emphasis: Clearly outlined critical security implications of the key logging feature, including warnings about sensitive data exposure, recommended safeguards, and best practices for its use in debugging versus production environments.

🧠 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 Assist

The 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 /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

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 .gemini/ folder in the base of the repository. Detailed instructions can be found here.

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

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

Copy link

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

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.

Suggested change
2. Reopens the file (truncating it if it exists)
2. Reopens the file for appending.

Comment on lines +206 to +207
- `MySQL_Session::handler()` for MySQL admin connections
- `PgSQL_Session::handler()` for PostgreSQL admin connections

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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.

Suggested change
- `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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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.

Suggested change
- 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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

There is a typo in the example tcpdump command. proxyql_ip should be proxysql_ip.

Suggested change
sudo tcpdump -i eth0 -w /tmp/proxysql_debug.pcap host client_ip and host proxyql_ip
sudo tcpdump -i eth0 -w /tmp/proxysql_debug.pcap host client_ip and host proxysql_ip

*
* @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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The @see link points to the documentation for HTTP Public Key Pinning (HPKP). This is unrelated to the NSS Key Log Format and is also a deprecated web security feature. This link is misleading and should be removed to avoid confusion.

#include "proxysql_sslkeylog.h"

// NSS Key Log Format reference:
// http://udn.realityripple.com/docs/Mozilla/Projects/NSS/Key_Log_Format

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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

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. */

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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.
     */

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) */

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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. */

@renecannao renecannao added this to the Release 3.0.5 milestone Jan 7, 2026
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
@renecannao
Copy link
Contributor Author

Thanks @gemini-code-assist for the thorough review! All feedback has been addressed in commit 8c90bda.

@gemini-code-assist
Copy link

That's great to hear, @renecannao! I appreciate you addressing the feedback so promptly. Excellent work on this pull request!

@sonarqubecloud
Copy link

sonarqubecloud bot commented Jan 7, 2026

@renecannao renecannao merged commit 4f675ed into v3.0 Jan 7, 2026
14 of 153 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant