Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is athttps://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 9 December 2025.¶

Copyright Notice

Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1.Introduction

Debugging or analyzing protocols can be challenging when TLS[TLS13] is usedto protect the content of communications. Inspecting the content of encryptedmessages in diagnostic tools can enable more thorough analysis.¶

Over time, multiple TLS implementations have informally adopted a file formatfor logging the secret values generated by the TLS key schedule. In manyimplementations, the file that the secrets are logged to is specified in anenvironment variable named "SSLKEYLOGFILE", hence the name of SSLKEYLOGFILEformat. Note the use of "SSL" as this convention originally predates theadoption of TLS as the name of the protocol.¶

This document describes the SSLKEYLOGFILE format. This format can be used forTLS 1.2[TLS12] and TLS 1.3[TLS13]. The format alsosupports earlier TLS versions, though use of earlier versions is strongly discouraged[RFC8996][RFC9325]. This format can also be used with DTLS[DTLS13], QUIC[RFC9000][RFC9001], and other protocols that also use the TLS keyschedule. Use of this format could complement other protocol-specific loggingsuch as QLOG[QLOG].¶

This document also defines labels that can be used to log informationabout exchanges that use Encrypted Client Hello (ECH)[ECH].¶

2.The SSLKEYLOGFILE Format

A file in SSLKEYLOGFILE format is a text file. This document specifies thecharacter encoding as UTF-8[RFC3629]. Though the format itself onlyincludes ASCII characters[RFC0020], commentsMAY contain other characters.Though Unicode is permitted in comments, the fileMUST NOT contain a Unicodebyte order mark (U+FEFF).¶

Lines are terminated using the line ending convention of the platform on whichthe file is generated. Tools that process these filesMUST accept CRLF (U+13followed by U+10), CR (U+13), or LF (U+10) as a line terminator. Lines areignored if they are empty or if the first character is an octothorpe character('#', U+23). Other lines of the file each contain a single secret.¶

Implementations that record secrets to a file do so continuously as thosesecrets are generated.¶

Each secret is described using a single line composed of three values that areseparated by a single space character (U+20). These values are:¶

label:

The label identifies the type of secret that is being conveyed; seeSection 2.1for a description of the labels that are defined in this document.¶

client_random:

The 32-byte value of the Random field from the ClientHello message thatestablished the TLS connection. This value is encoded as 64 hexadecimalcharacters. In a log that can include secrets from multiple connections, thisfield can be used to identify a connection.¶

secret:

The value of the identified secret for the identified connection. This valueis encoded in hexadecimal, with a length that depends on the size of thesecret.¶

For the hexadecimal values of theclient_random orsecret, no conventionexists for the case of characters 'a' through 'f' (or 'A' through 'F'). Filescan be generated with either, so either formMUST be accepted when processing afile.¶

Diagnostic tools that accept files in this format might choose to ignore linesthat do not conform to this format in the interest of ensuring that secrets canbe obtained from corrupted files.¶

Logged secret values are not annotated with the cipher suite or other connectionparameters. A record of the TLS handshake might therefore be needed to use thelogged secrets.¶

3.Security Considerations

Access to the content of a file in SSLKEYLOGFILE format allows an attacker tobreak the confidentiality and integrity protection on any TLS connections thatare included in the file. This includes both active connections and connectionsfor which encrypted records were previously stored. Ensuring adequate accesscontrol on these files therefore becomes very important.¶

Implementations that support logging this data need to ensure that logging canonly be enabled by those who are authorized. Allowing logging to be initiatedby any entity that is not otherwise authorized to observe or modify the contentof connections for which secrets are logged could represent a privilegeescalation attack. Implementations that enable logging also need to ensure thataccess to logged secrets is limited, using appropriate file permissions orequivalent access control mechanisms.¶

In order to support decryption, the secrets necessary to remove recordprotection are logged. However, as the keys that can be derived from thesesecrets are symmetric, an adversary with access to these secrets is also able toencrypt data for an active connection. This might allow for injection ormodification of application data on a connection that would otherwise beprotected by TLS.¶

As some protocols rely on TLS for generating encryption keys, the SSLKEYLOGFILEformat includes keys that identify the secret used in TLS exporters or earlyexporters (Section 7.5 of [TLS13]). Knowledge of these secrets can enablemore than inspection or modification of encrypted data, depending on how anapplication protocol uses exporters. For instance, exporters might be used forsession bindings (e.g.,[RFC8471]), authentication (e.g.,[RFC9261]), orother derived secrets that are used in application context. An adversary thatobtains these secrets might be able to use this information to attack theseapplications. A TLS implementation might either choose to omit these secrets incontexts where the information might be abused or require separateauthorization to enable logging of exporter secrets.¶

Using an environment variable, such asSSLKEYLOGFILE, to enable loggingimplies that access to the launch context for the application is needed toauthorize logging. On systems that support specially-named files, logs might bedirected to these names so that logging does not result in storage, but enableconsumption by other programs. In both cases, applications might requirespecial authorization or they might rely on system-level access control to limitaccess to these capabilities.¶

Forward secrecy guarantees provided in TLS 1.3 (see Section1.2 and AppendixE.1 of[RFC8446]) and some modes of TLS 1.2 (such as those in Sections2.2 and2.4 of[RFC4492]) do not hold if key material is recorded. Access to keymaterial allows an attacker to decrypt data exchanged in any previously logged TLSconnections.¶

Logging the TLS 1.2 "master" secret provides the recipient of that secret fargreater access to an active connection than TLS 1.3 secrets. In addition toreading and altering protected messages, the TLS 1.2 "master" secret confers theability to resume the connection and impersonate either endpoint, insert recordsthat result in renegotiation, and forge Finished messages. Implementations canavoid the risks associated with these capabilities by not logging this secretvalue.¶

Access to the ECH_SECRET record in the SSLKEYLOGFILE allows the attacker to decryptthe ECH extension and thereby reveal the content of the Inner ClientHello message,including the payload of the Server Name Indication (SNI) extension.¶

Access to the HPKE-established shared secret used in ECH introduces a potentialattack surface against the HPKE library since access to this keying materialis normally not available otherwise.¶

4.IANA Considerations

This document registers a media type (Section 4.1)and creates a registry for labels (Section 4.2).¶

5.References

Appendix A.Example

The following is a sample of a file in this format, including secrets from twoTLS 1.3 connections.¶

# NOTE: '\' line wrapping per RFC 8792CLIENT_HANDSHAKE_TRAFFIC_SECRET \  cf34899b3dcb8c9fe7160ceaf95d354a294793b67a2e49cb9cca4d69b43593a0 \  be4a28d81ce41242ff31c6d8a6615852178f2cd75eaca2ee8768f9ed51282b38SERVER_HANDSHAKE_TRAFFIC_SECRET \  cf34899b3dcb8c9fe7160ceaf95d354a294793b67a2e49cb9cca4d69b43593a0 \  258179721fa704e2f1ee16688b4b0419967ddea5624cd5ad0863288dc5ead35fCLIENT_HANDSHAKE_TRAFFIC_SECRET \  b2eb93b8ddab8c228993567947bca1e133736980c22754687874e3896f7d6d0a \  59ec0981b211a743f22d5a46a1fc77a2b230e16ef0de6d4e418abfe90eff10bfSERVER_HANDSHAKE_TRAFFIC_SECRET \  b2eb93b8ddab8c228993567947bca1e133736980c22754687874e3896f7d6d0a \  a37fe4d3b6c9a6a372396b1562f6f8a40c1c3f85f1aa9b02d5ed46c4a1301365CLIENT_TRAFFIC_SECRET_0 \  cf34899b3dcb8c9fe7160ceaf95d354a294793b67a2e49cb9cca4d69b43593a0 \  e9ca165bcb762fab8086068929d26c532e90ef2e2daa762d8b52346951a34c02SERVER_TRAFFIC_SECRET_0 \  cf34899b3dcb8c9fe7160ceaf95d354a294793b67a2e49cb9cca4d69b43593a0 \  4f93c61ac1393008d4c820f3723db3c67494f06574b65fcc21c9eef22f90071aEXPORTER_SECRET \  cf34899b3dcb8c9fe7160ceaf95d354a294793b67a2e49cb9cca4d69b43593a0 \  011c900833468f837f7c55d836b2719beebd39b1648fdeda58772f48d94a1ffaCLIENT_TRAFFIC_SECRET_0 \  b2eb93b8ddab8c228993567947bca1e133736980c22754687874e3896f7d6d0a \  e9160bca1a531d871f5ecf51943d8cfb88833adeccf97701546b5fb93e030d79SERVER_TRAFFIC_SECRET_0 \  b2eb93b8ddab8c228993567947bca1e133736980c22754687874e3896f7d6d0a \  fb1120b91e48d402fac20faa33880e77bace82c85d6688df0aa99bf5084430e4EXPORTER_SECRET \  b2eb93b8ddab8c228993567947bca1e133736980c22754687874e3896f7d6d0a \  db1f4fa1a6942fb125d4cc47e02938b6f8030c6956bb81b9e3269f1cf855a8f8

Note that secrets from the two connections might be interleaved as shown here,because secrets could be logged as they are generated.¶

The following shows a log entry for a TLS 1.2 connection.¶

# NOTE: '\' line wrapping per RFC 8792CLIENT_RANDOM \  ad52329fcadd34ee3aa07092680287f09954823e26d7b5ae25c0d47714152a6a \  97af4c8618cfdc0b2326e590114c2ec04b43b08b7e2c3f8124cc61a3b068ba966\  9517e744e3117c3ce6c538a2d88dfdf

The following shows a log entry for a TLS 1.3 connection that successfullynegotiated ECH.¶

# NOTE: '\' line wrapping per RFC 8792ECH_SECRET \  0ba587ee6b65ce21a726630efb881206a7cd995611095b5f4c244bb2b23f1ee1 \  e8828ec09909cc9363179dc13b62498550c8637129345263011a1678370ca52aECH_CONFIG \  0ba587ee6b65ce21a726630efb881206a7cd995611095b5f4c244bb2b23f1ee1 \  fe0d003c5500200020d5260ae4cdda08bcbdc37bd0dc53c29aea5f0fdd2b2d594\  e4235e99b134ac904000400010001000d636f7665722e6465666f2e69650000CLIENT_HANDSHAKE_TRAFFIC_SECRET \  8726180bb24718089a4c5c8c93e0ea1c6d6649d7dd3c978fc1413854a20e9647 \  a195b63ec4270609692a204c08e63e74d9ae58e377d11a383bfe641a63c01140SERVER_HANDSHAKE_TRAFFIC_SECRET \  8726180bb24718089a4c5c8c93e0ea1c6d6649d7dd3c978fc1413854a20e9647 \  022d1cb827a90f27dadde0c99110c2b7d0f362fdfe420a04818aa223e5f2c14cCLIENT_TRAFFIC_SECRET_0 \  8726180bb24718089a4c5c8c93e0ea1c6d6649d7dd3c978fc1413854a20e9647 \  c2310f7db71109de88bab6f2f433fdc1704aecc0d57349cbf9113e5033178172SERVER_TRAFFIC_SECRET_0 \  8726180bb24718089a4c5c8c93e0ea1c6d6649d7dd3c978fc1413854a20e9647 \  04ffc7c154f71ba5f530c7344b0496f60ce71b9b7c6b0e203ea574bfcdf14e27EXPORTER_SECRET \  8726180bb24718089a4c5c8c93e0ea1c6d6649d7dd3c978fc1413854a20e9647 \  befb5db5ac6785b5dd4c6a8c4693c379ec0a1486b5fd035b25e50c3c95abc500

Acknowledgments

The SSLKEYLOGFILE format originated in the NSS project, but it has evolved overtime as TLS has changed. Many people contributed to this evolution. The authorsare only documenting the format as it is used while extending it to cover ECH.¶

Authors' Addresses