From e7ee68dda56028aa9e0e0cead3a0d3832cfb16db Mon Sep 17 00:00:00 2001
From: Rahim Kanji <rahim.kanji@outlook.com>
Date: Fri, 3 Apr 2026 18:10:57 +0500
Subject: [PATCH 1/3] Add SSL/TLS traffic decryption for PostgreSQL backend
 connections (#5281)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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.
---
 deps/Makefile                                |   1 +
 deps/postgresql/sslkeylogfile.patch          |  63 +++
 doc/ssl_keylog/ssl_keylog_developer_guide.md | 425 -----------------
 doc/ssl_keylog/ssl_keylog_user_guide.md      |  51 ++-
 include/proxysql_sslkeylog.h                 |  15 +
 lib/ProxySQL_GloVars.cpp                     |   1 +
 lib/proxysql_sslkeylog.cpp                   |  17 +
 test/tap/groups/groups.json                  |   1 +
 test/tap/tests/pgsql-ssl_keylog-t.cpp        | 458 +++++++++++++++++++
 9 files changed, 599 insertions(+), 433 deletions(-)
 create mode 100644 deps/postgresql/sslkeylogfile.patch
 delete mode 100644 doc/ssl_keylog/ssl_keylog_developer_guide.md
 create mode 100644 test/tap/tests/pgsql-ssl_keylog-t.cpp

diff --git a/deps/Makefile b/deps/Makefile
index bfb9421de..29be815d9 100644
--- a/deps/Makefile
+++ b/deps/Makefile
@@ -370,6 +370,7 @@ postgresql/postgresql/src/interfaces/libpq/libpq.a:
 	cd postgresql/postgresql && patch -p0 < ../fmt_err_msg.patch
 	cd postgresql/postgresql && patch -p0 < ../bind_fmt_text.patch
 	cd postgresql/postgresql && patch -p0 < ../pqsendpipelinesync.patch
+	cd postgresql/postgresql && patch -p0 < ../sslkeylogfile.patch
 ifeq ($(UNAME_S),Darwin)
 	cd postgresql/postgresql && LDFLAGS="-L$$(brew --prefix icu4c)/lib" CPPFLAGS="-I$$(brew --prefix icu4c)/include" PKG_CONFIG_PATH="$$(brew --prefix icu4c)/lib/pkgconfig:$$PKG_CONFIG_PATH" DYLD_LIBRARY_PATH="$(SSL_LDIR):$$DYLD_LIBRARY_PATH" ./configure --with-ssl=openssl --with-includes="$(SSL_IDIR)" --with-libraries="$(SSL_LDIR)" --without-readline --with-icu
 else
diff --git a/deps/postgresql/sslkeylogfile.patch b/deps/postgresql/sslkeylogfile.patch
new file mode 100644
index 000000000..5c4752b6e
--- /dev/null
+++ b/deps/postgresql/sslkeylogfile.patch
@@ -0,0 +1,63 @@
+diff -ruN ../tmp/src/interfaces/libpq/fe-secure-openssl.c ./src/interfaces/libpq/fe-secure-openssl.c
+--- ../tmp/src/interfaces/libpq/fe-secure-openssl.c	2025-08-11 21:06:43.000000000 +0000
++++ ./src/interfaces/libpq/fe-secure-openssl.c	2026-04-03 00:00:00.000000000 +0000
+@@ -97,6 +97,8 @@
+
+ static PQsslKeyPassHook_OpenSSL_type PQsslKeyPassHook = NULL;
+ static int	ssl_protocol_version_to_openssl(const char *protocol);
++
++static PQsslKeyLogCallback_type PQsslKeyLogCB = NULL;
+
+ /* ------------------------------------------------------------ */
+ /*			 Procedures common to all secure sessions			*/
+@@ -972,6 +974,10 @@
+ 	/* Disable old protocol versions */
+ 	SSL_CTX_set_options(SSL_context, SSL_OP_NO_SSLv2 | SSL_OP_NO_SSLv3);
+
++	/* Set SSL keylog callback if configured (for TLS traffic decryption) */
++	if (PQsslKeyLogCB)
++		SSL_CTX_set_keylog_callback(SSL_context, (void(*)(const SSL*, const char*))PQsslKeyLogCB);
++
+ 	/* Set the minimum and maximum protocol versions if necessary */
+ 	if (conn->ssl_min_protocol_version &&
+ 		strlen(conn->ssl_min_protocol_version) != 0)
+@@ -1758,6 +1764,24 @@
+ 	return NULL;
+ }
+
++/*
++ * SSL Key Log callback support
++ *
++ * Global callback for writing TLS secrets to a keylog file.
++ * Follows the same pattern as PQsslKeyPassHook.
++ */
++PQsslKeyLogCallback_type
++PQgetSSLKeyLogCallback(void)
++{
++	return PQsslKeyLogCB;
++}
++
++void
++PQsetSSLKeyLogCallback(PQsslKeyLogCallback_type cb)
++{
++	PQsslKeyLogCB = cb;
++}
++
+ const char *const *
+ PQsslAttributeNames(PGconn *conn)
+ {
+diff -ruN ../tmp/src/interfaces/libpq/libpq-fe.h ./src/interfaces/libpq/libpq-fe.h
+--- ../tmp/src/interfaces/libpq/libpq-fe.h	2025-08-11 21:06:43.000000000 +0000
++++ ./src/interfaces/libpq/libpq-fe.h	2026-04-03 00:00:00.000000000 +0000
+@@ -669,6 +669,11 @@
+ extern void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook);
+ extern int	PQdefaultSSLKeyPassHook_OpenSSL(char *buf, int size, PGconn *conn);
+
++/* Support for SSL key log callback (TLS traffic decryption) */
++typedef void (*PQsslKeyLogCallback_type)(const void *ssl, const char *line);
++extern PQsslKeyLogCallback_type PQgetSSLKeyLogCallback(void);
++extern void PQsetSSLKeyLogCallback(PQsslKeyLogCallback_type cb);
++
+ #ifdef __cplusplus
+ }
+ #endif
diff --git a/doc/ssl_keylog/ssl_keylog_developer_guide.md b/doc/ssl_keylog/ssl_keylog_developer_guide.md
deleted file mode 100644
index 51822579a..000000000
--- a/doc/ssl_keylog/ssl_keylog_developer_guide.md
+++ /dev/null
@@ -1,425 +0,0 @@
-# SSL/TLS Key Log Feature - Developer Guide
-
-## Overview
-
-ProxySQL implements SSL/TLS key logging to enable decryption of encrypted traffic for debugging purposes. This feature writes TLS secrets to a file in the NSS Key Log Format, which can be used by tools like Wireshark to decrypt and analyze TLS traffic.
-
-**PR Reference:** #4236 - "Added support for SSLKEYLOGFILE"
-
----
-
-## Variable Naming Convention
-
-ProxySQL variables belong to **modules**. This is important for understanding how variables are referenced:
-
-| Context | Variable Name | Module |
-|---------|---------------|--------|
-| **Internal code** | `ssl_keylog_file` | Admin |
-| **SQL interface** | `admin-ssl_keylog_file` | Admin (with prefix) |
-| **Config file** | `ssl_keylog_file` | Admin (in `admin_variables` section) |
-
-**Code Location:** `include/proxysql_admin.h` - the variable is defined as `char* ssl_keylog_file` within the admin variables struct.
-
-**SQL Registration:** `lib/ProxySQL_Admin.cpp` - registered as `"ssl_keylog_file"` in the `admin_variables` array.
-
-When users set this variable via SQL, they must use the module prefix:
-```sql
-SET admin-ssl_keylog_file = '/path/to/file.txt';
-```
-
----
-
-## Architecture
-
-### Component Diagram
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│                         ProxySQL Process                            │
-│                                                                      │
-│  ┌────────────────┐         ┌─────────────────────────────────┐   │
-│  | ProxySQL_Admin |────────>|  Global Variables               │   │
-│  |                │         |  .ssl_keylog_file = "/path/..."  │   │
-│  └────────────────┘         └─────────────────────────────────┘   │
-│           │                                                          │
-│           | SET admin-ssl_keylog_file='/path/keylog.txt'           │
-│           v                                                          │
-│  ┌──────────────────────────────────────────────────────────────┐ │
-│  |            proxysql_sslkeylog module                          │ │
-│  │                                                               │ │
-│  │  ┌──────────────┐  ┌──────────────────┐  ┌───────────────┐ │ │
-│  │  | keylog_init  |  | keylog_open     |  | keylog_close  │ │ │
-│  │  └──────────────┘  └──────────────────┘  └───────────────┘ │ │
-│  │                                                               │ │
-│  │  ┌──────────────────────────────────────────────────────────┐│ │
-│  │  | proxysql_keylog_attach_callback(SSL_CTX*)                ││ │
-│  │  |                                                          ││ │
-│  │  |   SSL_CTX_set_keylog_callback(ctx, write_line_callback)  ││ │
-│  │  └──────────────────────────────────────────────────────────┘│ │
-│  └──────────────────────────────────────────────────────────────┘ │
-│                              │                                      │
-│                              │ Callback invoked by OpenSSL         │
-│                              v                                      │
-│  ┌──────────────────────────────────────────────────────────────┐ │
-│  │ proxysql_keylog_write_line_callback(ssl, line)               │ │
-│  │                                                              │ │
-│  │   - Validate line length                                     │ │
-│  │   - Acquire read lock (rwlock)                               │ │
-│  │   - Write to keylog file                                    │ │
-│  │   - Release lock                                            │ │
-│  └──────────────────────────────────────────────────────────────┘ │
-│                              │                                      │
-│                              v                                      │
-│  ┌──────────────────────────────────────────────────────────────┐ │
-│  │           keylog_file_fp (FILE*)                             │ │
-│  │           "/var/log/proxysql/sslkeys.txt"                    │ │
-│  │                                                              │ │
-│  │   CLIENT_RANDOM 3a4b5c... <48-byte-secret>                   │ │
-│  │   CLIENT_HANDSHAKE_TRAFFIC_SECRET 3a4b... <32-byte-secret>   │ │
-│  │   SERVER_HANDSHAKE_TRAFFIC_SECRET 3a4b... <32-byte-secret>   │ │
-│  └──────────────────────────────────────────────────────────────┘ │
-│                                                                      │
-└──────────────────────────────────────────────────────────────────────┘
-```
-
-### Thread Safety Model
-
-The keylog subsystem uses a **pthread read-write lock** for concurrent access.
-
-**Key Points:**
-- Multiple threads can write to the keylog file simultaneously during TLS handshakes
-- File rotation (open/close) acquires exclusive lock
-- Double-checked locking in `write_line_callback()` for performance
-
----
-
-## NSS Key Log Format
-
-### File Structure
-
-Each line in the keylog file has the following format:
-
-```
-<LABEL> <ClientRandom> <Secret>\n
-```
-
-### Label Types
-
-| Label | TLS Version | Description | Secret Size |
-|-------|-------------|-------------|-------------|
-| `CLIENT_RANDOM` | TLS 1.2 and earlier | Master secret | 48 bytes |
-| `CLIENT_HANDSHAKE_TRAFFIC_SECRET` | TLS 1.3 | Client handshake traffic secret | 32 or 48 bytes |
-| `SERVER_HANDSHAKE_TRAFFIC_SECRET` | TLS 1.3 | Server handshake traffic secret | 32 or 48 bytes |
-| `CLIENT_TRAFFIC_SECRET_0` | TLS 1.3 | Client application data secret N | 32 or 48 bytes |
-| `SERVER_TRAFFIC_SECRET_0` | TLS 1.3 | Server application data secret N | 32 or 48 bytes |
-
-### Example Keylog File
-
-```
-# TLS 1.2 connection
-CLIENT_RANDOM 3a4b5c6d7e8f... 48_byte_master_secret_here...
-
-# TLS 1.3 connection
-CLIENT_HANDSHAKE_TRAFFIC_SECRET 3a4b5c6d7e8f... 32_byte_secret_here...
-SERVER_HANDSHAKE_TRAFFIC_SECRET 3a4b5c6d7e8f... 32_byte_secret_here...
-CLIENT_TRAFFIC_SECRET_0 3a4b5c6d7e8f... 32_byte_secret_here...
-SERVER_TRAFFIC_SECRET_0 3a4b5c6d7e8f... 32_byte_secret_here...
-```
-
----
-
-## API Reference
-
-### Public Functions
-
-#### `proxysql_keylog_init()`
-
-```c
-void proxysql_keylog_init();
-```
-
-**Purpose:** Initialize the keylog subsystem
-
-**Called from:** `proxysql_global.cpp` during startup
-
-**Thread-safety:** Safe (single-threaded initialization only)
-
----
-
-#### `proxysql_keylog_open(const char* keylog_file)`
-
-```c
-bool proxysql_keylog_open(const char* keylog_file);
-```
-
-**Purpose:** Open/create the keylog file
-
-**Parameters:**
-- `keylog_file`: Path to the keylog file
-
-**Returns:** `true` on success, `false` on failure
-
-**Behavior:**
-- Opens file in append mode with line buffering (4096 bytes)
-- Closes existing file if open (supports rotation)
-- Acquires write lock for thread safety
-
-**Called from:**
-- `ProxySQL_Admin::set_variable()` when `ssl_keylog_file` is set
-- `ProxySQL_Admin::flush_logs()` for log rotation
-
----
-
-#### `proxysql_keylog_close(bool lock = true)`
-
-```c
-void proxysql_keylog_close(bool lock = true);
-```
-
-**Purpose:** Close the keylog file
-
-**Parameters:**
-- `lock`: If `true`, acquires write lock before closing
-
-**Behavior:**
-- Closes the file if open
-- Sets `keylog_file_fp` to `NULL`
-
----
-
-#### `proxysql_keylog_attach_callback(SSL_CTX* ssl_ctx)`
-
-```c
-void proxysql_keylog_attach_callback(SSL_CTX* ssl_ctx);
-```
-
-**Purpose:** Attach keylog callback to an SSL context
-
-**Parameters:**
-- `ssl_ctx`: The SSL context to attach to
-
-**Behavior:**
-- Idempotent: only attaches if no callback already registered
-- Uses `SSL_CTX_set_keylog_callback()` (OpenSSL 1.1.1+)
-
-**Called from:**
-- `MySQL_Session::handler()` for frontend MySQL connections
-- `PgSQL_Session::handler()` for frontend PostgreSQL connections
-
----
-
-#### `proxysql_keylog_write_line_callback(const SSL* ssl, const char* line)`
-
-```c
-void proxysql_keylog_write_line_callback(const SSL* ssl, const char* line);
-```
-
-**Purpose:** OpenSSL callback invoked during TLS handshake
-
-**Parameters:**
-- `ssl`: The SSL connection (unused)
-- `line`: The keylog line generated by OpenSSL (no newline)
-
-**Behavior:**
-- Validates line length (max 254 bytes)
-- Ensures newline termination
-- Acquires read lock and writes to file
-- Uses double-checked locking for performance
-
-**Called by:** OpenSSL automatically during TLS handshake
-
----
-
-## Configuration Variable
-
-### `ssl_keylog_file` (internal name)
-
-**Module:** Admin
-
-**Internal Name:** `ssl_keylog_file`
-
-**SQL Interface Name:** `admin-ssl_keylog_file`
-
-**Type:** String (path)
-
-**Default:** `""` (empty string = disabled)
-
-**Runtime Configurable:** Yes
-
-**Path Resolution:**
-- Absolute path (starts with `/`): used as-is
-- Relative path: resolved relative to ProxySQL data directory
-- Empty string: disables key logging
-
-**SQL Usage:**
-```sql
--- Enable key logging
-SET admin-ssl_keylog_file = '/var/log/proxysql/sslkeys.txt';
-
--- Disable key logging
-SET admin-ssl_keylog_file = '';
-
--- Apply to runtime
-LOAD ADMIN VARIABLES TO RUNTIME;
-```
-
-**Config File Usage:**
-```ini
-admin_variables=
-{
-    ssl_keylog_file='/var/log/proxysql/sslkeys.txt'
-}
-```
-
----
-
-## Integration Points
-
-### 1. Variable Definition
-
-**File:** `include/proxysql_admin.h`
-
-```cpp
-struct {
-    // ...
-    char* ssl_keylog_file;  // Path to keylog file
-} variables;
-```
-
-### 2. Variable Registration
-
-**File:** `lib/ProxySQL_Admin.cpp`
-
-```cpp
-{ (char *)"ssl_keylog_file", ... }
-```
-
-### 3. Runtime Variable Setter
-
-**File:** `lib/ProxySQL_Admin.cpp:set_variable()`
-
-```cpp
-if (!strcasecmp(name, "ssl_keylog_file")) {
-    // Handle absolute vs relative paths
-    // Open file or validate path
-    // Set GloVars.global.ssl_keylog_enabled
-}
-```
-
-### 4. Log Rotation
-
-**File:** `lib/ProxySQL_Admin.cpp:flush_logs()`
-
-```cpp
-void ProxySQL_Admin::flush_logs() {
-    // ...
-    proxysql_keylog_close();  // Close current file
-    proxysql_keylog_open(ssl_keylog_file);  // Reopen
-}
-```
-
-### 5. SSL Context Integration
-
-**Files:**
-- `lib/MySQL_Session.cpp`
-- `lib/PgSQL_Session.cpp`
-
-```cpp
-proxysql_keylog_attach_callback(GloVars.get_SSL_ctx());
-```
-
----
-
-## Security Considerations
-
-### WARNING: Critical Security Implications
-
-The keylog file contains **cryptographic secrets** that can decrypt ALL TLS traffic:
-
-1. **What the file contains:**
-   - TLS master secrets (TLS 1.2)
-   - Traffic encryption keys (TLS 1.3)
-   - Enough to decrypt past, present, and future connections
-
-2. **Attack scenarios if compromised:**
-   - Decryption of captured network traffic, exposing all plaintext data, including credentials, queries, and results.
-
-3. **Recommended safeguards:**
-   - **File permissions:** `0600` (owner read/write only)
-   - **Directory permissions:** `0700` (owner access only)
-   - **Enable only for debugging:** Disable in production
-   - **Rotate regularly:** `PROXYSQL FLUSH LOGS`
-   - **Secure deletion:** Shred file before deletion
-
-### Code Review Checklist
-
-When reviewing changes to this module:
-
-- [ ] File permissions are set correctly
-- [ ] Path validation prevents directory traversal
-- [ ] Lock acquisition is correct (rdlock vs wrlock)
-- [ ] Double-checked locking is properly implemented
-- [ ] No sensitive data in logs/error messages
-- [ ] Proper cleanup on error conditions
-
----
-
-## Testing
-
-### Unit Test Structure
-
-**File:** `test/tap/tests/test_auth_methods-t.cpp`
-
-```cpp
-void ssl_keylog_callback(SSL*, const char* line) {
-    // Verify line format
-    // Verify file contents
-}
-
-// Test callback registration
-mysql_options(proxy, MARIADB_OPT_SSL_KEYLOG_CALLBACK, ...);
-```
-
-### Manual Testing
-
-1. **Enable key logging:**
-
-```bash
-mysql -h 127.0.0.1 -P 6032 -u admin -padmin -e "SET admin-ssl_keylog_file='/tmp/keylog.txt'; LOAD ADMIN VARIABLES TO RUNTIME;"
-```
-
-2. **Create TLS connection:**
-
-```bash
-mysql -h 127.0.0.1 -P 6033 -u user -ppass --ssl
-```
-
-3. **Verify keylog file:**
-
-```bash
-cat /tmp/keylog.txt
-# Should see CLIENT_RANDOM or TRAFFIC_SECRET lines
-```
-
-4. **Configure Wireshark:**
-   - Edit → Preferences → Protocols → TLS
-   - Set "(Pre)-Master-Secret log filename" to `/tmp/keylog.txt`
-   - Decrypt TLS traffic in Wireshark
-
----
-
-## Performance Considerations
-
-1. **Line buffering:** 4096 bytes minimizes syscalls
-2. **Read-write lock:** Allows concurrent writes during handshakes
-3. **Double-checked locking:** Avoids lock acquisition when disabled
-4. **File mode:** Append mode minimizes disk seeks
-
----
-
-## References
-
-- [NSS Key Log Format](https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format)
-- [Wireshark TLS Decryption](https://wiki.wireshark.org/TLS#TLS_Decryption)
-- [OpenSSL SSL_CTX_set_keylog_callback](https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_keylog_callback.html)
-- [PR #4236](https://github.com/sysown/proxysql/pull/4236)
diff --git a/doc/ssl_keylog/ssl_keylog_user_guide.md b/doc/ssl_keylog/ssl_keylog_user_guide.md
index 92282428e..c6ac5204d 100644
--- a/doc/ssl_keylog/ssl_keylog_user_guide.md
+++ b/doc/ssl_keylog/ssl_keylog_user_guide.md
@@ -8,8 +8,8 @@ SSL/TLS key logging is a debugging feature that allows ProxySQL to write TLS enc
 
 This feature is primarily useful for:
 
-- **Debugging TLS connection issues** between clients and ProxySQL
-- **Analyzing encrypted traffic** without modifying application code
+- **Debugging TLS connection issues** between clients and ProxySQL, or between ProxySQL and MySQL/PostgreSQL backends
+- **Analyzing encrypted backend traffic** to MySQL and PostgreSQL servers without modifying application code
 - **Troubleshooting TLS handshake problems**
 - **Performance analysis** of TLS connections
 - **Security auditing** of TLS configurations
@@ -222,11 +222,16 @@ In production environments, you typically don't run Wireshark directly on the se
 On the ProxySQL server, capture network traffic to a pcap file:
 
 ```bash
-# Capture on the interface ProxySQL is listening on (e.g., eth0)
-# Replace 6033 with your ProxySQL MySQL port
+# Capture MySQL frontend traffic (client → ProxySQL)
 sudo tcpdump -i eth0 -w /tmp/proxysql_debug.pcap port 6033
 
-# Or capture traffic between specific hosts
+# Capture PgSQL frontend traffic (client → ProxySQL)
+sudo tcpdump -i eth0 -w /tmp/proxysql_debug.pcap port 6133
+
+# Capture PgSQL backend traffic (ProxySQL → PostgreSQL server)
+sudo tcpdump -i eth0 -w /tmp/proxysql_debug.pcap port 5432
+
+# Capture traffic between specific hosts
 sudo tcpdump -i eth0 -w /tmp/proxysql_debug.pcap host client_ip and host proxysql_ip
 
 # Run for a specific duration
@@ -271,6 +276,9 @@ On your analysis system with Wireshark installed:
    # Show only MySQL packets
    mysql
    
+   # Show only PostgreSQL packets
+   pgsql
+   
    # Show TLS handshake
    tls.handshake.type == 1
    
@@ -407,10 +415,20 @@ mysql_variables=
 **Solutions:**
 1. Verify TLS is actually being used:
    ```sql
-   -- Check if connections are using TLS
+   -- Check MySQL backend connections
    SELECT * FROM stats_mysql_connection_pool;
+   -- Check PgSQL backend connections
+   SELECT * FROM stats_pgsql_connection_pool;
+   ```
+2. For PgSQL backends, ensure `use_ssl=1` is set on the servers:
+   ```sql
+   SELECT hostgroup_id, hostname, port, use_ssl FROM pgsql_servers;
+   ```
+3. Keylog entries are only written during **new** SSL handshakes. Existing pooled connections won't generate entries. To force new handshakes, reload servers:
+   ```sql
+   LOAD PGSQL SERVERS TO RUNTIME;
    ```
-2. Make sure clients are connecting with SSL/TLS
+4. Make sure clients are connecting with SSL/TLS
 3. Check that `admin-ssl_keylog_file` is loaded into runtime:
    ```sql
    LOAD ADMIN VARIABLES TO RUNTIME;
@@ -476,9 +494,26 @@ sudo tcpdump -i eth0 -w /tmp/capture.pcap port 6033
 
 ---
 
+## Supported Connection Types
+
+When `admin-ssl_keylog_file` is configured, TLS secrets are captured from **all** SSL/TLS connection types:
+
+| Connection Type | Direction | Protocol |
+|----------------|-----------|----------|
+| Frontend (client) | Client → ProxySQL | MySQL |
+| Frontend (client) | Client → ProxySQL | PostgreSQL |
+| Backend | ProxySQL → MySQL server | MySQL |
+| Backend | ProxySQL → PostgreSQL server | PostgreSQL |
+| Monitor | ProxySQL → MySQL server | MySQL |
+| Monitor | ProxySQL → PostgreSQL server | PostgreSQL |
+| Cluster | ProxySQL → ProxySQL peer | MySQL |
+
+No additional configuration is needed per connection type — the single `admin-ssl_keylog_file` variable enables logging for all types.
+
+---
+
 ## Additional Resources
 
-- **Developer Documentation:** See `ssl_keylog_developer_guide.md` for implementation details
 - **NSS Key Log Format:** https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format
 - **Wireshark TLS Decryption:** https://wiki.wireshark.org/TLS
 - **tshark Manual:** `man tshark` or https://www.wireshark.org/docs/man-pages/tshark.html
diff --git a/include/proxysql_sslkeylog.h b/include/proxysql_sslkeylog.h
index 5ec1793b0..21c5d15e9 100644
--- a/include/proxysql_sslkeylog.h
+++ b/include/proxysql_sslkeylog.h
@@ -103,4 +103,19 @@ void proxysql_keylog_attach_callback(SSL_CTX* ssl_ctx);
  */
 void proxysql_keylog_write_line_callback(const SSL* ssl, const char* line);
 
+/**
+ * @brief Register the ProxySQL keylog callback with libpq
+ *
+ * Sets the global SSL keylog callback in libpq so that all PostgreSQL
+ * backend connections (regular, monitor, kill, harvester) will write
+ * TLS secrets to the keylog file.
+ *
+ * Must be called once at ProxySQL startup after proxysql_keylog_init().
+ *
+ * Thread-safety: Safe (should only be called during single-threaded initialization)
+ *
+ * @see PQsetSSLKeyLogCallback
+ */
+void proxysql_keylog_set_pgsql_callback();
+
 #endif // __PROXYSQL_SSLKEYLOG_H
diff --git a/lib/ProxySQL_GloVars.cpp b/lib/ProxySQL_GloVars.cpp
index e6f271246..bd119cbc4 100644
--- a/lib/ProxySQL_GloVars.cpp
+++ b/lib/ProxySQL_GloVars.cpp
@@ -487,6 +487,7 @@ void ProxySQL_GlobalVariables::process_opts_pre() {
 	init_coredump_struct();
 
 	proxysql_keylog_init();
+	proxysql_keylog_set_pgsql_callback();
 };
 
 void ProxySQL_GlobalVariables::process_opts_post() {
diff --git a/lib/proxysql_sslkeylog.cpp b/lib/proxysql_sslkeylog.cpp
index 18281e950..7b4041dcd 100644
--- a/lib/proxysql_sslkeylog.cpp
+++ b/lib/proxysql_sslkeylog.cpp
@@ -23,6 +23,7 @@
  */
 
 #include "proxysql_sslkeylog.h"
+#include "libpq-fe.h"
 
 // NSS Key Log Format reference:
 // https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format
@@ -229,3 +230,19 @@ void proxysql_keylog_attach_callback(SSL_CTX* ssl_ctx) {
 	    SSL_CTX_set_keylog_callback(ssl_ctx, proxysql_keylog_write_line_callback);
     }
 }
+
+/**
+ * @brief Register the ProxySQL keylog callback with libpq
+ *
+ * Sets the global SSL keylog callback in libpq using PQsetSSLKeyLogCallback().
+ * This ensures all PostgreSQL backend connections write TLS secrets to the
+ * keylog file, matching the behavior already implemented for MySQL backends
+ * via MARIADB_OPT_SSL_KEYLOG_CALLBACK.
+ *
+ * The callback is set globally (not per-connection) because libpq creates
+ * a new SSL_CTX per connection internally. A global callback ensures coverage
+ * for both async (PQconnectStart) and sync (PQconnectdb) connection paths.
+ */
+void proxysql_keylog_set_pgsql_callback() {
+    PQsetSSLKeyLogCallback((PQsslKeyLogCallback_type)proxysql_keylog_write_line_callback);
+}
diff --git a/test/tap/groups/groups.json b/test/tap/groups/groups.json
index c0c5ab6c1..2aaa9fc6b 100644
--- a/test/tap/groups/groups.json
+++ b/test/tap/groups/groups.json
@@ -145,6 +145,7 @@
   "pgsql-reg_test_5415_copy_error_recovery-t" : [ "legacy-g4","mysql-auto_increment_delay_multiplex=0-g4","mysql-multiplexing=false-g4","mysql-query_digests=0-g4","mysql-query_digests_keep_comment=1-g4" ],
   "pgsql-set_parameter_validation_test-t" : [ "legacy-g1","mysql-auto_increment_delay_multiplex=0-g1","mysql-multiplexing=false-g1","mysql-query_digests=0-g1","mysql-query_digests_keep_comment=1-g1" ],
   "pgsql-set_statement_test-t" : [ "legacy-g4","mysql-auto_increment_delay_multiplex=0-g4","mysql-multiplexing=false-g4","mysql-query_digests=0-g4","mysql-query_digests_keep_comment=1-g4" ],
+  "pgsql-ssl_keylog-t" : [ "legacy-g4","mysql-auto_increment_delay_multiplex=0-g4","mysql-multiplexing=false-g4","mysql-query_digests=0-g4","mysql-query_digests_keep_comment=1-g4" ],
   "pgsql-test_malformed_packet-t" : [ "legacy-g4","mysql-auto_increment_delay_multiplex=0-g4","mysql-multiplexing=false-g4","mysql-query_digests=0-g4","mysql-query_digests_keep_comment=1-g4" ],
   "pgsql-transaction_state_comprehensive-t" : [ "legacy-g4","mysql-auto_increment_delay_multiplex=0-g4","mysql-multiplexing=false-g4","mysql-query_digests=0-g4","mysql-query_digests_keep_comment=1-g4" ],
   "pgsql-transaction_variable_state_tracking-t" : [ "legacy-g4","mysql-auto_increment_delay_multiplex=0-g4","mysql-multiplexing=false-g4","mysql-query_digests=0-g4","mysql-query_digests_keep_comment=1-g4" ],
diff --git a/test/tap/tests/pgsql-ssl_keylog-t.cpp b/test/tap/tests/pgsql-ssl_keylog-t.cpp
new file mode 100644
index 000000000..89939a871
--- /dev/null
+++ b/test/tap/tests/pgsql-ssl_keylog-t.cpp
@@ -0,0 +1,458 @@
+/**
+ * @file pgsql-ssl_keylog-t.cpp
+ * @brief Integration test for PgSQL backend SSL keylog support.
+ *
+ * @details Validates that TLS secrets from PostgreSQL backend SSL connections
+ *          are written to the keylog file when admin-ssl_keylog_file is set.
+ *
+ *          ProxySQL patches libpq with a global SSL keylog callback
+ *          (PQsetSSLKeyLogCallback). When admin-ssl_keylog_file is set, ALL
+ *          TLS connections write secrets to the keylog file in NSS Key Log Format.
+ *
+ * Test cases:
+ *   1. Basic keylog creation         — set admin-ssl_keylog_file, make PgSQL SSL connection,
+ *                                      verify file is non-empty
+ *   2. NSS format validation         — parse keylog lines, verify regex match for NSS Key Log Format
+ *   3. TLS version label check       — verify keylog contains TLS 1.2 or 1.3 secret labels
+ *   4. Concurrent connections        — 8 threads making PgSQL SSL connections, verify no corruption
+ *   5. Disable keylog                — set empty, make new connections, verify no new lines
+ *   6. Log rotation                  — PROXYSQL FLUSH LOGS, verify new secrets appended
+ *   7. Monitor SSL keylog            — enable use_ssl=1, wait for monitor, verify keylog entries
+ *   8. Non-SSL no keylog             — use_ssl=0, verify no new entries
+ *   9. Invalid keylog path           — set /nonexistent/dir/file, verify graceful handling
+ *
+ * Test infrastructure: docker-pgsql16-single (PgSQL backend with SSL enabled)
+ * Admin connection: PgSQL protocol on pgsql_admin_host:pgsql_admin_port
+ */
+
+#include <unistd.h>
+#include <string>
+#include <sstream>
+#include <fstream>
+#include <thread>
+#include <vector>
+#include <atomic>
+#include <regex>
+#include <cstdio>
+#include <cstring>
+
+#include "libpq-fe.h"
+#include "command_line.h"
+#include "tap.h"
+#include "utils.h"
+
+CommandLine cl;
+
+using PGConnPtr = std::unique_ptr<PGconn, decltype(&PQfinish)>;
+
+static const char* KEYLOG_PATH = "/tmp/pgsql_ssl_keylog_test.log";
+
+// ============================================================
+// Helper: open PgSQL admin connection
+// ============================================================
+static PGConnPtr open_admin() {
+    std::stringstream ss;
+    ss << "host=" << cl.pgsql_admin_host
+       << " port=" << cl.pgsql_admin_port
+       << " user=" << cl.admin_username
+       << " password=" << cl.admin_password
+       << " sslmode=disable";
+    PGconn* conn = PQconnectdb(ss.str().c_str());
+    if (PQstatus(conn) != CONNECTION_OK) {
+        fprintf(stderr, "Admin connection failed: %s", PQerrorMessage(conn));
+        PQfinish(conn);
+        return PGConnPtr(nullptr, &PQfinish);
+    }
+    return PGConnPtr(conn, &PQfinish);
+}
+
+// ============================================================
+// Helper: run admin SQL, return true on success
+// ============================================================
+static bool admin_exec(PGconn* admin, const char* sql) {
+    PGresult* res = PQexec(admin, sql);
+    ExecStatusType st = PQresultStatus(res);
+    bool ok = (st == PGRES_COMMAND_OK || st == PGRES_TUPLES_OK);
+    if (!ok) {
+        diag("Admin query failed: '%s' err='%s'", sql, PQerrorMessage(admin));
+    }
+    PQclear(res);
+    return ok;
+}
+
+// ============================================================
+// Helper: run admin SQL and return first column of first row
+// ============================================================
+static std::string admin_query_value(PGconn* admin, const char* sql) {
+    std::string result;
+    PGresult* res = PQexec(admin, sql);
+    if (PQresultStatus(res) == PGRES_TUPLES_OK && PQntuples(res) > 0) {
+        const char* val = PQgetvalue(res, 0, 0);
+        if (val) result = val;
+    } else {
+        diag("Admin query failed: '%s' err='%s'", sql, PQerrorMessage(admin));
+    }
+    PQclear(res);
+    return result;
+}
+
+// ============================================================
+// Helper: set admin-ssl_keylog_file and load to runtime
+// ============================================================
+static bool set_keylog_file(PGconn* admin, const char* path) {
+    std::string sql = "SET admin-ssl_keylog_file='";
+    if (path) sql += path;
+    sql += "'";
+    if (!admin_exec(admin, sql.c_str())) return false;
+    return admin_exec(admin, "LOAD ADMIN VARIABLES TO RUNTIME");
+}
+
+// ============================================================
+// Helper: make a PgSQL backend connection with SSL
+// ============================================================
+static PGConnPtr make_pgsql_ssl_conn() {
+    std::stringstream ss;
+    ss << "host=" << cl.pgsql_host
+       << " port=" << cl.pgsql_port
+       << " user=" << cl.pgsql_root_username
+       << " password=" << cl.pgsql_root_password
+       << " sslmode=require";
+    PGconn* conn = PQconnectdb(ss.str().c_str());
+    return PGConnPtr(conn, &PQfinish);
+}
+
+// ============================================================
+// Helper: make a PgSQL backend connection without SSL
+// ============================================================
+static PGConnPtr make_pgsql_nossl_conn() {
+    std::stringstream ss;
+    ss << "host=" << cl.pgsql_host
+       << " port=" << cl.pgsql_port
+       << " user=" << cl.pgsql_root_username
+       << " password=" << cl.pgsql_root_password
+       << " sslmode=disable";
+    PGconn* conn = PQconnectdb(ss.str().c_str());
+    return PGConnPtr(conn, &PQfinish);
+}
+
+// ============================================================
+// Helper: count non-empty lines in a file
+// ============================================================
+static long count_file_lines(const char* path) {
+    std::ifstream f(path);
+    if (!f.is_open()) return -1;
+    long n = 0;
+    std::string line;
+    while (std::getline(f, line)) {
+        if (!line.empty()) ++n;
+    }
+    return n;
+}
+
+// ============================================================
+// Helper: get file size in bytes, returns -1 if file doesn't exist
+// ============================================================
+static long file_size(const char* path) {
+    std::ifstream f(path, std::ios::ate | std::ios::binary);
+    if (!f.is_open()) return -1;
+    return (long)f.tellg();
+}
+
+// ============================================================
+// Helper: check whether any line in the file matches a regex
+// ============================================================
+static bool file_has_regex_match(const char* path, const std::regex& re) {
+    std::ifstream f(path);
+    if (!f.is_open()) return false;
+    std::string line;
+    while (std::getline(f, line)) {
+        if (std::regex_search(line, re)) return true;
+    }
+    return false;
+}
+
+// ============================================================
+// Helper: set pgsql_servers use_ssl and reload
+// ============================================================
+static bool set_pgsql_use_ssl(PGconn* admin, int value) {
+    std::string sql = "UPDATE pgsql_servers SET use_ssl=" + std::to_string(value);
+    if (!admin_exec(admin, sql.c_str())) return false;
+    return admin_exec(admin, "LOAD PGSQL SERVERS TO RUNTIME");
+}
+
+// ============================================================
+// Helper: get pgsql-monitor_connect_interval (ms)
+// ============================================================
+static long get_monitor_interval(PGconn* admin) {
+    std::string v = admin_query_value(admin,
+        "SELECT Variable_Value FROM global_variables "
+        "WHERE Variable_Name='pgsql-monitor_connect_interval'");
+    return v.empty() ? 1000 : atol(v.c_str());
+}
+
+int main(int argc, char** argv) {
+    plan(9);
+
+    if (cl.getEnv()) {
+        diag("Failed to get required environment variables");
+        return exit_status();
+    }
+
+    // Remove any leftover keylog file from a prior run
+    ::remove(KEYLOG_PATH);
+
+    // Open PgSQL admin connection
+    auto admin_conn = open_admin();
+    if (!admin_conn) {
+        BAIL_OUT("Admin connection failed — cannot continue");
+        return exit_status();
+    }
+    PGconn* admin = admin_conn.get();
+    diag("PgSQL admin connected to %s:%d", cl.pgsql_admin_host, cl.pgsql_admin_port);
+
+    // Save original keylog file setting so we can restore it at the end
+    std::string original_keylog = admin_query_value(admin,
+        "SELECT Variable_Value FROM global_variables "
+        "WHERE Variable_Name='admin-ssl_keylog_file'");
+    diag("Original admin-ssl_keylog_file='%s'", original_keylog.c_str());
+
+    // ================================================================
+    // Test 1: Basic keylog creation
+    // ================================================================
+    diag("---- Test 1: Basic keylog creation ----");
+
+    bool set_ok = set_keylog_file(admin, KEYLOG_PATH);
+    diag("Set admin-ssl_keylog_file='%s' result=%s", KEYLOG_PATH, set_ok ? "ok" : "FAIL");
+
+    if (set_ok) {
+        auto conn1 = make_pgsql_ssl_conn();
+        if (PQstatus(conn1.get()) != CONNECTION_OK) {
+            diag("PgSQL SSL connection failed: %s", PQerrorMessage(conn1.get()));
+        }
+        usleep(100000);
+    }
+
+    long sz = file_size(KEYLOG_PATH);
+    diag("Keylog file size after SSL PgSQL connection: %ld bytes", sz);
+    ok(set_ok && sz > 0,
+        "Test 1: Keylog file is non-empty after PgSQL SSL connection (size=%ld)", sz);
+
+    // ================================================================
+    // Test 2: NSS format validation
+    // ================================================================
+    diag("---- Test 2: NSS Key Log Format validation ----");
+
+    std::regex nss_re(R"(^[A-Z_]+ [0-9a-fA-F]{64} [0-9a-fA-F]+$)");
+    bool has_valid_line = file_has_regex_match(KEYLOG_PATH, nss_re);
+    ok(has_valid_line,
+        "Test 2: Keylog file contains valid NSS Key Log Format lines");
+
+    // ================================================================
+    // Test 3: TLS version label check
+    // ================================================================
+    diag("---- Test 3: TLS 1.2/1.3 secret label check ----");
+
+    std::regex tls_label_re(
+        R"(^(CLIENT_RANDOM|CLIENT_HANDSHAKE_TRAFFIC_SECRET|SERVER_HANDSHAKE_TRAFFIC_SECRET|)"
+        R"(CLIENT_TRAFFIC_SECRET_\d+|SERVER_TRAFFIC_SECRET_\d+) )");
+    bool has_tls_label = file_has_regex_match(KEYLOG_PATH, tls_label_re);
+    ok(has_tls_label,
+        "Test 3: Keylog contains TLS 1.2 CLIENT_RANDOM or TLS 1.3 traffic secret labels");
+
+    // ================================================================
+    // Test 4: Concurrent connections — no corruption
+    // ================================================================
+    diag("---- Test 4: Concurrent SSL connections ----");
+
+    long lines_before = count_file_lines(KEYLOG_PATH);
+    diag("Lines before concurrent test: %ld", lines_before);
+
+    const int NUM_THREADS = 8;
+    std::atomic<int> conn_ok_count{0};
+    std::vector<std::thread> threads;
+    threads.reserve(NUM_THREADS);
+
+    for (int i = 0; i < NUM_THREADS; ++i) {
+        threads.emplace_back([&conn_ok_count]() {
+            auto c = make_pgsql_ssl_conn();
+            if (PQstatus(c.get()) == CONNECTION_OK) {
+                ++conn_ok_count;
+            }
+        });
+    }
+    for (auto& t : threads) t.join();
+    usleep(200000);
+
+    long lines_after = count_file_lines(KEYLOG_PATH);
+    diag("Lines after concurrent test: %ld (conn_ok=%d)", lines_after, (int)conn_ok_count);
+
+    bool all_valid = true;
+    {
+        std::ifstream f(KEYLOG_PATH);
+        std::string line;
+        while (std::getline(f, line)) {
+            if (line.empty()) continue;
+            if (!std::regex_search(line, nss_re)) {
+                diag("Corrupt/unexpected line: '%s'", line.c_str());
+                all_valid = false;
+            }
+        }
+    }
+    ok(all_valid && lines_after > lines_before,
+        "Test 4: Concurrent SSL connections produced valid keylog lines without corruption "
+        "(before=%ld after=%ld)", lines_before, lines_after);
+
+    // ================================================================
+    // Test 5: Disable keylog — no new lines after clearing
+    // ================================================================
+    diag("---- Test 5: Disable keylog ----");
+
+    set_keylog_file(admin, "");
+    usleep(50000);
+
+    long lines_disabled = count_file_lines(KEYLOG_PATH);
+    diag("Lines before disable connection: %ld", lines_disabled);
+
+    for (int i = 0; i < 3; ++i) {
+        auto c = make_pgsql_ssl_conn();
+        (void)c;
+    }
+    usleep(200000);
+
+    long lines_after_disable = count_file_lines(KEYLOG_PATH);
+    diag("Lines after connections with keylog disabled: %ld", lines_after_disable);
+    ok(lines_after_disable == lines_disabled,
+        "Test 5: No new keylog lines written after disabling keylog "
+        "(before=%ld after=%ld)", lines_disabled, lines_after_disable);
+
+    // ================================================================
+    // Test 6: Log rotation — PROXYSQL FLUSH LOGS appends new secrets
+    // ================================================================
+    diag("---- Test 6: Log rotation via PROXYSQL FLUSH LOGS ----");
+
+    set_keylog_file(admin, KEYLOG_PATH);
+    usleep(50000);
+
+    {
+        auto c = make_pgsql_ssl_conn();
+        (void)c;
+    }
+    usleep(100000);
+
+    long lines_pre_flush = count_file_lines(KEYLOG_PATH);
+    diag("Lines before PROXYSQL FLUSH LOGS: %ld", lines_pre_flush);
+
+    bool flush_ok = admin_exec(admin, "PROXYSQL FLUSH LOGS");
+    diag("PROXYSQL FLUSH LOGS result=%s", flush_ok ? "ok" : "FAIL");
+
+    {
+        auto c = make_pgsql_ssl_conn();
+        (void)c;
+    }
+    usleep(100000);
+
+    long lines_post_flush = count_file_lines(KEYLOG_PATH);
+    diag("Lines after PROXYSQL FLUSH LOGS + new connection: %ld", lines_post_flush);
+    ok(flush_ok && lines_post_flush > lines_pre_flush,
+        "Test 6: New keylog secrets appended after PROXYSQL FLUSH LOGS "
+        "(before=%ld after=%ld)", lines_pre_flush, lines_post_flush);
+
+    // ================================================================
+    // Test 7: Monitor SSL keylog — enable use_ssl, wait, verify entries
+    // ================================================================
+    diag("---- Test 7: Monitor SSL keylog ----");
+
+    ::remove(KEYLOG_PATH);
+    set_keylog_file(admin, KEYLOG_PATH);
+    usleep(50000);
+
+    long lines_before_monitor = count_file_lines(KEYLOG_PATH);
+    diag("Lines before enabling monitor SSL: %ld", lines_before_monitor);
+
+    long monitor_interval_ms = get_monitor_interval(admin);
+    diag("pgsql-monitor_connect_interval=%ld ms", monitor_interval_ms);
+
+    bool use_ssl_ok = set_pgsql_use_ssl(admin, 1);
+    diag("Set pgsql_servers use_ssl=1 result=%s", use_ssl_ok ? "ok" : "FAIL");
+
+    useconds_t wait_us = (useconds_t)(monitor_interval_ms * 2 * 1000);
+    if (wait_us > 10000000) wait_us = 10000000;
+    diag("Waiting %u us for monitor cycles...", wait_us);
+    usleep(wait_us);
+
+    long lines_after_monitor = count_file_lines(KEYLOG_PATH);
+    diag("Lines after monitor SSL cycles: %ld", lines_after_monitor);
+    ok(use_ssl_ok && lines_after_monitor > lines_before_monitor,
+        "Test 7: Monitor SSL connections write keylog entries "
+        "(before=%ld after=%ld)", lines_before_monitor, lines_after_monitor);
+
+    set_pgsql_use_ssl(admin, 0);
+    usleep(50000);
+
+    // ================================================================
+    // Test 8: Non-SSL PgSQL connection — no keylog entries added
+    // ================================================================
+    diag("---- Test 8: Non-SSL connection produces no keylog entries ----");
+
+    admin_exec(admin, "SET pgsql-monitor_enabled='false'");
+    admin_exec(admin, "LOAD PGSQL VARIABLES TO RUNTIME");
+    usleep(500000);
+
+    ::remove(KEYLOG_PATH);
+    set_keylog_file(admin, KEYLOG_PATH);
+    usleep(50000);
+
+    long lines_nossl_before = count_file_lines(KEYLOG_PATH);
+    diag("Lines before non-SSL connections: %ld", lines_nossl_before);
+
+    for (int i = 0; i < 3; ++i) {
+        auto c = make_pgsql_nossl_conn();
+        if (PQstatus(c.get()) != CONNECTION_OK) {
+            diag("Non-SSL PgSQL connection failed (may be expected): %s",
+                 PQerrorMessage(c.get()));
+        }
+    }
+    usleep(200000);
+
+    long lines_nossl_after = count_file_lines(KEYLOG_PATH);
+    diag("Lines after non-SSL connections: %ld", lines_nossl_after);
+    ok(lines_nossl_after == lines_nossl_before,
+        "Test 8: Non-SSL PgSQL connections do not add keylog entries "
+        "(before=%ld after=%ld)", lines_nossl_before, lines_nossl_after);
+
+    admin_exec(admin, "SET pgsql-monitor_enabled='true'");
+    admin_exec(admin, "LOAD PGSQL VARIABLES TO RUNTIME");
+
+    // ================================================================
+    // Test 9: Invalid keylog path — graceful handling
+    // ================================================================
+    diag("---- Test 9: Invalid keylog path ----");
+
+    const char* bad_path = "/nonexistent/dir/proxysql_keylog.log";
+    set_keylog_file(admin, bad_path);
+
+    {
+        auto c = make_pgsql_ssl_conn();
+        (void)c;
+    }
+    usleep(100000);
+
+    long bad_sz = file_size(bad_path);
+    diag("bad_path size=%ld (expected -1)", bad_sz);
+
+    ok(bad_sz < 0,
+        "Test 9: Invalid keylog path handled gracefully — file not created at bad path");
+
+    // ================================================================
+    // Cleanup
+    // ================================================================
+    diag("---- Cleanup ----");
+
+    set_keylog_file(admin, original_keylog.empty() ? "" : original_keylog.c_str());
+
+    if (::remove(KEYLOG_PATH) == 0) {
+        diag("Removed keylog file: %s", KEYLOG_PATH);
+    }
+
+    return exit_status();
+}

From f2bd22214550fd58e555412f6cf55cc4bfdc1cdf Mon Sep 17 00:00:00 2001
From: Rahim Kanji <rahim.kanji@outlook.com>
Date: Fri, 3 Apr 2026 18:14:18 +0500
Subject: [PATCH 2/3] Fixed compilation issue

---
 doc/ssl_keylog/ssl_keylog_developer_guide.md  | 425 ++++++++++++++++++
 .../tests/unit/genai_query_handler_unit-t.cpp |   3 +-
 2 files changed, 427 insertions(+), 1 deletion(-)
 create mode 100644 doc/ssl_keylog/ssl_keylog_developer_guide.md

diff --git a/doc/ssl_keylog/ssl_keylog_developer_guide.md b/doc/ssl_keylog/ssl_keylog_developer_guide.md
new file mode 100644
index 000000000..51822579a
--- /dev/null
+++ b/doc/ssl_keylog/ssl_keylog_developer_guide.md
@@ -0,0 +1,425 @@
+# SSL/TLS Key Log Feature - Developer Guide
+
+## Overview
+
+ProxySQL implements SSL/TLS key logging to enable decryption of encrypted traffic for debugging purposes. This feature writes TLS secrets to a file in the NSS Key Log Format, which can be used by tools like Wireshark to decrypt and analyze TLS traffic.
+
+**PR Reference:** #4236 - "Added support for SSLKEYLOGFILE"
+
+---
+
+## Variable Naming Convention
+
+ProxySQL variables belong to **modules**. This is important for understanding how variables are referenced:
+
+| Context | Variable Name | Module |
+|---------|---------------|--------|
+| **Internal code** | `ssl_keylog_file` | Admin |
+| **SQL interface** | `admin-ssl_keylog_file` | Admin (with prefix) |
+| **Config file** | `ssl_keylog_file` | Admin (in `admin_variables` section) |
+
+**Code Location:** `include/proxysql_admin.h` - the variable is defined as `char* ssl_keylog_file` within the admin variables struct.
+
+**SQL Registration:** `lib/ProxySQL_Admin.cpp` - registered as `"ssl_keylog_file"` in the `admin_variables` array.
+
+When users set this variable via SQL, they must use the module prefix:
+```sql
+SET admin-ssl_keylog_file = '/path/to/file.txt';
+```
+
+---
+
+## Architecture
+
+### Component Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         ProxySQL Process                            │
+│                                                                      │
+│  ┌────────────────┐         ┌─────────────────────────────────┐   │
+│  | ProxySQL_Admin |────────>|  Global Variables               │   │
+│  |                │         |  .ssl_keylog_file = "/path/..."  │   │
+│  └────────────────┘         └─────────────────────────────────┘   │
+│           │                                                          │
+│           | SET admin-ssl_keylog_file='/path/keylog.txt'           │
+│           v                                                          │
+│  ┌──────────────────────────────────────────────────────────────┐ │
+│  |            proxysql_sslkeylog module                          │ │
+│  │                                                               │ │
+│  │  ┌──────────────┐  ┌──────────────────┐  ┌───────────────┐ │ │
+│  │  | keylog_init  |  | keylog_open     |  | keylog_close  │ │ │
+│  │  └──────────────┘  └──────────────────┘  └───────────────┘ │ │
+│  │                                                               │ │
+│  │  ┌──────────────────────────────────────────────────────────┐│ │
+│  │  | proxysql_keylog_attach_callback(SSL_CTX*)                ││ │
+│  │  |                                                          ││ │
+│  │  |   SSL_CTX_set_keylog_callback(ctx, write_line_callback)  ││ │
+│  │  └──────────────────────────────────────────────────────────┘│ │
+│  └──────────────────────────────────────────────────────────────┘ │
+│                              │                                      │
+│                              │ Callback invoked by OpenSSL         │
+│                              v                                      │
+│  ┌──────────────────────────────────────────────────────────────┐ │
+│  │ proxysql_keylog_write_line_callback(ssl, line)               │ │
+│  │                                                              │ │
+│  │   - Validate line length                                     │ │
+│  │   - Acquire read lock (rwlock)                               │ │
+│  │   - Write to keylog file                                    │ │
+│  │   - Release lock                                            │ │
+│  └──────────────────────────────────────────────────────────────┘ │
+│                              │                                      │
+│                              v                                      │
+│  ┌──────────────────────────────────────────────────────────────┐ │
+│  │           keylog_file_fp (FILE*)                             │ │
+│  │           "/var/log/proxysql/sslkeys.txt"                    │ │
+│  │                                                              │ │
+│  │   CLIENT_RANDOM 3a4b5c... <48-byte-secret>                   │ │
+│  │   CLIENT_HANDSHAKE_TRAFFIC_SECRET 3a4b... <32-byte-secret>   │ │
+│  │   SERVER_HANDSHAKE_TRAFFIC_SECRET 3a4b... <32-byte-secret>   │ │
+│  └──────────────────────────────────────────────────────────────┘ │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+### Thread Safety Model
+
+The keylog subsystem uses a **pthread read-write lock** for concurrent access.
+
+**Key Points:**
+- Multiple threads can write to the keylog file simultaneously during TLS handshakes
+- File rotation (open/close) acquires exclusive lock
+- Double-checked locking in `write_line_callback()` for performance
+
+---
+
+## NSS Key Log Format
+
+### File Structure
+
+Each line in the keylog file has the following format:
+
+```
+<LABEL> <ClientRandom> <Secret>\n
+```
+
+### Label Types
+
+| Label | TLS Version | Description | Secret Size |
+|-------|-------------|-------------|-------------|
+| `CLIENT_RANDOM` | TLS 1.2 and earlier | Master secret | 48 bytes |
+| `CLIENT_HANDSHAKE_TRAFFIC_SECRET` | TLS 1.3 | Client handshake traffic secret | 32 or 48 bytes |
+| `SERVER_HANDSHAKE_TRAFFIC_SECRET` | TLS 1.3 | Server handshake traffic secret | 32 or 48 bytes |
+| `CLIENT_TRAFFIC_SECRET_0` | TLS 1.3 | Client application data secret N | 32 or 48 bytes |
+| `SERVER_TRAFFIC_SECRET_0` | TLS 1.3 | Server application data secret N | 32 or 48 bytes |
+
+### Example Keylog File
+
+```
+# TLS 1.2 connection
+CLIENT_RANDOM 3a4b5c6d7e8f... 48_byte_master_secret_here...
+
+# TLS 1.3 connection
+CLIENT_HANDSHAKE_TRAFFIC_SECRET 3a4b5c6d7e8f... 32_byte_secret_here...
+SERVER_HANDSHAKE_TRAFFIC_SECRET 3a4b5c6d7e8f... 32_byte_secret_here...
+CLIENT_TRAFFIC_SECRET_0 3a4b5c6d7e8f... 32_byte_secret_here...
+SERVER_TRAFFIC_SECRET_0 3a4b5c6d7e8f... 32_byte_secret_here...
+```
+
+---
+
+## API Reference
+
+### Public Functions
+
+#### `proxysql_keylog_init()`
+
+```c
+void proxysql_keylog_init();
+```
+
+**Purpose:** Initialize the keylog subsystem
+
+**Called from:** `proxysql_global.cpp` during startup
+
+**Thread-safety:** Safe (single-threaded initialization only)
+
+---
+
+#### `proxysql_keylog_open(const char* keylog_file)`
+
+```c
+bool proxysql_keylog_open(const char* keylog_file);
+```
+
+**Purpose:** Open/create the keylog file
+
+**Parameters:**
+- `keylog_file`: Path to the keylog file
+
+**Returns:** `true` on success, `false` on failure
+
+**Behavior:**
+- Opens file in append mode with line buffering (4096 bytes)
+- Closes existing file if open (supports rotation)
+- Acquires write lock for thread safety
+
+**Called from:**
+- `ProxySQL_Admin::set_variable()` when `ssl_keylog_file` is set
+- `ProxySQL_Admin::flush_logs()` for log rotation
+
+---
+
+#### `proxysql_keylog_close(bool lock = true)`
+
+```c
+void proxysql_keylog_close(bool lock = true);
+```
+
+**Purpose:** Close the keylog file
+
+**Parameters:**
+- `lock`: If `true`, acquires write lock before closing
+
+**Behavior:**
+- Closes the file if open
+- Sets `keylog_file_fp` to `NULL`
+
+---
+
+#### `proxysql_keylog_attach_callback(SSL_CTX* ssl_ctx)`
+
+```c
+void proxysql_keylog_attach_callback(SSL_CTX* ssl_ctx);
+```
+
+**Purpose:** Attach keylog callback to an SSL context
+
+**Parameters:**
+- `ssl_ctx`: The SSL context to attach to
+
+**Behavior:**
+- Idempotent: only attaches if no callback already registered
+- Uses `SSL_CTX_set_keylog_callback()` (OpenSSL 1.1.1+)
+
+**Called from:**
+- `MySQL_Session::handler()` for frontend MySQL connections
+- `PgSQL_Session::handler()` for frontend PostgreSQL connections
+
+---
+
+#### `proxysql_keylog_write_line_callback(const SSL* ssl, const char* line)`
+
+```c
+void proxysql_keylog_write_line_callback(const SSL* ssl, const char* line);
+```
+
+**Purpose:** OpenSSL callback invoked during TLS handshake
+
+**Parameters:**
+- `ssl`: The SSL connection (unused)
+- `line`: The keylog line generated by OpenSSL (no newline)
+
+**Behavior:**
+- Validates line length (max 254 bytes)
+- Ensures newline termination
+- Acquires read lock and writes to file
+- Uses double-checked locking for performance
+
+**Called by:** OpenSSL automatically during TLS handshake
+
+---
+
+## Configuration Variable
+
+### `ssl_keylog_file` (internal name)
+
+**Module:** Admin
+
+**Internal Name:** `ssl_keylog_file`
+
+**SQL Interface Name:** `admin-ssl_keylog_file`
+
+**Type:** String (path)
+
+**Default:** `""` (empty string = disabled)
+
+**Runtime Configurable:** Yes
+
+**Path Resolution:**
+- Absolute path (starts with `/`): used as-is
+- Relative path: resolved relative to ProxySQL data directory
+- Empty string: disables key logging
+
+**SQL Usage:**
+```sql
+-- Enable key logging
+SET admin-ssl_keylog_file = '/var/log/proxysql/sslkeys.txt';
+
+-- Disable key logging
+SET admin-ssl_keylog_file = '';
+
+-- Apply to runtime
+LOAD ADMIN VARIABLES TO RUNTIME;
+```
+
+**Config File Usage:**
+```ini
+admin_variables=
+{
+    ssl_keylog_file='/var/log/proxysql/sslkeys.txt'
+}
+```
+
+---
+
+## Integration Points
+
+### 1. Variable Definition
+
+**File:** `include/proxysql_admin.h`
+
+```cpp
+struct {
+    // ...
+    char* ssl_keylog_file;  // Path to keylog file
+} variables;
+```
+
+### 2. Variable Registration
+
+**File:** `lib/ProxySQL_Admin.cpp`
+
+```cpp
+{ (char *)"ssl_keylog_file", ... }
+```
+
+### 3. Runtime Variable Setter
+
+**File:** `lib/ProxySQL_Admin.cpp:set_variable()`
+
+```cpp
+if (!strcasecmp(name, "ssl_keylog_file")) {
+    // Handle absolute vs relative paths
+    // Open file or validate path
+    // Set GloVars.global.ssl_keylog_enabled
+}
+```
+
+### 4. Log Rotation
+
+**File:** `lib/ProxySQL_Admin.cpp:flush_logs()`
+
+```cpp
+void ProxySQL_Admin::flush_logs() {
+    // ...
+    proxysql_keylog_close();  // Close current file
+    proxysql_keylog_open(ssl_keylog_file);  // Reopen
+}
+```
+
+### 5. SSL Context Integration
+
+**Files:**
+- `lib/MySQL_Session.cpp`
+- `lib/PgSQL_Session.cpp`
+
+```cpp
+proxysql_keylog_attach_callback(GloVars.get_SSL_ctx());
+```
+
+---
+
+## Security Considerations
+
+### WARNING: Critical Security Implications
+
+The keylog file contains **cryptographic secrets** that can decrypt ALL TLS traffic:
+
+1. **What the file contains:**
+   - TLS master secrets (TLS 1.2)
+   - Traffic encryption keys (TLS 1.3)
+   - Enough to decrypt past, present, and future connections
+
+2. **Attack scenarios if compromised:**
+   - Decryption of captured network traffic, exposing all plaintext data, including credentials, queries, and results.
+
+3. **Recommended safeguards:**
+   - **File permissions:** `0600` (owner read/write only)
+   - **Directory permissions:** `0700` (owner access only)
+   - **Enable only for debugging:** Disable in production
+   - **Rotate regularly:** `PROXYSQL FLUSH LOGS`
+   - **Secure deletion:** Shred file before deletion
+
+### Code Review Checklist
+
+When reviewing changes to this module:
+
+- [ ] File permissions are set correctly
+- [ ] Path validation prevents directory traversal
+- [ ] Lock acquisition is correct (rdlock vs wrlock)
+- [ ] Double-checked locking is properly implemented
+- [ ] No sensitive data in logs/error messages
+- [ ] Proper cleanup on error conditions
+
+---
+
+## Testing
+
+### Unit Test Structure
+
+**File:** `test/tap/tests/test_auth_methods-t.cpp`
+
+```cpp
+void ssl_keylog_callback(SSL*, const char* line) {
+    // Verify line format
+    // Verify file contents
+}
+
+// Test callback registration
+mysql_options(proxy, MARIADB_OPT_SSL_KEYLOG_CALLBACK, ...);
+```
+
+### Manual Testing
+
+1. **Enable key logging:**
+
+```bash
+mysql -h 127.0.0.1 -P 6032 -u admin -padmin -e "SET admin-ssl_keylog_file='/tmp/keylog.txt'; LOAD ADMIN VARIABLES TO RUNTIME;"
+```
+
+2. **Create TLS connection:**
+
+```bash
+mysql -h 127.0.0.1 -P 6033 -u user -ppass --ssl
+```
+
+3. **Verify keylog file:**
+
+```bash
+cat /tmp/keylog.txt
+# Should see CLIENT_RANDOM or TRAFFIC_SECRET lines
+```
+
+4. **Configure Wireshark:**
+   - Edit → Preferences → Protocols → TLS
+   - Set "(Pre)-Master-Secret log filename" to `/tmp/keylog.txt`
+   - Decrypt TLS traffic in Wireshark
+
+---
+
+## Performance Considerations
+
+1. **Line buffering:** 4096 bytes minimizes syscalls
+2. **Read-write lock:** Allows concurrent writes during handshakes
+3. **Double-checked locking:** Avoids lock acquisition when disabled
+4. **File mode:** Append mode minimizes disk seeks
+
+---
+
+## References
+
+- [NSS Key Log Format](https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format)
+- [Wireshark TLS Decryption](https://wiki.wireshark.org/TLS#TLS_Decryption)
+- [OpenSSL SSL_CTX_set_keylog_callback](https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_keylog_callback.html)
+- [PR #4236](https://github.com/sysown/proxysql/pull/4236)
diff --git a/test/tap/tests/unit/genai_query_handler_unit-t.cpp b/test/tap/tests/unit/genai_query_handler_unit-t.cpp
index b4062d5bd..ea1439255 100644
--- a/test/tap/tests/unit/genai_query_handler_unit-t.cpp
+++ b/test/tap/tests/unit/genai_query_handler_unit-t.cpp
@@ -14,9 +14,10 @@
  * Compiled only when PROXYSQLGENAI=1 (auto-detected from libproxysql.a).
  */
 
+#include "tap.h"
+
 #ifdef PROXYSQLGENAI
 
-#include "tap.h"
 #include "test_globals.h"
 #include "test_init.h"
 #include "proxysql.h"

From 50221943a3a8ed852540c23932867451583e4eda Mon Sep 17 00:00:00 2001
From: Rahim Kanji <rahim.kanji@outlook.com>
Date: Fri, 3 Apr 2026 18:31:33 +0500
Subject: [PATCH 3/3] Fix numbering in ssl_keylog user guide troubleshooting
 section (#5281)

---
 doc/ssl_keylog/ssl_keylog_user_guide.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/ssl_keylog/ssl_keylog_user_guide.md b/doc/ssl_keylog/ssl_keylog_user_guide.md
index c6ac5204d..e050e244d 100644
--- a/doc/ssl_keylog/ssl_keylog_user_guide.md
+++ b/doc/ssl_keylog/ssl_keylog_user_guide.md
@@ -429,7 +429,7 @@ mysql_variables=
    LOAD PGSQL SERVERS TO RUNTIME;
    ```
 4. Make sure clients are connecting with SSL/TLS
-3. Check that `admin-ssl_keylog_file` is loaded into runtime:
+5. Check that `admin-ssl_keylog_file` is loaded into runtime:
    ```sql
    LOAD ADMIN VARIABLES TO RUNTIME;
    ```