rfc9850.original   rfc9850.txt 
Transport Layer Security M. Thomson Internet Engineering Task Force (IETF) M. Thomson
Internet-Draft Mozilla Request for Comments: 9850 Mozilla
Intended status: Informational Y. Rosomakho Category: Informational Y. Rosomakho
Expires: 11 December 2025 Zscaler ISSN: 2070-1721 Zscaler
H. Tschofenig H. Tschofenig
H-BRS H-BRS
9 June 2025 December 2025
The SSLKEYLOGFILE Format for TLS The SSLKEYLOGFILE Format for TLS
draft-ietf-tls-keylogfile-05
Abstract Abstract
A format that supports logging information about the secrets used in This document describes a format that supports logging information
a TLS connection is described. Recording secrets to a file in about the secrets used in a TLS connection. Recording secrets to a
SSLKEYLOGFILE format allows diagnostic and logging tools that use file in SSLKEYLOGFILE format allows diagnostic and logging tools that
this file to decrypt messages exchanged by TLS endpoints. This use this file to decrypt messages exchanged by TLS endpoints. This
format is intended for use in systems where TLS only protects test format is intended for use in systems where TLS only protects test
data. data.
About This Document
This note is to be removed before publishing as an RFC.
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.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This document is not an Internet Standards Track specification; it is
provisions of BCP 78 and BCP 79. published for informational purposes.
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 at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months This document is a product of the Internet Engineering Task Force
and may be updated, replaced, or obsoleted by other documents at any (IETF). It represents the consensus of the IETF community. It has
time. It is inappropriate to use Internet-Drafts as reference received public review and has been approved for publication by the
material or to cite them other than as "work in progress." Internet Engineering Steering Group (IESG). Not all documents
approved by the IESG are candidates for any level of Internet
Standard; see Section 2 of RFC 7841.
This Internet-Draft will expire on 11 December 2025. Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
https://www.rfc-editor.org/info/rfc9850.
Copyright Notice Copyright Notice
Copyright (c) 2025 IETF Trust and the persons identified as the Copyright (c) 2025 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/ Provisions Relating to IETF Documents
license-info) in effect on the date of publication of this document. (https://trustee.ietf.org/license-info) in effect on the date of
Please review these documents carefully, as they describe your rights publication of this document. Please review these documents
and restrictions with respect to this document. Code Components carefully, as they describe your rights and restrictions with respect
extracted from this document must include Revised BSD License text as to this document. Code Components extracted from this document must
described in Section 4.e of the Trust Legal Provisions and are include Revised BSD License text as described in Section 4.e of the
provided without warranty as described in the Revised BSD License. Trust Legal Provisions and are provided without warranty as described
in the Revised BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction
1.1. Applicability Statement . . . . . . . . . . . . . . . . . 3 1.1. Applicability Statement
1.2. Conventions and Definitions . . . . . . . . . . . . . . . 3 1.2. Conventions
2. The SSLKEYLOGFILE Format . . . . . . . . . . . . . . . . . . 4 2. The SSLKEYLOGFILE Format
2.1. Secret Labels for TLS 1.3 . . . . . . . . . . . . . . . . 5 2.1. Secret Labels for TLS 1.3
2.2. Secret Labels for TLS 1.2 . . . . . . . . . . . . . . . . 6 2.2. Secret Labels for TLS 1.2
2.3. Secret Labels for ECH . . . . . . . . . . . . . . . . . . 6 2.3. Secret Labels for ECH
3. Security Considerations . . . . . . . . . . . . . . . . . . . 6 3. Security Considerations
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 4. IANA Considerations
4.1. SSLKEYLOGFILE Media Type . . . . . . . . . . . . . . . . 8 4.1. SSLKEYLOGFILE Media Type
4.2. SSLKEYLOGFILE Labels Registry . . . . . . . . . . . . . . 9 4.2. TLS SSLKEYLOGFILE Labels Registry
5. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 5. References
5.1. Normative References . . . . . . . . . . . . . . . . . . 11 5.1. Normative References
5.2. Informative References . . . . . . . . . . . . . . . . . 11 5.2. Informative References
Appendix A. Example . . . . . . . . . . . . . . . . . . . . . . 13 Appendix A. Example
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 15 Acknowledgments
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 Authors' Addresses
1. Introduction 1. Introduction
Debugging or analyzing protocols can be challenging when TLS [TLS13] Debugging or analyzing protocols can be challenging when TLS [TLS13]
is used to protect the content of communications. Inspecting the is used to protect the content of communications. Inspecting the
content of encrypted messages in diagnostic tools can enable more content of encrypted messages in diagnostic tools can enable more
thorough analysis. thorough analysis.
Over time, multiple TLS implementations have informally adopted a Over time, multiple TLS implementations have informally adopted a
file format for logging the secret values generated by the TLS key file format for logging the secret values generated by the TLS key
schedule. In many implementations, the file that the secrets are schedule. In many implementations, the file that the secrets are
logged to is specified in an environment variable named logged to is specified in an environment variable named
"SSLKEYLOGFILE", hence the name of SSLKEYLOGFILE format. Note the "SSLKEYLOGFILE", hence the name of SSLKEYLOGFILE format. Note the
use of "SSL" as this convention originally predates the adoption of use of "SSL" as this convention originally predates the adoption of
TLS as the name of the protocol. TLS as the name of the protocol.
This document describes the SSLKEYLOGFILE format. This format can be This document describes the SSLKEYLOGFILE format. This format can be
used for TLS 1.2 [TLS12] and TLS 1.3 [TLS13]. The format also used for TLS 1.2 [TLS12] and TLS 1.3 [TLS13]. The format also
supports earlier TLS versions, though use of earlier versions is supports earlier TLS versions, though use of earlier versions is
strongly discouraged [RFC8996][RFC9325]. This format can also be strongly discouraged [RFC8996] [RFC9325]. This format can also be
used with DTLS [DTLS13], QUIC [RFC9000][RFC9001], and other protocols used with DTLS [DTLS13], QUIC [RFC9000] [RFC9001], and other
that also use the TLS key schedule. Use of this format could protocols that use the TLS key schedule. Use of this format could
complement other protocol-specific logging such as QLOG [QLOG]. complement other protocol-specific logging such as qlog [QLOG].
This document also defines labels that can be used to log information This document also defines labels that can be used to log information
about exchanges that use Encrypted Client Hello (ECH) [ECH]. about exchanges that use Encrypted Client Hello (ECH) [ECH].
1.1. Applicability Statement 1.1. Applicability Statement
The artifact that this document describes - if made available to The artifact that this document describes -- if made available to
entities other than endpoints - completely undermines the core entities other than endpoints -- completely undermines the core
guarantees that TLS provides. This format is intended for use in guarantees that TLS provides. This format is intended for use in
systems where TLS only protects test data. While the access that systems where TLS only protects test data. While the access that
this information provides to TLS connections can be useful for this information provides to TLS connections can be useful for
diagnosing problems while developing systems, this mechanism MUST NOT diagnosing problems while developing systems, this mechanism MUST NOT
be used in a production system. For software that is compiled, use be used in a production system. For software that is compiled, use
of conditional compilation is the best way to ensure that deployed of conditional compilation is the best way to ensure that deployed
binaries cannot be configured to enable key logging. binaries cannot be configured to enable key logging.
Section 3 addresses a number of additional concerns that arise from Section 3 addresses a number of additional concerns that arise from
the use of key logging. the use of key logging.
1.2. Conventions and Definitions 1.2. Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in "OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
2. The SSLKEYLOGFILE Format 2. The SSLKEYLOGFILE Format
A file in SSLKEYLOGFILE format is a text file. This document A file in SSLKEYLOGFILE format is a text file. This document
specifies the character encoding as UTF-8 [RFC3629]. Though the specifies the character encoding as UTF-8 [RFC3629]. Though the
format itself only includes ASCII characters [RFC0020], comments MAY format itself only includes ASCII characters [RFC0020], comments MAY
contain other characters. Though Unicode is permitted in comments, contain other characters. Though Unicode is permitted in comments,
the file MUST NOT contain a Unicode byte order mark (U+FEFF). the file MUST NOT contain a Unicode byte order mark (U+FEFF).
Lines are terminated using the line ending convention of the platform Lines are terminated using the line-ending convention of the platform
on which the file is generated. Tools that process these files MUST 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 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 line terminator. Lines are ignored if they are empty or if the first
character is an octothorpe character ('#', U+23). Other lines of the character is an octothorpe character ('#', U+23). Other lines of the
file each contain a single secret. file each contain a single secret.
Implementations that record secrets to a file do so continuously as Implementations that record secrets to a file do so continuously as
those secrets are generated. those secrets are generated.
Each secret is described using a single line composed of three values Each secret is described using a single line composed of three values
that are separated by a single space character (U+20). These values that are separated by a single space character (U+20). These values
are: are:
label: The label identifies the type of secret that is being label:
conveyed; see Section 2.1 for a description of the labels that are The label identifies the type of secret that is being conveyed;
defined in this document. see Section 2.1 for descriptions of the labels that are defined in
this document.
client_random: The 32-byte value of the Random field from the client_random:
ClientHello message that established the TLS connection. This The 32-byte value of the Random field from the ClientHello message
value is encoded as 64 hexadecimal characters. In a log that can that established the TLS connection. This value is encoded as 64
include secrets from multiple connections, this field can be used hexadecimal characters. In a log that can include secrets from
to identify a connection. multiple connections, this field can be used to identify a
connection.
secret: The value of the identified secret for the identified secret:
connection. This value is encoded in hexadecimal, with a length The value of the identified secret for the identified connection.
that depends on the size of the secret. 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 For the hexadecimal values of client_random or secret, no convention
convention exists for the case of characters 'a' through 'f' (or 'A' exists for the case of characters "a" through "f" (or "A" through
through 'F'). Files can be generated with either, so either form "F"). Files can be generated with either, so either form MUST be
MUST be accepted when processing a file. accepted when processing a file.
Diagnostic tools that accept files in this format might choose to Diagnostic tools that accept files in this format might choose to
ignore lines that do not conform to this format in the interest of ignore lines that do not conform to this format in the interest of
ensuring that secrets can be obtained from corrupted files. ensuring that secrets can be obtained from corrupted files.
Logged secret values are not annotated with the cipher suite or other Logged secret values are not annotated with the cipher suite or other
connection parameters. A record of the TLS handshake might therefore connection parameters. Therefore, a record of the TLS handshake
be needed to use the logged secrets. might be needed to use the logged secrets.
2.1. Secret Labels for TLS 1.3 2.1. Secret Labels for TLS 1.3
An implementation of TLS 1.3 produces a number of values as part of An implementation of TLS 1.3 produces a number of values as part of
the key schedule (see Section 7.1 of [TLS13]). If ECH was the key schedule (see Section 7.1 of [TLS13]). If ECH was
successfully negotiated for a given connection, these labels MUST be successfully negotiated for a given connection, these labels MUST be
followed by the Random from the Inner ClientHello. Otherwise, the followed by the Random from the Inner ClientHello. Otherwise, the
Random from the Outer ClientHello MUST be used. Random from the Outer ClientHello MUST be used.
Each of the following labels correspond to the equivalent secret Each of the following labels correspond to the equivalent secret
produced by the key schedule: produced by the key schedule:
CLIENT_EARLY_TRAFFIC_SECRET: CLIENT_EARLY_TRAFFIC_SECRET:
This secret is used to protect records sent by the client as early 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 data, if early data is attempted by the client. Note that a
server that rejects early data will not log this secret, though a server that rejects early data will not log this secret, though a
client that attempts early data can do so unconditionally. client that attempts early data can do so unconditionally.
EARLY_EXPORTER_SECRET: EARLY_EXPORTER_SECRET:
This secret is used for early exporters. Like the This secret is used for early exporters. Like
CLIENT_EARLY_TRAFFIC_SECRET, this is only generated when early 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 attempted and might not be logged by a server if early
data is rejected. data is rejected.
CLIENT_HANDSHAKE_TRAFFIC_SECRET: CLIENT_HANDSHAKE_TRAFFIC_SECRET:
This secret is used to protect handshake records sent by the This secret is used to protect handshake records sent by the
client. client.
SERVER_HANDSHAKE_TRAFFIC_SECRET: SERVER_HANDSHAKE_TRAFFIC_SECRET:
This secret is used to protect handshake records sent by the This secret is used to protect handshake records sent by the
skipping to change at page 5, line 49 skipping to change at line 217
is identified as client_application_traffic_secret_0 in the TLS is identified as client_application_traffic_secret_0 in the TLS
1.3 key schedule. 1.3 key schedule.
SERVER_TRAFFIC_SECRET_0: SERVER_TRAFFIC_SECRET_0:
This secret is used to protect application_data records sent by This secret is used to protect application_data records sent by
the server immediately after the handshake completes. This secret the server immediately after the handshake completes. This secret
is identified as server_application_traffic_secret_0 in the TLS is identified as server_application_traffic_secret_0 in the TLS
1.3 key schedule. 1.3 key schedule.
EXPORTER_SECRET: EXPORTER_SECRET:
This secret is used in generating exporters Section 7.5 of This secret is used in generating exporters (Section 7.5 of
[TLS13]. [TLS13]).
These labels all appear in uppercase in the key log, but they These labels all appear in uppercase in the key log, but they
correspond to lowercase labels in the TLS key schedule (Section 7.1 correspond to lowercase labels in the TLS key schedule (Section 7.1
of [TLS13]), except for the application data secrets as noted. For of [TLS13]), except for the application data secrets as noted. For
example, "EXPORTER_SECRET" in the log file corresponds to the secret example, "EXPORTER_SECRET" in the log file corresponds to the secret
named exporter_secret. named exporter_secret.
Note that the order that labels appear here corresponds to the order Note that the order that labels appear here corresponds to the order
in which they are presented in [TLS13], but there is no guarantee in which they are presented in [TLS13], but there is no guarantee
that implementations will log secrets strictly in this order. that implementations will log secrets strictly in this order.
skipping to change at page 6, line 26 skipping to change at line 241
Implementations of TLS 1.2 [TLS12] (and also earlier versions) use Implementations of TLS 1.2 [TLS12] (and also earlier versions) use
the label "CLIENT_RANDOM" to identify the "master" secret for the the label "CLIENT_RANDOM" to identify the "master" secret for the
connection. connection.
2.3. Secret Labels for ECH 2.3. Secret Labels for ECH
With ECH [ECH], additional secrets are derived during the handshake With ECH [ECH], additional secrets are derived during the handshake
to encrypt the Inner ClientHello message using Hybrid Public Key to encrypt the Inner ClientHello message using Hybrid Public Key
Encryption (HPKE) [HPKE]. A client can log the ECH labels described Encryption (HPKE) [HPKE]. A client can log the ECH labels described
below if it offered ECH regardless of server acceptance. The server below if it offered ECH, regardless of server acceptance. The server
can log the labels only if it successfully decrypted the ECH offered can log the labels only if it successfully decrypted the ECH offered
by the client, though it could choose to do so only when it accepts by the client, though it could choose to do so only when it accepts
ECH. ECH.
These labels MUST always use the Random from the Outer ClientHello. These labels MUST always use the Random from the Outer ClientHello.
ECH_SECRET: This label corresponds to the KEM shared secret used by ECH_SECRET:
HPKE (shared_secret in the algorithms in Section 5.1.1 of [HPKE]). This label corresponds to the Key Encapsulation Mechanism (KEM)
Length of the secret is defined by the KEM negotiated for use with shared secret used by HPKE (shared_secret in the algorithms in
ECH. Section 5.1.1 of [HPKE]). The length of the secret is defined by
the KEM negotiated for use with ECH.
ECH_CONFIG: The ECHConfig used to construct the ECH extension. The ECH_CONFIG:
value is logged in hexadecimal representation. The ECHConfig used to construct the ECH extension. The value is
logged in hexadecimal representation.
3. Security Considerations 3. Security Considerations
Access to the content of a file in SSLKEYLOGFILE format allows an Access to the content of a file in SSLKEYLOGFILE format allows an
attacker to break the confidentiality and integrity protection on any attacker to break the confidentiality and integrity protection on any
TLS connections that are included in the file. This includes both TLS connections that are included in the file. This includes both
active connections and connections for which encrypted records were active connections and connections for which encrypted records were
previously stored. Ensuring adequate access control on these files previously stored. Therefore, ensuring adequate access control on
therefore becomes very important. these files becomes very important.
Implementations that support logging this data need to ensure that Implementations that support logging this data need to ensure that
logging can only be enabled by those who are authorized. Allowing logging can only be enabled by those who are authorized. Allowing
logging to be initiated by any entity that is not otherwise logging to be initiated by any entity that is not otherwise
authorized to observe or modify the content of connections for which authorized to observe or modify the content of connections for which
secrets are logged could represent a privilege escalation attack. secrets are logged could represent a privilege escalation attack.
Implementations that enable logging also need to ensure that access Implementations that enable logging also need to ensure that access
to logged secrets is limited, using appropriate file permissions or to logged secrets is limited, using appropriate file permissions or
equivalent access control mechanisms. equivalent access control mechanisms.
skipping to change at page 7, line 33 skipping to change at line 299
bindings (e.g., [RFC8471]), authentication (e.g., [RFC9261]), or bindings (e.g., [RFC8471]), authentication (e.g., [RFC9261]), or
other derived secrets that are used in application context. An other derived secrets that are used in application context. An
adversary that obtains these secrets might be able to use this adversary that obtains these secrets might be able to use this
information to attack these applications. A TLS implementation might information to attack these applications. A TLS implementation might
either choose to omit these secrets in contexts where the information either choose to omit these secrets in contexts where the information
might be abused or require separate authorization to enable logging might be abused or require separate authorization to enable logging
of exporter secrets. of exporter secrets.
Using an environment variable, such as SSLKEYLOGFILE, to enable Using an environment variable, such as SSLKEYLOGFILE, to enable
logging implies that access to the launch context for the application logging implies that access to the launch context for the application
is needed to authorize logging. On systems that support specially- is needed to authorize logging. On systems that support specially
named files, logs might be directed to these names so that logging named files, logs might be directed to these names so that logging
does not result in storage, but enable consumption by other programs. does not result in storage but enables consumption by other programs.
In both cases, applications might require special authorization or In both cases, applications might require special authorization or
they might rely on system-level access control to limit access to might rely on system-level access control to limit access to these
these capabilities. capabilities.
Forward secrecy guarantees provided in TLS 1.3 (see Section 1.2 and 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 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 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 recorded. Access to key material allows an attacker to decrypt data
exchanged in any previously logged TLS connections. exchanged in any previously logged TLS connections.
Logging the TLS 1.2 "master" secret provides the recipient of that Logging the TLS 1.2 "master" secret provides the recipient of that
secret far greater access to an active connection than TLS 1.3 secret far greater access to an active connection than TLS 1.3
secrets. In addition to reading and altering protected messages, the secrets provide. In addition to reading and altering protected
TLS 1.2 "master" secret confers the ability to resume the connection messages, the TLS 1.2 "master" secret confers the ability to resume
and impersonate either endpoint, insert records that result in the connection and impersonate either endpoint, insert records that
renegotiation, and forge Finished messages. Implementations can result in renegotiation, and forge Finished messages.
avoid the risks associated with these capabilities by not logging Implementations can avoid the risks associated with these
this secret value. capabilities by not logging this secret value.
Access to the ECH_SECRET record in the SSLKEYLOGFILE allows the Access to the ECH_SECRET record in SSLKEYLOGFILE allows the attacker
attacker to decrypt the ECH extension and thereby reveal the content to decrypt the ECH extension and thereby reveal the content of the
of the Inner ClientHello message, including the payload of the Server Inner ClientHello message, including the payload of the Server Name
Name Indication (SNI) extension. Indication (SNI) extension.
Access to the HPKE-established shared secret used in ECH introduces a Access to the HPKE-established shared secret used in ECH introduces a
potential attack surface against the HPKE library since access to potential attack surface against the HPKE library since access to
this keying material is normally not available otherwise. this keying material is normally not available otherwise.
4. IANA Considerations 4. IANA Considerations
This document registers a media type (Section 4.1) and creates a This document registers a media type (Section 4.1) and creates a
registry for labels (Section 4.2). registry for labels (Section 4.2).
4.1. SSLKEYLOGFILE Media Type 4.1. SSLKEYLOGFILE Media Type
The "application/sslkeylogfile" media type can be used to describe The "application/sslkeylogfile" media type can be used to describe
content in the SSLKEYLOGFILE format. IANA [has added/is requested to content in the SSLKEYLOGFILE format. IANA has added the following
add] the following information to the "Media Types" registry at information to the "Media Types" registry at
https://www.iana.org/assignments/media-types <https://www.iana.org/assignments/media-types>:
(https://www.iana.org/assignments/media-types):
Type name: application Type name: application
Subtype name: sslkeylogfile Subtype name: sslkeylogfile
Required parameters: N/A Required parameters: N/A
Optional parameters: N/A Optional parameters: N/A
Encoding considerations: UTF-8 without BOM, or ASCII only Encoding considerations: UTF-8 without BOM, or ASCII only
Security considerations: See Section 3. Security considerations: See Section 3.
Interoperability considerations: Line endings might differ from Interoperability considerations: Line endings might differ from
platform convention platform convention.
Published specification: RFC XXXX (RFC Editor: please update)
Published specification: RFC 9850
Applications that use this media type: Diagnostic and analysis tools Applications that use this media type: Diagnostic and analysis tools
that need to decrypt data that is otherwise protected by TLS. that need to decrypt data that is otherwise protected by TLS.
Fragment identifier considerations: N/A Fragment identifier considerations: N/A
Additional information: Deprecated alias names for this type: N/A
Magic number(s): N/A Additional information:
File extension(s): N/A
Macintosh file type code(s): N/A Deprecated alias names for this type: N/A
Person & email address to contact for further information: TLS WG (t Magic number(s): N/A
ls@ietf.org) 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 Intended usage: COMMON
Restrictions on usage: N/A Restrictions on usage: N/A
Author: IETF TLS Working Group Author: IETF TLS Working Group
Change controller: IETF Change controller: IETF
4.2. SSLKEYLOGFILE Labels Registry 4.2. TLS SSLKEYLOGFILE Labels Registry
IANA is requested to create a new registry "TLS SSLKEYLOGFILE IANA has created a new registry named "TLS SSLKEYLOGFILE Labels"
Labels", within the existing "Transport Layer Security (TLS) within the existing "Transport Layer Security (TLS) Parameters"
Parameters" registry page. This new registry reserves labels used registry group. This new registry reserves labels used for
for SSLKEYLOGFILE entries. The initial contents of this registry are SSLKEYLOGFILE entries. The initial contents of this registry are as
as follows. follows:
+=================================+=====================+===========+ +=================================+=====================+===========+
| Value | Description | Reference | | Value | Description | Reference |
+=================================+=====================+===========+ +=================================+=====================+===========+
| CLIENT_RANDOM | Master secret in | This | | CLIENT_RANDOM | Master secret in | RFC 9850 |
| | TLS 1.2 and | document | | | TLS 1.2 and | |
| | earlier | | | | earlier | |
+---------------------------------+---------------------+-----------+ +---------------------------------+---------------------+-----------+
| CLIENT_EARLY_TRAFFIC_SECRET | Secret for client | This | | CLIENT_EARLY_TRAFFIC_SECRET | Secret for client | RFC 9850 |
| | early data | document | | | early data | |
| | records | | | | records | |
+---------------------------------+---------------------+-----------+ +---------------------------------+---------------------+-----------+
| EARLY_EXPORTER_SECRET | Early exporters | This | | EARLY_EXPORTER_SECRET | Early exporters | RFC 9850 |
| | secret | document | | | secret | |
+---------------------------------+---------------------+-----------+ +---------------------------------+---------------------+-----------+
| CLIENT_HANDSHAKE_TRAFFIC_SECRET | Secret protecting | This | | CLIENT_HANDSHAKE_TRAFFIC_SECRET | Secret protecting | RFC 9850 |
| | client handshake | document | | | client handshake | |
+---------------------------------+---------------------+-----------+ +---------------------------------+---------------------+-----------+
| SERVER_HANDSHAKE_TRAFFIC_SECRET | Secret protecting | This | | SERVER_HANDSHAKE_TRAFFIC_SECRET | Secret protecting | RFC 9850 |
| | server handshake | document | | | server handshake | |
+---------------------------------+---------------------+-----------+ +---------------------------------+---------------------+-----------+
| CLIENT_TRAFFIC_SECRET_0 | Secret protecting | This | | CLIENT_TRAFFIC_SECRET_0 | Secret protecting | RFC 9850 |
| | client records | document | | | client records | |
| | post handshake | | | | post handshake | |
+---------------------------------+---------------------+-----------+ +---------------------------------+---------------------+-----------+
| SERVER_TRAFFIC_SECRET_0 | Secret protecting | This | | SERVER_TRAFFIC_SECRET_0 | Secret protecting | RFC 9850 |
| | server records | document | | | server records | |
| | post handshake | | | | post handshake | |
+---------------------------------+---------------------+-----------+ +---------------------------------+---------------------+-----------+
| EXPORTER_SECRET | Exporter secret | This | | EXPORTER_SECRET | Exporter secret | RFC 9850 |
| | after handshake | document | | | after handshake | |
+---------------------------------+---------------------+-----------+ +---------------------------------+---------------------+-----------+
| ECH_SECRET | HPKE KEM shared | This | | ECH_SECRET | HPKE KEM shared | RFC 9850 |
| | secret used in | document | | | secret used in | |
| | the ECH | | | | the ECH | |
+---------------------------------+---------------------+-----------+ +---------------------------------+---------------------+-----------+
| ECH_CONFIG | ECHConfig used | This | | ECH_CONFIG | ECHConfig used | RFC 9850 |
| | for construction | document | | | for construction | |
| | of the ECH | | | | of the ECH | |
+---------------------------------+---------------------+-----------+ +---------------------------------+---------------------+-----------+
Table 1 Table 1
New assignments in the "SSLKEYLOGFILE Labels" registry will be New assignments in the "TLS SSLKEYLOGFILE Labels" registry will be
administered by IANA through Specification Required procedure administered by IANA through the Specification Required procedure
[RFC8126]. The role of the designated expert is described in [RFC8126]. The role of the designated expert is described in
Section 17 of [RFC8447]. The designated expert [RFC8126] ensures Section 17 of [RFC8447]. The designated expert [RFC8126] ensures
that the specification is publicly available. It is sufficient to that the specification is publicly available. In the Reference
have an Internet-Draft (that is posted and never published as an RFC) column, it is sufficient to cite an Internet-Draft (that is posted
or to cite a document from another standards body, industry but not published as an RFC) or a document from another standards
consortium, or any other location. An expert may provide more in- body, an industry consortium, or any other location. The designated
depth reviews, but their approval should not be taken as an expert may provide more in-depth reviews, but their approval should
endorsement of the SSLKEYLOGFILE label. not be taken as an endorsement of the SSLKEYLOGFILE label.
5. References 5. References
5.1. Normative References 5.1. Normative References
[ECH] Rescorla, E., Oku, K., Sullivan, N., and C. A. Wood, "TLS [ECH] Rescorla, E., Oku, K., Sullivan, N., and C. A. Wood, "TLS
Encrypted Client Hello", Work in Progress, Internet-Draft, Encrypted Client Hello", RFC 9849, DOI 10.17487/RFC9849,
draft-ietf-tls-esni-24, 20 March 2025, December 2025, <https://www.rfc-editor.org/info/rfc9849>.
<https://datatracker.ietf.org/doc/html/draft-ietf-tls-
esni-24>.
[HPKE] Barnes, R., Bhargavan, K., Lipp, B., and C. Wood, "Hybrid [HPKE] Barnes, R., Bhargavan, K., Lipp, B., and C. Wood, "Hybrid
Public Key Encryption", RFC 9180, DOI 10.17487/RFC9180, Public Key Encryption", RFC 9180, DOI 10.17487/RFC9180,
February 2022, <https://www.rfc-editor.org/rfc/rfc9180>. February 2022, <https://www.rfc-editor.org/info/rfc9180>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/rfc/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
2003, <https://www.rfc-editor.org/rfc/rfc3629>. 2003, <https://www.rfc-editor.org/info/rfc3629>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/rfc/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[TLS12] Dierks, T. and E. Rescorla, "The Transport Layer Security [TLS12] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, (TLS) Protocol Version 1.2", RFC 5246,
DOI 10.17487/RFC5246, August 2008, DOI 10.17487/RFC5246, August 2008,
<https://www.rfc-editor.org/rfc/rfc5246>. <https://www.rfc-editor.org/info/rfc5246>.
[TLS13] Rescorla, E., "The Transport Layer Security (TLS) Protocol [TLS13] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", Work in Progress, Internet-Draft, draft- Version 1.3", RFC 9846, DOI 10.17487/RFC9846, December
ietf-tls-rfc8446bis-12, 17 February 2025, 2025, <https://www.rfc-editor.org/info/rfc9846>.
<https://datatracker.ietf.org/doc/html/draft-ietf-tls-
rfc8446bis-12>.
5.2. Informative References 5.2. Informative References
[DTLS13] Rescorla, E., Tschofenig, H., and N. Modadugu, "The [DTLS13] Rescorla, E., Tschofenig, H., and N. Modadugu, "The
Datagram Transport Layer Security (DTLS) Protocol Version Datagram Transport Layer Security (DTLS) Protocol Version
1.3", RFC 9147, DOI 10.17487/RFC9147, April 2022, 1.3", RFC 9147, DOI 10.17487/RFC9147, April 2022,
<https://www.rfc-editor.org/rfc/rfc9147>. <https://www.rfc-editor.org/info/rfc9147>.
[QLOG] Marx, R., Niccolini, L., Seemann, M., and L. Pardue, [QLOG] Marx, R., Ed., Niccolini, L., Ed., Seemann, M., Ed., and
"qlog: Structured Logging for Network Protocols", Work in L. Pardue, Ed., "qlog: Structured Logging for Network
Progress, Internet-Draft, draft-ietf-quic-qlog-main- Protocols", Work in Progress, Internet-Draft, draft-ietf-
schema-11, 17 March 2025, quic-qlog-main-schema-13, 20 October 2025,
<https://datatracker.ietf.org/doc/html/draft-ietf-quic- <https://datatracker.ietf.org/doc/html/draft-ietf-quic-
qlog-main-schema-11>. qlog-main-schema-13>.
[RFC0020] Cerf, V., "ASCII format for network interchange", STD 80, [RFC0020] Cerf, V., "ASCII format for network interchange", STD 80,
RFC 20, DOI 10.17487/RFC0020, October 1969, RFC 20, DOI 10.17487/RFC0020, October 1969,
<https://www.rfc-editor.org/rfc/rfc20>. <https://www.rfc-editor.org/info/rfc20>.
[RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B.
Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites
for Transport Layer Security (TLS)", RFC 4492, for Transport Layer Security (TLS)", RFC 4492,
DOI 10.17487/RFC4492, May 2006, DOI 10.17487/RFC4492, May 2006,
<https://www.rfc-editor.org/rfc/rfc4492>. <https://www.rfc-editor.org/info/rfc4492>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26, Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017, RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/rfc/rfc8126>. <https://www.rfc-editor.org/info/rfc8126>.
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
<https://www.rfc-editor.org/rfc/rfc8446>. <https://www.rfc-editor.org/info/rfc8446>.
[RFC8447] Salowey, J. and S. Turner, "IANA Registry Updates for TLS [RFC8447] Salowey, J. and S. Turner, "IANA Registry Updates for TLS
and DTLS", RFC 8447, DOI 10.17487/RFC8447, August 2018, and DTLS", RFC 8447, DOI 10.17487/RFC8447, August 2018,
<https://www.rfc-editor.org/rfc/rfc8447>. <https://www.rfc-editor.org/info/rfc8447>.
[RFC8471] Popov, A., Ed., Nystroem, M., Balfanz, D., and J. Hodges, [RFC8471] Popov, A., Ed., Nystroem, M., Balfanz, D., and J. Hodges,
"The Token Binding Protocol Version 1.0", RFC 8471, "The Token Binding Protocol Version 1.0", RFC 8471,
DOI 10.17487/RFC8471, October 2018, DOI 10.17487/RFC8471, October 2018,
<https://www.rfc-editor.org/rfc/rfc8471>. <https://www.rfc-editor.org/info/rfc8471>.
[RFC8792] Watsen, K., Auerswald, E., Farrel, A., and Q. Wu, [RFC8792] Watsen, K., Auerswald, E., Farrel, A., and Q. Wu,
"Handling Long Lines in Content of Internet-Drafts and "Handling Long Lines in Content of Internet-Drafts and
RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020, RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020,
<https://www.rfc-editor.org/rfc/rfc8792>. <https://www.rfc-editor.org/info/rfc8792>.
[RFC8996] Moriarty, K. and S. Farrell, "Deprecating TLS 1.0 and TLS [RFC8996] Moriarty, K. and S. Farrell, "Deprecating TLS 1.0 and TLS
1.1", BCP 195, RFC 8996, DOI 10.17487/RFC8996, March 2021, 1.1", BCP 195, RFC 8996, DOI 10.17487/RFC8996, March 2021,
<https://www.rfc-editor.org/rfc/rfc8996>. <https://www.rfc-editor.org/info/rfc8996>.
[RFC9000] Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based [RFC9000] Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based
Multiplexed and Secure Transport", RFC 9000, Multiplexed and Secure Transport", RFC 9000,
DOI 10.17487/RFC9000, May 2021, DOI 10.17487/RFC9000, May 2021,
<https://www.rfc-editor.org/rfc/rfc9000>. <https://www.rfc-editor.org/info/rfc9000>.
[RFC9001] Thomson, M., Ed. and S. Turner, Ed., "Using TLS to Secure [RFC9001] Thomson, M., Ed. and S. Turner, Ed., "Using TLS to Secure
QUIC", RFC 9001, DOI 10.17487/RFC9001, May 2021, QUIC", RFC 9001, DOI 10.17487/RFC9001, May 2021,
<https://www.rfc-editor.org/rfc/rfc9001>. <https://www.rfc-editor.org/info/rfc9001>.
[RFC9261] Sullivan, N., "Exported Authenticators in TLS", RFC 9261, [RFC9261] Sullivan, N., "Exported Authenticators in TLS", RFC 9261,
DOI 10.17487/RFC9261, July 2022, DOI 10.17487/RFC9261, July 2022,
<https://www.rfc-editor.org/rfc/rfc9261>. <https://www.rfc-editor.org/info/rfc9261>.
[RFC9325] Sheffer, Y., Saint-Andre, P., and T. Fossati, [RFC9325] Sheffer, Y., Saint-Andre, P., and T. Fossati,
"Recommendations for Secure Use of Transport Layer "Recommendations for Secure Use of Transport Layer
Security (TLS) and Datagram Transport Layer Security Security (TLS) and Datagram Transport Layer Security
(DTLS)", BCP 195, RFC 9325, DOI 10.17487/RFC9325, November (DTLS)", BCP 195, RFC 9325, DOI 10.17487/RFC9325, November
2022, <https://www.rfc-editor.org/rfc/rfc9325>. 2022, <https://www.rfc-editor.org/info/rfc9325>.
Appendix A. Example Appendix A. Example
The following is a sample of a file in this format, including secrets The following is a sample of a file in SSLKEYLOGFILE format,
from two TLS 1.3 connections. including secrets from two TLS 1.3 connections.
# NOTE: '\' line wrapping per RFC 8792 # NOTE: '\' line wrapping per RFC 8792
CLIENT_HANDSHAKE_TRAFFIC_SECRET \ CLIENT_HANDSHAKE_TRAFFIC_SECRET \
cf34899b3dcb8c9fe7160ceaf95d354a294793b67a2e49cb9cca4d69b43593a0 \ cf34899b3dcb8c9fe7160ceaf95d354a294793b67a2e49cb9cca4d69b43593a0 \
be4a28d81ce41242ff31c6d8a6615852178f2cd75eaca2ee8768f9ed51282b38 be4a28d81ce41242ff31c6d8a6615852178f2cd75eaca2ee8768f9ed51282b38
SERVER_HANDSHAKE_TRAFFIC_SECRET \ SERVER_HANDSHAKE_TRAFFIC_SECRET \
cf34899b3dcb8c9fe7160ceaf95d354a294793b67a2e49cb9cca4d69b43593a0 \ cf34899b3dcb8c9fe7160ceaf95d354a294793b67a2e49cb9cca4d69b43593a0 \
258179721fa704e2f1ee16688b4b0419967ddea5624cd5ad0863288dc5ead35f 258179721fa704e2f1ee16688b4b0419967ddea5624cd5ad0863288dc5ead35f
CLIENT_HANDSHAKE_TRAFFIC_SECRET \ CLIENT_HANDSHAKE_TRAFFIC_SECRET \
skipping to change at page 15, line 32 skipping to change at line 627
c2310f7db71109de88bab6f2f433fdc1704aecc0d57349cbf9113e5033178172 c2310f7db71109de88bab6f2f433fdc1704aecc0d57349cbf9113e5033178172
SERVER_TRAFFIC_SECRET_0 \ SERVER_TRAFFIC_SECRET_0 \
8726180bb24718089a4c5c8c93e0ea1c6d6649d7dd3c978fc1413854a20e9647 \ 8726180bb24718089a4c5c8c93e0ea1c6d6649d7dd3c978fc1413854a20e9647 \
04ffc7c154f71ba5f530c7344b0496f60ce71b9b7c6b0e203ea574bfcdf14e27 04ffc7c154f71ba5f530c7344b0496f60ce71b9b7c6b0e203ea574bfcdf14e27
EXPORTER_SECRET \ EXPORTER_SECRET \
8726180bb24718089a4c5c8c93e0ea1c6d6649d7dd3c978fc1413854a20e9647 \ 8726180bb24718089a4c5c8c93e0ea1c6d6649d7dd3c978fc1413854a20e9647 \
befb5db5ac6785b5dd4c6a8c4693c379ec0a1486b5fd035b25e50c3c95abc500 befb5db5ac6785b5dd4c6a8c4693c379ec0a1486b5fd035b25e50c3c95abc500
Acknowledgments Acknowledgments
The SSLKEYLOGFILE format originated in the NSS project, but it has The SSLKEYLOGFILE format originated in the Network Security Services
evolved over time as TLS has changed. Many people contributed to (NSS) project, but it has evolved over time as TLS has changed. Many
this evolution. The authors are only documenting the format as it is people contributed to this evolution. The authors are only
used while extending it to cover ECH. documenting the format as it is used while extending it to cover ECH.
Authors' Addresses Authors' Addresses
Martin Thomson Martin Thomson
Mozilla Mozilla
Email: mt@lowentropy.net Email: mt@lowentropy.net
Yaroslav Rosomakho Yaroslav Rosomakho
Zscaler Zscaler
Email: yrosomakho@zscaler.com Email: yrosomakho@zscaler.com
 End of changes. 81 change blocks. 
197 lines changed or deleted 196 lines changed or added

This html diff was produced by rfcdiff 1.48.