The SSLKEYLOGFILE Format for TLS
Internet-Draft draft-ietf-tls-keylogfile-02
Martin Thomson
Mozilla
mt@lowentropy.net
30 April 2024
Security
Transport Layer Security
network transparency
tls
blockchain
A format that supports the logging information about the secrets used in a TLS connection is described. Recording secrets to a file in SSLKEYLOGFILE format allows diagnostic and logging tools that use this file to decrypt messages exchanged by TLS endpoints.
About This Document
The latest revision of this draft can be found at https://tlswg.github.io/sslkeylogfile/draft-ietf-tls-keylogfile.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-ietf-tls-keylogfile/.
Discussion of this document takes place on the Transport Layer Security Working Group mailing list (mailto:tls@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/tls/. Subscribe at https://www.ietf.org/mailman/listinfo/tls/.
Source for this draft and an issue tracker can be found at https://github.com/tlswg/sslkeylogfile.
Introduction
Debugging or analyzing protocols can be challenging when TLS [TLS13] is used to protect the content of communications. Inspecting the content of encrypted messages in diagnostic tools can enable more thorough analysis.
Over time, multiple TLS implementations have informally adopted a file format that logging the secret values generated by the TLS key schedule. In many implementations, the file that the secrets are logged to is specified in an environment variable named "SSLKEYLOGFILE", hence the name of SSLKEYLOGFILE format. Note the use of "SSL" as this convention originally predates the adoption of TLS as the name of the protocol.
This document describes the SSLKEYLOGFILE format. This format can be used for TLS 1.2 [TLS12] and TLS 1.3 [TLS13]. The format also supports earlier TLS versions, though use of earlier versions is forbidden [RFC8996]. This format can also be used with DTLS [DTLS13], QUIC [RFC9000][RFC9001], and other protocols that also use the TLS key schedule. Use of this format could complement other protocol-specific logging such as QLOG [QLOG].
Applicability Statement
The artifact that this document describes - if made available to entities other than endpoints - completely undermines the core guarantees that TLS provides. This format is intended for use in systems where TLS only protects test data. While the access that this information provides to TLS connections can be useful for diagnosing problems while developing systems, this mechanism MUST NOT be used in a production system.
Conventions and Definitions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
The SSLKEYLOGFILE Format
A file in SSLKEYLOGFILE format is a text file. This document specifies the character encoding as UTF-8 [RFC3629]. Though the format itself only includes ASCII characters [RFC0020], comments MAY contain other characters. Though Unicode is permitted in comments, the file MUST NOT contain a Unicode byte order mark (U+FEFF).
Lines are terminated using the line ending convention of the platform on which 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 are empty or if the first character is an octothorp character ('#', U+23). Other lines of the file each contain a single secret.
Implementations that record secrets to a file do so continuously as those secrets are generated.
Each secret is described using a single line composed of three values that are separated by a single space character (U+20). These values are:
label:
The label identifies the type of secret that is being conveyed; see Section 2.1 for 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 that established the TLS connection. This value is encoded as 64 hexadecimal characters. Including this field allows a single file to include secrets from multiple connections and for the secrets to be applied to the correct connection, though this depends on being able to match records to the correct ClientHello message.
secret:
The value of the identified secret for the identified connection. This value is encoded in hexadecimal, with a length that depends on the size of the secret.
For the hexadecimal values of the client_random or secret, no convention exists for the case of characters 'a' through 'f' (or 'A' through 'F'). Files can be generated with either, so either form MUST be accepted when processing a file.
Diagnostic tools that accept files in this format might choose to ignore lines that do not conform to this format in the interest of ensuring that secrets can be obtained from corrupted files.
Logged secret values are not annotated with the cipher suite or other connection parameters. A record of the TLS handshake might therefore be needed to use the logged secrets.
Secret Labels for TLS 1.3
An implementation of TLS 1.3 produces a number of values as part of the key schedule (see Section 7.1 of [TLS13]). Each of the following labels correspond to the equivalent secret produced by the key schedule:
CLIENT_EARLY_TRAFFIC_SECRET:
This secret is used to protect records sent by the client as early data, if early data is attempted by the client. Note that a server that rejects early data will not log this secret, though a client that attempts early data can do so unconditionally.
EARLY_EXPORTER_MASTER_SECRET:
This secret is used for early exporters. Like the CLIENT_EARLY_TRAFFIC_SECRET, this is only generated when early data is attempted and might not be logged by a server if early data is rejected.
CLIENT_HANDSHAKE_TRAFFIC_SECRET:
This secret is used to protect handshake records sent by the client.
SERVER_HANDSHAKE_TRAFFIC_SECRET:
This secret is used to protect handshake records sent by the server.
CLIENT_TRAFFIC_SECRET_0:
This secret is used to protect application_data records sent by the client immediately after the handshake completes. This secret is identified as client_application_traffic_secret_0 in the TLS 1.3 key schedule.
SERVER_TRAFFIC_SECRET_0:
This secret is used to protect application_data records sent by the server immediately after the handshake completes. This secret is identified as server_application_traffic_secret_0 in the TLS 1.3 key schedule.
EXPORTER_SECRET:
This secret is used in generating exporters Section 7.5 of [TLS13].
These labels all appear in uppercase in the key log, but they correspond to 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 file corresponds to the secret named exporter_secret.
Note that the order that labels appear here corresponds to the order in which they are presented in [TLS13], but there is no guarantee that implementations will log secrets strictly in this order.
Key updates (Section 7.2 of [TLS13]) result in new secrets being generated for protecting application_data records. The label used for these secrets comprises a base label of "CLIENT_TRAFFIC_SECRET_" for a client or "SERVER_TRAFFIC_SECRET_" for a server, plus the decimal value of a counter. This counter identifies the number of key updates that occurred to produce this secret. This counter starts at 0, which produces the first application data traffic secret, as above. Note that with knowledge of "_TRAFFIC_SECRET_N", all subsequent application data traffic secret can be derived without any additional information.
Secret Labels for TLS 1.2
An implementation of TLS 1.2 [TLS12] (and also earlier versions) use the label "CLIENT_RANDOM" to identify the "master" secret for the connection.
Security Considerations
Access to the content of a file in SSLKEYLOGFILE format allows an attacker to break the confidentiality and integrity protection on any TLS connections that are included in the file. This includes both active connections and connections for which encrypted records were previously stored. Ensuring adequate access control on these files therefore becomes very important.
Implementations that support logging this data need to ensure that logging can only be enabled by those who are authorized. Allowing logging to be initiated by any entity that is not otherwise authorized to observe or modify the content of connections for which secrets are logged could represent a privilege escalation attack. Implementations that enable logging also need to ensure that access to logged secrets is limited, using appropriate file permissions or equivalent access control mechanisms.
In order to support decryption, the secrets necessary to remove record protection are logged. However, as the keys that can be derived from these secrets are symmetric, an adversary with access to these secrets is also able to encrypt data for an active connection. This might allow for injection or modification of application data on a connection that would otherwise be protected by TLS.
As some protocols rely on TLS for generating encryption keys, the SSLKEYLOGFILE format includes keys that identify the secret used in TLS exporters or early exporters (Section 7.5 of [TLS13]. Knowledge of these secrets can enable more than inspection or modification of encrypted data, depending on how an application protocol uses exporters. For instance, exporters might be used for session bindings (e.g., [RFC8471]), authentication (e.g., [RFC9261]), or other derived secrets that are used in application context. An adversary that obtains these secrets might be able to use this information to attack these applications. A TLS implementation might either choose to omit these secrets in contexts where the information might be abused or require separate authorization to enable logging of exporter secrets.
Using an environment variable, such as SSLKEYLOGFILE, to enable logging implies that access to the launch context for the application is needed to authorize logging. On systems that support specially-named files, logs might be directed to these names so that logging does not result in storage, but enable consumption by other programs. In both cases, applications might require special authorization or they might rely on system-level access control to limit access to these capabilities.
Forward secrecy guarantees provided in TLS 1.3 (see Section 1.2 and Appendix E.1 of [RFC8446]) and some modes of TLS 1.2 (such as those in Sections 2.2 and 2.4 of [RFC4492]) do not hold if key material is recorded. Access to key material allows an attacker to decrypt data exchanged in any previously logged TLS connections.
Logging the TLS 1.2 "master" secret provides the recipient of that secret far greater access to an active connection than TLS 1.3 secrets. In addition to reading and altering protected messages, the TLS 1.2 "master" secret confers the ability to resume the connection and impersonate either endpoint, insert records that result in renegotiation, and forge Finished messages. Implementations can avoid the risks associated with these capabilities by not logging this secret value.
IANA Considerations
The "application/sslkeylogfile" media type can be used to describe content in the SSLKEYLOGFILE format. IANA [has added/is requested to add] the following information 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 XXXX (RFC Editor: please update)
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:
IESG
References
Normative References
[TLS13]

The Transport Layer Security (TLS) Protocol Version 1.3
Eric Rescorla
Windy Hill Systems, LLC
3 March 2024
Internet-Draft draft-ietf-tls-rfc8446bis-10
[TLS12]

The Transport Layer Security (TLS) Protocol Version 1.2
T. Dierks
E. Rescorla
August 2008
RFC 5246
DOI 10.17487/RFC5246
[RFC2119]

Key words for use in RFCs to Indicate Requirement Levels
S. Bradner
March 1997
BCP 14
RFC 2119
DOI 10.17487/RFC2119
[RFC8174]

Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words
B. Leiba
May 2017
BCP 14
RFC 8174
DOI 10.17487/RFC8174
[RFC3629]

UTF-8, a transformation format of ISO 10646
F. Yergeau
November 2003
STD 63
RFC 3629
DOI 10.17487/RFC3629
Informative References
[RFC8996]

Deprecating TLS 1.0 and TLS 1.1
K. Moriarty
S. Farrell
March 2021
BCP 195
RFC 8996
DOI 10.17487/RFC8996
[DTLS13]

The Datagram Transport Layer Security (DTLS) Protocol Version 1.3
E. Rescorla
H. Tschofenig
N. Modadugu
April 2022
RFC 9147
DOI 10.17487/RFC9147
[RFC9000]

QUIC: A UDP-Based Multiplexed and Secure Transport
J. Iyengar, Ed.
M. Thomson, Ed.
May 2021
RFC 9000
DOI 10.17487/RFC9000
[RFC9001]

Using TLS to Secure QUIC
M. Thomson, Ed.
S. Turner, Ed.
May 2021
RFC 9001
DOI 10.17487/RFC9001
[QLOG]

Main logging schema for qlog
Robin Marx
Akamai
Luca Niccolini
Meta
Marten Seemann
Lucas Pardue
Cloudflare
4 March 2024
Internet-Draft draft-ietf-quic-qlog-main-schema-08
[RFC0020]

ASCII format for network interchange
V.G. Cerf
October 1969
STD 80
RFC 20
DOI 10.17487/RFC0020
[RFC8471]

The Token Binding Protocol Version 1.0
A. Popov, Ed.
M. Nystroem
D. Balfanz
J. Hodges
October 2018
RFC 8471
DOI 10.17487/RFC8471
[RFC9261]

Exported Authenticators in TLS
N. Sullivan
July 2022
RFC 9261
DOI 10.17487/RFC9261
[RFC8446]

The Transport Layer Security (TLS) Protocol Version 1.3
E. Rescorla
August 2018
RFC 8446
DOI 10.17487/RFC8446
[RFC4492]

Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS)
S. Blake-Wilson
N. Bolyard
V. Gupta
C. Hawk
B. Moeller
May 2006
RFC 4492
DOI 10.17487/RFC4492
Example
The following is a sample of a file in this format, including secrets from two TLS 1.3 connections.

# NOTE: '\' line wrapping per RFC 8792

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

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 8792

CLIENT_RANDOM \
  ad52329fcadd34ee3aa07092680287f09954823e26d7b5ae25c0d47714152a6a \
  97af4c8618cfdc0b2326e590114c2ec04b43b08b7e2c3f8124cc61a3b068ba966\
  9517e744e3117c3ce6c538a2d88dfdf

Acknowledgments
The SSLKEYLOGFILE format originated in the NSS project, but it has evolved over time as TLS has changed. Many people contributed to this evolution. The author is only documenting the format as it is used.