The SSLKEYLOGFILE Format for TLS

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 at https://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 27 April 2023.¶

Copyright Notice

Copyright (c) 2022 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 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 strongly discouraged [RFC8996]. This format can also be used with the corresponding DTLS version [DTLS13] and QUIC [RFC9000][RFC9001], which use the TLS key schedule.¶

2. 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.¶

3. 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. Lines are ignored if they are empty or if the first character with an octothorp character ('#', U+23). Other lines of the file each contain a single secret.¶

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 3.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.¶

4. Security Considerations

Access to the content of a file in SSLKEYLOGFILE allows an attacker to break the confidentiality 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 that depend on TLS generate 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 to require separate authorization to enable logging of exporter secrets.¶

Logging the TLS 1.2 "master" secret provides the recipient of a file in SSLKEYLOGFILE far greater access to an active connection. This can include the ability to resume the connection and impersonate either endpoint, insert records that result in renegotiation, or even forge Finished messages. Implementations might avoid these risks by not logging this secret value.¶

5. 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:

8bit (Unicode without BOM or ASCII only)¶

Security considerations:

See Section 4.¶

Interoperability considerations:

Line endings might differ from platform convention¶

Published specification:

This document¶

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:

See the Authors' Addresses section.¶

Intended usage:

COMMON¶

Restrictions on usage:

N/A¶

Author:

See the Authors' Addresses section.¶

Change controller:

IESG¶

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.¶

Author's Address