]> Mozilla

mt@lowentropy.net

Zscaler

yrosomakho@zscaler.com

University of Applied Sciences Bonn-Rhein-Sieg

Hannes.Tschofenig@gmx.net

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 . Status information for this document may be found at . Discussion of this document takes place on the Transport Layer Security Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction Debugging or analyzing protocols can be challenging when TLS 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 and TLS 1.3 . The format also supports earlier TLS versions, though use of earlier versions is strongly discouraged . This format can also be used with DTLS , QUIC , and other protocols that also use the TLS key schedule. Use of this format could complement other protocol-specific logging such as QLOG . This document also defines labels that can be used to log information about exchanges that use Encrypted Client Hello (ECH) .

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 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 . Though the format itself only includes ASCII characters , 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 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 ). If ECH was successfully negotiated for a given connection, these labels MUST be followed by the Random from the Inner ClientHello. Otherwise, the Random from the Outer ClientHello MUST be used. 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 .

These labels all appear in uppercase in the key log, but they correspond to lowercase labels in the TLS key schedule (), 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 , but there is no guarantee that implementations will log secrets strictly in this order.

Secret Labels for TLS 1.2 An implementation of TLS 1.2 (and also earlier versions) use the label "CLIENT_RANDOM" to identify the "master" secret for the connection.

Secret Labels for ECH With ECH , additional secrets are derived during the handshake to encrypt the Inner ClientHello message using Hybrid Public Key Encryption (HPKE) . A client can log the ECH labels described below if it offered ECH regardless of server acceptance. The server 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 ECH. These labels MUST always use the Random from the Outer ClientHello.

ECH_SECRET:

This label corresponds to the KEM shared secret used by HPKE (shared_secret in the algorithms in ). 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 value is logged in hexadecimal representation.

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 (). 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., ), authentication (e.g., ), 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 and Appendix of ) and some modes of TLS 1.2 (such as those in Sections and of ) 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. Access to the ECH_SECRET record in the SSLKEYLOGFILE allows the attacker to decrypt the 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 potential attack surface against the HPKE library since access to this keying material is normally not available otherwise.

IANA Considerations This document registers a media type () and creates a registry for labels ().

SSLKEYLOGFILE Media Type 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 .

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:

IETF

SSLKEYLOGFILE Labels Registry IANA is requested to create a new registry "SSLKEYLOGFILE Labels", within the existing "Transport Layer Security (TLS) Parameters" registry page. This new registry reserves labels used for SSLKEYLOGFILE entries. The initial contents of this registry are as follows.

Value	Description	Reference
CLIENT_RANDOM	Master secret in TLS 1.2 and earlier	This document
CLIENT_EARLY_TRAFFIC_SECRET	Secret for client early data records	This document
EARLY_EXPORTER_MASTER_SECRET	Early exporters secret	This document
CLIENT_HANDSHAKE_TRAFFIC_SECRET	Secret protecting client handshake	This document
SERVER_HANDSHAKE_TRAFFIC_SECRET	Secret protecting server handshake	This document
CLIENT_TRAFFIC_SECRET_0	Secret protecting client records post handshake	This document
SERVER_TRAFFIC_SECRET_0	Secret protecting server records post handshake	This document
EXPORTER_SECRET	Exporter secret after handshake	This document
ECH_SECRET	HPKE KEM shared secret used in the ECH	This document
ECH_CONFIG	ECHConfig used for construction of the ECH	This document

New assignments in the "SSLKEYLOGFILE Labels" registry will be administered by IANA through Specification Required procedure . The role of the designated expert is described in . The designated expert ensures that the specification is publicly available. It is sufficient to have an Internet-Draft (that is posted and never published as an RFC) or to cite a document from another standards body, industry consortium, or any other location. An expert may provide more in depth reviews, but their approval should not be taken as an endorsement of the SSLKEYLOGFILE label.

References Normative References Independent This document specifies version 1.3 of the Transport Layer Security (TLS) protocol. TLS allows client/server applications to communicate over the Internet in a way that is designed to prevent eavesdropping, tampering, and message forgery. This document updates RFCs 5705, 6066, 7627, and 8422 and obsoletes RFCs 5077, 5246, 6961, 8422, and 8446. This document also specifies new requirements for TLS 1.2 implementations. This document specifies Version 1.2 of the Transport Layer Security (TLS) protocol. The TLS protocol provides communications security over the Internet. The protocol allows client/server applications to communicate in a way that is designed to prevent eavesdropping, tampering, or message forgery. [STANDARDS-TRACK] Independent Fastly Cryptography Consulting LLC Cloudflare This document describes a mechanism in Transport Layer Security (TLS) for encrypting a ClientHello message under a server public key. Discussion Venues This note is to be removed before publishing as an RFC. Source for this draft and an issue tracker can be found at https://github.com/tlswg/draft-ietf-tls-esni (https://github.com/tlswg/draft-ietf-tls-esni). In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. ISO/IEC 10646-1 defines a large character set called the Universal Character Set (UCS) which encompasses most of the world's writing systems. The originally proposed encodings of the UCS, however, were not compatible with many current applications and protocols, and this has led to the development of UTF-8, the object of this memo. UTF-8 has the characteristic of preserving the full US-ASCII range, providing compatibility with file systems, parsers and other software that rely on US-ASCII values but are transparent to other values. This memo obsoletes and replaces RFC 2279. This document describes a scheme for hybrid public key encryption (HPKE). This scheme provides a variant of public key encryption of arbitrary-sized plaintexts for a recipient public key. It also includes three authenticated variants, including one that authenticates possession of a pre-shared key and two optional ones that authenticate possession of a key encapsulation mechanism (KEM) private key. HPKE works for any combination of an asymmetric KEM, key derivation function (KDF), and authenticated encryption with additional data (AEAD) encryption function. Some authenticated variants may not be supported by all KEMs. We provide instantiations of the scheme using widely used and efficient primitives, such as Elliptic Curve Diffie-Hellman (ECDH) key agreement, HMAC-based key derivation function (HKDF), and SHA2. This document is a product of the Crypto Forum Research Group (CFRG) in the IRTF. Informative References This document formally deprecates Transport Layer Security (TLS) versions 1.0 (RFC 2246) and 1.1 (RFC 4346). Accordingly, those documents have been moved to Historic status. These versions lack support for current and recommended cryptographic algorithms and mechanisms, and various government and industry profiles of applications using TLS now mandate avoiding these old TLS versions. TLS version 1.2 became the recommended version for IETF protocols in 2008 (subsequently being obsoleted by TLS version 1.3 in 2018), providing sufficient time to transition away from older versions. Removing support for older versions from implementations reduces the attack surface, reduces opportunity for misconfiguration, and streamlines library and product maintenance. This document also deprecates Datagram TLS (DTLS) version 1.0 (RFC 4347) but not DTLS version 1.2, and there is no DTLS version 1.1. This document updates many RFCs that normatively refer to TLS version 1.0 or TLS version 1.1, as described herein. This document also updates the best practices for TLS usage in RFC 7525; hence, it is part of BCP 195. Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) are used to protect data exchanged over a wide range of application protocols and can also form the basis for secure transport protocols. Over the years, the industry has witnessed several serious attacks on TLS and DTLS, including attacks on the most commonly used cipher suites and their modes of operation. This document provides the latest recommendations for ensuring the security of deployed services that use TLS and DTLS. These recommendations are applicable to the majority of use cases. RFC 7525, an earlier version of the TLS recommendations, was published when the industry was transitioning to TLS 1.2. Years later, this transition is largely complete, and TLS 1.3 is widely available. This document updates the guidance given the new environment and obsoletes RFC 7525. In addition, this document updates RFCs 5288 and 6066 in view of recent attacks. This document specifies version 1.3 of the Datagram Transport Layer Security (DTLS) protocol. DTLS 1.3 allows client/server applications to communicate over the Internet in a way that is designed to prevent eavesdropping, tampering, and message forgery. The DTLS 1.3 protocol is based on the Transport Layer Security (TLS) 1.3 protocol and provides equivalent security guarantees with the exception of order protection / non-replayability. Datagram semantics of the underlying transport are preserved by the DTLS protocol. This document obsoletes RFC 6347. This document defines the core of the QUIC transport protocol. QUIC provides applications with flow-controlled streams for structured communication, low-latency connection establishment, and network path migration. QUIC includes security measures that ensure confidentiality, integrity, and availability in a range of deployment circumstances. Accompanying documents describe the integration of TLS for key negotiation, loss detection, and an exemplary congestion control algorithm. This document describes how Transport Layer Security (TLS) is used to secure QUIC. Akamai Meta Cloudflare qlog provides extensible structured logging for network protocols, allowing for easy sharing of data that benefits common debug and analysis methods and tooling. This document describes key concepts of qlog: formats, files, traces, events, and extension points. This definition includes the high-level log file schemas, and generic event schemas. Requirements and guidelines for creating protocol- specific event schemas are also presented. All schemas are defined independent of serialization format, allowing logs to be represented in various ways such as JSON, CSV, or protobuf. Note to Readers Note to RFC editor: Please remove this section before publication. Feedback and discussion are welcome at https://github.com/quicwg/qlog (https://github.com/quicwg/qlog). Readers are advised to refer to the "editor's draft" at that URL for an up-to-date version of this document. Concrete examples of integrations of this schema in various programming languages can be found at https://github.com/quiclog/ qlog/ (https://github.com/quiclog/qlog/). This document describes a scheme for hybrid public key encryption (HPKE). This scheme provides a variant of public key encryption of arbitrary-sized plaintexts for a recipient public key. It also includes three authenticated variants, including one that authenticates possession of a pre-shared key and two optional ones that authenticate possession of a key encapsulation mechanism (KEM) private key. HPKE works for any combination of an asymmetric KEM, key derivation function (KDF), and authenticated encryption with additional data (AEAD) encryption function. Some authenticated variants may not be supported by all KEMs. We provide instantiations of the scheme using widely used and efficient primitives, such as Elliptic Curve Diffie-Hellman (ECDH) key agreement, HMAC-based key derivation function (HKDF), and SHA2. This document is a product of the Crypto Forum Research Group (CFRG) in the IRTF. This document specifies version 1.0 of the Token Binding protocol. The Token Binding protocol allows client/server applications to create long-lived, uniquely identifiable TLS bindings spanning multiple TLS sessions and connections. Applications are then enabled to cryptographically bind security tokens to the TLS layer, preventing token export and replay attacks. To protect privacy, the Token Binding identifiers are only conveyed over TLS and can be reset by the user at any time. This document describes a mechanism that builds on Transport Layer Security (TLS) or Datagram Transport Layer Security (DTLS) and enables peers to provide proof of ownership of an identity, such as an X.509 certificate. This proof can be exported by one peer, transmitted out of band to the other peer, and verified by the receiving peer. This document specifies version 1.3 of the Transport Layer Security (TLS) protocol. TLS allows client/server applications to communicate over the Internet in a way that is designed to prevent eavesdropping, tampering, and message forgery. This document updates RFCs 5705 and 6066, and obsoletes RFCs 5077, 5246, and 6961. This document also specifies new requirements for TLS 1.2 implementations. This document describes new key exchange algorithms based on Elliptic Curve Cryptography (ECC) for the Transport Layer Security (TLS) protocol. In particular, it specifies the use of Elliptic Curve Diffie-Hellman (ECDH) key agreement in a TLS handshake and the use of Elliptic Curve Digital Signature Algorithm (ECDSA) as a new authentication mechanism. This memo provides information for the Internet community. Many protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA). To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry. This is the third edition of this document; it obsoletes RFC 5226. This document describes a number of changes to TLS and DTLS IANA registries that range from adding notes to the registry all the way to changing the registration policy. These changes were mostly motivated by WG review of the TLS- and DTLS-related registries undertaken as part of the TLS 1.3 development process. This document updates the following RFCs: 3749, 5077, 4680, 5246, 5705, 5878, 6520, and 7301.

Example The following is a sample of a file in this format, including secrets from two TLS 1.3 connections. 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. The following shows a log entry for a TLS 1.3 connection that successfully negotiated ECH.

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 authors are only documenting the format as it is used while extending it to cover ECH.