TLS Key Logging

When a support incident involves an encrypted connector — FTPS, IMAP(S), HTTP/REST over TLS, and so on — a packet capture on the wire shows only the TCP stream and the TLS handshake. The payload and all protocol replies are encrypted, which makes wire-level diagnosis slow.

TLS key logging is an opt-in, admin-gated debugging aid. When enabled, TLS-capable connectors write an NSS-format key log (the same SSLKEYLOGFILE format browsers use) for each execution. Feeding that key log to Wireshark alongside a packet capture of the same connection decrypts the traffic, turning multi-hour guesswork into a direct read.

Security

A TLS key log contains the master secrets that decrypt all traffic on the logged connection, including credentials and payload. Anyone with the key log and a packet capture can read everything the connector sent and received.

Enable it only on a system you control, for a specific investigation, and delete the key logs as soon as the investigation is complete. The feature is designed to be impossible for a tenant or flow author to enable on their own — it requires host-level access and an administrator role — precisely because it exposes secrets.

Supported connectors

Key logging applies to every connector that routes through the shared TLS context builder:

• FTP / FTPS (both the implicit and the explicit-FTPS path)
• SMTP(S)
• IMAP(S)
• HTTP / REST (HTTPS)
• WebDAV
• SOAP
• XML-RPC
• JSON-RPC
• Vault
• PostgreSQL
• MySQL

Enabling it

Two independent gates must both be set. Either one alone is a no-op, so key logging stays off unless an administrator deliberately turns on both — one at the host level, one at the workspace level.

1. Host: set the output directory

Set the installation environment variable CLOUDOMATION_TLS_KEYLOG_DIR on the workspace host to an admin-owned directory. The workspace creates it with mode 0700 if it does not exist, so it is readable only by the account that runs the workspace.

# on the workspace host, in the installation's environment
CLOUDOMATION_TLS_KEYLOG_DIR=/var/lib/cloudomation/tls-keylogs

This variable is a host-level setting. It is deliberately not a workspace configuration value, so it cannot be set from inside the product.

If it is unset, TLS key logging is a hard no-op regardless of the workspace configuration below.

2. Workspace: turn on the toggle

Set the TLS_KEYLOG_DEBUG workspace configuration to true. This key is editable only with administrator permissions and defaults to false.

Once both gates are set, the next TLS connection from any supported connector writes a key log and emits a WARNING audit line to its execution log:

TLS key logging is active for this connection. Master secrets that decrypt ALL traffic on this connection — INCLUDING credentials and payload — are being written to <path> on the workspace host.

Where the key log is written

Each execution writes one file, named:

keylog-<execution_id>-<timestamp>.log

in the directory named by CLOUDOMATION_TLS_KEYLOG_DIR. Key logs are never written to git-tracked content, bundle content, or an execution's output value — only to the admin-owned host directory.

Capturing and decrypting

1. Enable key logging as described above.
2. Start a packet capture on the workspace host for the connector's traffic, for example:

   tcpdump -i any -w /tmp/capture.pcap host <target-host> and port <target-port>

3. Run the flow or connector whose connection you want to inspect. Note its execution id — it is part of the key-log filename.
4. Stop the capture. Copy both the .pcap and the matching keylog-<execution_id>-<ts>.log to the machine where you run Wireshark.
5. In Wireshark, open Edit → Preferences → Protocols → TLS and set (Pre)-Master-Secret log filename to the copied key log. Wireshark decrypts the matching TLS sessions in the capture.

Retention and cleanup

Key logs are sensitive and short-lived by design.

• Automatic reaping. While CLOUDOMATION_TLS_KEYLOG_DIR is configured, the workspace opportunistically removes keylog-*.log files older than CLOUDOMATION_TLS_KEYLOG_TTL_MINUTES (default 30). The reaper runs on every connection gate check — including while the TLS_KEYLOG_DEBUG toggle is off — so key logs do not linger after an investigation ends. Set the value to 0 to disable automatic reaping.
• Manual cleanup — mandatory. When the investigation is complete, set TLS_KEYLOG_DEBUG back to false and delete any key logs you copied off the host. Do not rely on the reaper alone for copies made elsewhere.

The off path

With either gate unset, keylog_filename is never assigned on the TLS context, so the connection behaves exactly as it does without the feature. There is no performance, behaviour, or format change on the normal path.

Learn More

Exceptions

Interactive Mode

Workspace Configuration