RFC 9850

The SSLKEYLOGFILE Format for TLS

📅 published July 2026, from ietf

RFC 9850: The SSLKEYLOGFILE Format for TLS ✨🎀

okay bestie, let's get into it 🦋 this one is a tiny Informational doc (not a standard, just published for info) about how to log TLS secrets to a file so diagnostic tools can decrypt test traffic. 🔐 Super handy, but also super dangerous if it leaks into production, so pay attention 🙈

Title block, the highlights 💅

  • Number and title: RFC 9850, The SSLKEYLOGFILE Format for TLS
  • Authors: M. Thomson (Mozilla), Y. Rosomakho (Zscaler), H. Tschofenig (H-BRS) 👑
  • Category: Informational 🌸
  • Date: July 2026 💜
  • Obsoletes and updates: nothing listed in the title block 🧚

Abstract

okay so the abstract says this doc describes a format for logging info about the secrets used in a TLS connection. recording those secrets into a file in SSLKEYLOGFILE format lets diagnostic and logging tools decrypt messages exchanged by TLS endpoints. it's meant for systems where TLS only protects test data, periodt 💀✨

Status of This Memo

this is not an Internet Standards Track spec, it's published for info only 🫶 it did go through IETF consensus and IESG approval, but not every approved doc is a candidate for any level of Internet Standard (see Section 2 of RFC 7841). 🌈

for the current status, errata, and feedback, check https://www.rfc-editor.org/info/rfc9850 🔥

Copyright (c) 2026 IETF Trust and the document authors, all rights reserved 💖 the doc is subject to BCP 78 and the IETF Trust's Legal Provisions (https://trustee.ietf.org/license-info) as of the publication date. read those, they cover your rights, ngl 🙈 any Code Components pulled from this doc must include Revised BSD License text (Section 4.e of the Trust Legal Provisions) and come without warranty, as the Revised BSD License describes. 📜

Table of Contents

  1. Introduction 1.1. Applicability Statement 1.2. Conventions
  2. The SSLKEYLOGFILE Format 2.1. Secret Labels for TLS 1.3 2.2. Secret Labels for TLS 1.2 2.3. Secret Labels for ECH
  3. Security Considerations
  4. IANA Considerations 4.1. SSLKEYLOGFILE Media Type 4.2. TLS SSLKEYLOGFILE Labels Registry
  5. References 5.1. Normative References 5.2. Informative References Appendix A. Example Acknowledgments Authors' Addresses

1. Introduction 🦋

okay so debugging gets really hard when TLS [TLS13] is encrypting everything. being able to inspect encrypted messages in diagnostic tools makes analysis way more thorough, lowkey a must 🔍

over time, a bunch of TLS implementations informally adopted a file format for logging the secret values generated by the TLS key schedule. lots of them point the log file at an environment variable called "SSLKEYLOGFILE", which is where the format gets its name 🌸 the "SSL" in there is a leftover from before TLS was the protocol's name, so don't be confused 💅

this doc describes that SSLKEYLOGFILE format. it works with TLS 1.2 [TLS12] and TLS 1.3 [TLS13]. earlier TLS versions are supported too, but using them is strongly discouraged [RFC8996] [RFC9325], so not it 🙅‍♀️ it can also be used with DTLS [DTLS13], QUIC [RFC9000] [RFC9001], and other protocols that use the TLS key schedule. it could also complement protocol-specific logging like qlog [QLOG] ✨

this doc also defines labels for logging info about exchanges that use Encrypted Client Hello (ECH) [ECH] 🧚

1.1. Applicability Statement

okay, this is the big warning 🚨 the artifact this doc describes, if it's given to anyone other than endpoints, completely undermines the core guarantees TLS provides. the format is intended for systems where TLS only protects test data. the access it gives to TLS connections is useful for diagnosing problems while developing, but this mechanism MUST NOT be used in a production system. 🛑 for compiled software, using conditional compilation is the best way to make sure deployed binaries can't be configured to enable key logging. 🔒

⚠️ bestie, read this one twice. key logging in production = game over for the encryption.

Section 3 covers a bunch of additional concerns that come up with key logging 👑

1.2. Conventions

the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this doc are interpreted as described in BCP 14 [RFC2119] [RFC8174], but only when they show up in all capitals, exactly like this 🎀

2. The SSLKEYLOGFILE Format 🔐

a file in SSLKEYLOGFILE format is a text file. the doc specifies UTF-8 [RFC3629] as the character encoding 💜 the format itself only has ASCII characters [RFC0020], but comments MAY contain other characters. Unicode is allowed in comments, but the file MUST NOT contain a Unicode byte order mark (U+FEFF). 🙅‍♀️

line endings follow the convention of the platform where the file is generated. tools that process these files MUST accept CRLF (U+13 followed by U+10), CR (U+13), or LF (U+10) as a line terminator. lines are ignored if they're empty or if the first character is an octothorpe ('#', U+23). every other line holds a single secret. 🌈

implementations that record secrets to a file do it continuously, as the secrets get generated. ⭐

each secret is a single line made of three values, separated by a single space (U+20). the values are:

label: identifies the type of secret being conveyed. see Sections 2.1, 2.2, and 2.3 for the labels this doc defines. 🏷️

client_random: the 32-byte value of the Random field from the ClientHello that set up the TLS connection. it's encoded as 64 hexadecimal characters. in a log that can hold secrets from multiple connections, this field is how you identify a connection 🧩

secret: the value of the identified secret for the identified connection. it's hex-encoded, and its length depends on the size of the secret. 🔑

for hex values of client_random or secret, there's no convention for "a" through "f" (or "A" through "F"). files can be generated with either, so processing MUST accept either form. 💅

diagnostic tools that accept this format MAY choose to ignore lines that don't conform, so secrets can still be pulled out of corrupted files. 🛠️

logged secret values aren't annotated with the cipher suite or other connection parameters, so you might need a record of the TLS handshake to actually use the logged secrets. 📝

2.1. Secret Labels for TLS 1.3 🦋

an implementation of TLS 1.3 produces a bunch of values as part of the key schedule (see Section 7.1 of [TLS13]). if ECH was successfully negotiated for a connection, these labels MUST be followed by the value of the Random field from the Inner ClientHello. otherwise, the Random field from the Outer ClientHello MUST be used. ✨

each label below matches the equivalent secret from the key schedule:

CLIENT_EARLY_TRAFFIC_SECRET: protects records the client sends as early data, if the client attempts early data. a server that rejects early data won't log this secret, though a client that attempts early data can log it unconditionally. 🚀

EARLY_EXPORTER_SECRET: used for early exporters. like CLIENT_EARLY_TRAFFIC_SECRET, it's only generated when early data is attempted, and a server might not log it if early data gets rejected. 🌷

CLIENT_HANDSHAKE_TRAFFIC_SECRET: protects handshake records the client sends. 🤝

SERVER_HANDSHAKE_TRAFFIC_SECRET: protects handshake records the server sends. 🤝

CLIENT_TRAFFIC_SECRET_0: protects application_data records the client sends right after the handshake completes. it's called client_application_traffic_secret_0 in the TLS 1.3 key schedule. 💌

SERVER_TRAFFIC_SECRET_0: protects application_data records the server sends right after the handshake completes. it's called server_application_traffic_secret_0 in the TLS 1.3 key schedule. 💌

EXPORTER_SECRET: used to generate exporters (Section 7.5 of [TLS13]). 🌟

these labels all show up in uppercase in the log, but they match lowercase labels in the TLS key schedule (Section 7.1 of [TLS13]), except for the application data secrets, as noted. for example, "EXPORTER_SECRET" in the log corresponds to the secret named exporter_secret. 🔤

the labels are listed in the order they appear in [TLS13], but there's no guarantee implementations will log secrets in that exact order. 🎀

2.2. Secret Labels for TLS 1.2 🌸

implementations of TLS 1.2 [TLS12] (and earlier versions too) use the label "CLIENT_RANDOM" to identify the "master" secret for the connection. 💖

2.3. Secret Labels for ECH 🧚

with ECH [ECH], extra secrets get derived during the handshake to encrypt the Inner ClientHello using Hybrid Public Key Encryption (HPKE) [HPKE] 🔐 a client can log the ECH labels below if it offered ECH, regardless of whether the server accepted it. the server can log them only if it successfully decrypted the ECH the client offered, though it could choose to log only when it accepts ECH. 🫶

these labels MUST always use the Random from the Outer ClientHello. 🌈

ECH_SECRET: corresponds to the Key Encapsulation Mechanism (KEM) shared secret used by HPKE (shared_secret in the algorithms in Section 5.1.1 of [HPKE]). the length of the secret is defined by the KEM negotiated for ECH. 🔑

ECH_CONFIG: the ECHConfig used to construct the ECH extension. the value is logged in hexadecimal. 📦

okay bestie that's part 1 🎀 we've covered the title block, the abstract, the status and copyright stuff, the TOC, and sections 1 through 2.3 💖 more parts coming, so stay tuned 🦋✨

3. Security Considerations 🔐💅

okay bestie, this section is SERIOUS and I'm not gonna pretend it isn't 😭 anyone who can read an SSLKEYLOGFILE can break the confidentiality and integrity protection on every TLS connection in it. That includes live connections AND old ones where the encrypted records were stored earlier. So locking down access to these files is literally the whole game 🔒✨

Implementations that can log this stuff MUST make sure only authorized people can turn logging on. If anyone who isn't already allowed to watch or change a connection can start logging its secrets, that's a privilege escalation attack, and it is NOT giving. Implementations that do enable logging also need to limit who can read the logged secrets, using file permissions or some other equivalent access control 🫶

Okay so here's the spicy part 🌶️. The logged secrets are what's needed to take off record protection, and the keys derived from them are symmetric. That means anyone holding these secrets can also ENCRYPT data for an active connection. Which might let them inject or modify application data on a connection that TLS would otherwise be protecting. Scary, I know 💀

Some protocols lean on TLS to generate their encryption keys, so the SSLKEYLOGFILE format includes keys that identify the secret used in TLS exporters or early exporters (Section 7.5 of [TLS13]). Knowing these can be about way more than just reading or changing encrypted data, depending on how an application protocol uses exporters. For example, exporters might be used for session bindings (e.g., [RFC8471]), authentication (e.g., [RFC9261]), or other derived secrets used in an application context. An adversary who gets these secrets might be able to use them to attack those applications 😱 A TLS implementation might either choose to leave these secrets out in contexts where the info could be abused, or require separate authorization before it logs exporter secrets 🙈

Using an environment variable, like SSLKEYLOGFILE, to turn on logging means that access to the application's launch context is needed to authorize logging. On systems that support specially named files, logs might be sent to those names so nothing gets stored but other programs can still consume them 🧚 In both cases, applications might need special authorization, or they might just rely on system-level access control to limit who can use these capabilities.

Forward secrecy, the vibe TLS 1.3 gives you (see Section 1.3 and Appendix F.1 of [TLS13]) and some TLS 1.2 modes (like the ones in Sections 2.1 and 2.2 of [RFC8422]), does NOT hold up if key material gets recorded. Anyone with that key material can decrypt data from any previously logged TLS connection. Not iconic 💔

⚠️ Logging the TLS 1.2 "master" secret gives the recipient of that secret WAY more access to an active connection than TLS 1.3 secrets do. Besides reading and altering protected messages, the TLS 1.2 "master" secret lets them resume the connection, impersonate either endpoint, insert records that cause renegotiation, and forge Finished messages. Implementations MAY avoid all of these risks by not logging this secret value.

Hmm, that last line was supposed to be exact: the original says "Implementations can avoid the risks associated with these capabilities by not logging this secret value," so no capitalised key word there. Correcting that below 👇

⚠️ Logging the TLS 1.2 "master" secret gives the recipient of that secret WAY more access to an active connection than TLS 1.3 secrets do. Besides reading and altering protected messages, the TLS 1.2 "master" secret lets them resume the connection, impersonate either endpoint, insert records that cause renegotiation, and forge Finished messages. Implementations can avoid the risks tied to these capabilities by not logging this secret value. 🛡️

Access to the ECH_SECRET record in SSLKEYLOGFILE lets an attacker decrypt the ECH extension, which reveals the content of the Inner ClientHello message, including the payload of the Server Name Indication (SNI) extension 🕵️‍♀️ yikes.

And last but not least, access to the HPKE-established shared secret used in ECH creates a potential attack surface against the HPKE library, since that keying material is normally not available otherwise 🧐 Main character villain arc, honestly.

4. IANA Considerations 📋✨

okay so this section is all about paperwork 🎀 This document registers a media type (Section 4.1) and creates a registry for labels (Section 4.2). Lowkey my favourite kind of bureaucracy 💜

4.1. SSLKEYLOGFILE Media Type 🦋

The "application/sslkeylogfile" media type can be used to describe content in the SSLKEYLOGFILE format. IANA has added the following info to the "Media Types" registry at <https://www.iana.org/assignments/media-types>:

Type name:  application

Subtype name:  sslkeylogfile

Required parameters:  N/A

Optional parameters:  N/A

Encoding considerations:  UTF-8 without BOM, or ASCII only

Security considerations:  See Section 3.

Interoperability considerations:  Line endings might differ from
   platform convention.

Published specification:  RFC 9850

Applications that use this media type:  Diagnostic and analysis tools
   that need to decrypt data that is otherwise protected by TLS.

Fragment identifier considerations:  N/A

Additional information:

   Deprecated alias names for this type:  N/A
   Magic number(s):  N/A
   File extension(s):  N/A
   Macintosh file type code(s):  N/A

Person & email address to contact for further information:
   TLS WG (tls@ietf.org)

Intended usage:  COMMON

Restrictions on usage:  N/A

Author:  IETF TLS Working Group

Change controller:  IETF

4.2. TLS SSLKEYLOGFILE Labels Registry 🏷️

IANA has created a new registry named "TLS SSLKEYLOGFILE Labels" within the existing "Transport Layer Security (TLS) Parameters" registry group. This new registry reserves labels used for SSLKEYLOGFILE entries. The initial contents look like this 👀

+=================================+=====================+===========+
| Value                           | Description         | Reference |
+=================================+=====================+===========+
| CLIENT_RANDOM                   | Master secret in    | RFC 9850  |
|                                 | TLS 1.2 and         |           |
|                                 | earlier             |           |
+---------------------------------+---------------------+-----------+
| CLIENT_EARLY_TRAFFIC_SECRET     | Secret for client   | RFC 9850  |
|                                 | early data          |           |
|                                 | records             |           |
+---------------------------------+---------------------+-----------+
| EARLY_EXPORTER_SECRET           | Early exporter      | RFC 9850  |
|                                 | secret              |           |
+---------------------------------+---------------------+-----------+
| CLIENT_HANDSHAKE_TRAFFIC_SECRET | Secret protecting   | RFC 9850  |
|                                 | client handshake    |           |
+---------------------------------+---------------------+-----------+
| SERVER_HANDSHAKE_TRAFFIC_SECRET | Secret protecting   | RFC 9850  |
|                                 | server handshake    |           |
+---------------------------------+---------------------+-----------+
| CLIENT_TRAFFIC_SECRET_0         | Secret protecting   | RFC 9850  |
|                                 | client records      |           |
|                                 | post handshake      |           |
+---------------------------------+---------------------+-----------+
| SERVER_TRAFFIC_SECRET_0         | Secret protecting   | RFC 9850  |
|                                 | server records      |           |
|                                 | post handshake      |           |
+---------------------------------+---------------------+-----------+
| EXPORTER_SECRET                 | Exporter secret     | RFC 9850  |
|                                 | after handshake     |           |
+---------------------------------+---------------------+-----------+
| ECH_SECRET                      | HPKE KEM shared     | RFC 9850  |
|                                 | secret used in      |           |
|                                 | the ECH             |           |
+---------------------------------+---------------------+-----------+
| ECH_CONFIG                      | ECHConfig used      | RFC 9850  |
|                                 | for construction    |           |
|                                 | of the ECH          |           |
+---------------------------------+---------------------+-----------+

Table 1

New assignments in the "TLS SSLKEYLOGFILE Labels" registry will be administered by IANA through the Specification Required procedure [RFC8126]. The role of designated experts for TLS registries is described in Section 17 of [RFC8447]. Designated experts for this registry are advised to make sure the specification is publicly available. In the Reference column, it's enough to cite an Internet-Draft (posted but not published as an RFC) or a document from another standards body, an industry consortium, or any other organization. Designated experts may give more in-depth reviews, but their approval should NOT be taken as an endorsement of the SSLKEYLOGFILE label 🙅‍♀️

Wait, I need to fix that last one: the original says "should not be taken," which is a SHOULD NOT. Correct version: their approval SHOULD NOT be taken as an endorsement of the SSLKEYLOGFILE label 💖

5. References 📚

5.1. Normative References 🌟

[ECH]      Rescorla, E., Oku, K., Sullivan, N., and C. A. Wood, "TLS
           Encrypted Client Hello", RFC 9849, DOI 10.17487/RFC9849,
           March 2026, <https://www.rfc-editor.org/info/rfc9849>.

[HPKE]     Barnes, R., Bhargavan, K., Lipp, B., and C. Wood, "Hybrid
           Public Key Encryption", RFC 9180, DOI 10.17487/RFC9180,
           February 2022, <https://www.rfc-editor.org/info/rfc9180>.

[RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
           Requirement Levels", BCP 14, RFC 2119,
           DOI 10.17487/RFC2119, March 1997,
           <https://www.rfc-editor.org/info/rfc2119>.

[RFC3629]  Yergeau, F., "UTF-8, a transformation format of ISO
           10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
           2003, <https://www.rfc-editor.org/info/rfc3629>.

[RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
           2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
           May 2017, <https://www.rfc-editor.org/info/rfc8174>.

[TLS12]    Dierks, T. and E. Rescorla, "The Transport Layer Security
           (TLS) Protocol Version 1.2", RFC 5246,
           DOI 10.17487/RFC5246, August 2008,
           <https://www.rfc-editor.org/info/rfc5246>.

[TLS13]    Rescorla, E., "The Transport Layer Security (TLS) Protocol
           Version 1.3", RFC 9846, DOI 10.17487/RFC9846, July 2026,
           <https://www.rfc-editor.org/info/rfc9846>.

5.2. Informative References ✨

okay bestie, these are the informative refs, the "go read this if you want the backstory" pile 📚💅

Appendix A. Example 🎀

okay this is the fun part!! here's a sample file in SSLKEYLOGFILE format, with secrets from two TLS 1.3 connections 🔐✨

the examples below use line wrapping per [RFC8792] 💅

CLIENT_HANDSHAKE_TRAFFIC_SECRET \
  cf34899b3dcb8c9fe7160ceaf95d354a294793b67a2e49cb9cca4d69b43593a0 \
  be4a28d81ce41242ff31c6d8a6615852178f2cd75eaca2ee8768f9ed51282b38
SERVER_HANDSHAKE_TRAFFIC_SECRET \
  cf34899b3dcb8c9fe7160ceaf95d354a294793b67a2e49cb9cca4d69b43593a0 \
  258179721fa704e2f1ee16688b4b0419967ddea5624cd5ad0863288dc5ead35f
CLIENT_HANDSHAKE_TRAFFIC_SECRET \
  b2eb93b8ddab8c228993567947bca1e133736980c22754687874e3896f7d6d0a \
  59ec0981b211a743f22d5a46a1fc77a2b230e16ef0de6d4e418abfe90eff10bf
SERVER_HANDSHAKE_TRAFFIC_SECRET \
  b2eb93b8ddab8c228993567947bca1e133736980c22754687874e3896f7d6d0a \
  a37fe4d3b6c9a6a372396b1562f6f8a40c1c3f85f1aa9b02d5ed46c4a1301365
CLIENT_TRAFFIC_SECRET_0 \
  cf34899b3dcb8c9fe7160ceaf95d354a294793b67a2e49cb9cca4d69b43593a0 \
  e9ca165bcb762fab8086068929d26c532e90ef2e2daa762d8b52346951a34c02
SERVER_TRAFFIC_SECRET_0 \
  cf34899b3dcb8c9fe7160ceaf95d354a294793b67a2e49cb9cca4d69b43593a0 \
  4f93c61ac1393008d4c820f3723db3c67494f06574b65fcc21c9eef22f90071a
EXPORTER_SECRET \
  cf34899b3dcb8c9fe7160ceaf95d354a294793b67a2e49cb9cca4d69b43593a0 \
  011c900833468f837f7c55d836b2719beebd39b1648fdeda58772f48d94a1ffa
CLIENT_TRAFFIC_SECRET_0 \
  b2eb93b8ddab8c228993567947bca1e133736980c22754687874e3896f7d6d0a \
  e9160bca1a531d871f5ecf51943d8cfb88833adeccf97701546b5fb93e030d79
SERVER_TRAFFIC_SECRET_0 \
  b2eb93b8ddab8c228993567947bca1e133736980c22754687874e3896f7d6d0a \
  fb1120b91e48d402fac20faa33880e77bace82c85d6688df0aa99bf5084430e4
EXPORTER_SECRET \
  b2eb93b8ddab8c228993567947bca1e133736980c22754687874e3896f7d6d0a \
  db1f4fa1a6942fb125d4cc47e02938b6f8030c6956bb81b9e3269f1cf855a8f8

heads up: secrets from the two connections might be interleaved like this, because secrets could be logged as they're generated. ngl that's very real life 🌀

next up, a log entry for a TLS 1.2 connection 🧚

CLIENT_RANDOM \
  ad52329fcadd34ee3aa07092680287f09954823e26d7b5ae25c0d47714152a6a \
  97af4c8618cfdc0b2326e590114c2ec04b43b08b7e2c3f8124cc61a3b068ba966\
  9517e744e3117c3ce6c538a2d88dfdf

and last but not least, a log entry for a TLS 1.3 connection that successfully negotiated ECH 🦋

ECH_SECRET \
  0ba587ee6b65ce21a726630efb881206a7cd995611095b5f4c244bb2b23f1ee1 \
  e8828ec09909cc9363179dc13b62498550c8637129345263011a1678370ca52a
ECH_CONFIG \
  0ba587ee6b65ce21a726630efb881206a7cd995611095b5f4c244bb2b23f1ee1 \
  fe0d003c5500200020d5260ae4cdda08bcbdc37bd0dc53c29aea5f0fdd2b2d59 \
  4e4235e99b134ac904000400010001000d636f7665722e6465666f2e69650000
CLIENT_HANDSHAKE_TRAFFIC_SECRET \
  8726180bb24718089a4c5c8c93e0ea1c6d6649d7dd3c978fc1413854a20e9647 \
  a195b63ec4270609692a204c08e63e74d9ae58e377d11a383bfe641a63c01140
SERVER_HANDSHAKE_TRAFFIC_SECRET \
  8726180bb24718089a4c5c8c93e0ea1c6d6649d7dd3c978fc1413854a20e9647 \
  022d1cb827a90f27dadde0c99110c2b7d0f362fdfe420a04818aa223e5f2c14c
CLIENT_TRAFFIC_SECRET_0 \
  8726180bb24718089a4c5c8c93e0ea1c6d6649d7dd3c978fc1413854a20e9647 \
  c2310f7db71109de88bab6f2f433fdc1704aecc0d57349cbf9113e5033178172
SERVER_TRAFFIC_SECRET_0 \
  8726180bb24718089a4c5c8c93e0ea1c6d6649d7dd3c978fc1413854a20e9647 \
  04ffc7c154f71ba5f530c7344b0496f60ce71b9b7c6b0e203ea574bfcdf14e27
EXPORTER_SECRET \
  8726180bb24718089a4c5c8c93e0ea1c6d6649d7dd3c978fc1413854a20e9647 \
  befb5db5ac6785b5dd4c6a8c4693c379ec0a1486b5fd035b25e50c3c95abc500

Acknowledgments 🫶

the SSLKEYLOGFILE format started out in the Network Security Services (NSS) project, and it has evolved as TLS has changed. loads of people helped it grow 🌷 the authors are just documenting the format as it's used, while extending it to cover ECH 💖

Authors' Addresses 💌

Martin Thomson Mozilla Email: mt@lowentropy.net

Yaroslav Rosomakho Zscaler Email: yrosomakho@zscaler.com

Hannes Tschofenig University of Applied Sciences Bonn-Rhein-Sieg Email: Hannes.Tschofenig@gmx.net

the end, bestie!! 🌈✨💅

📦 where this page comes from