diff --git a/index.html b/index.html index 0651dd6..3a41bdd 100644 --- a/index.html +++ b/index.html @@ -24,6 +24,14 @@

Editor's drafts for main branch of fs-break

+ + + + + + +
SSLKEYLOGFILEplain textdiff with main

Preview for branch draft-ietf-tls-keylogfile-01

@@ -32,12 +40,12 @@

Preview for branch draft-ietf-tls-key

same as main
-

Preview for branch fs-break

- +

Preview for branch multiple-connections

+
- - - + + +
SSLKEYLOGFILEplain textdiff with mainSSLKEYLOGFILEplain textdiff with main

Preview for branch seanturner-cluster-time

diff --git a/multiple-connections/draft-ietf-tls-keylogfile.html b/multiple-connections/draft-ietf-tls-keylogfile.html new file mode 100644 index 0000000..276160a --- /dev/null +++ b/multiple-connections/draft-ietf-tls-keylogfile.html @@ -0,0 +1,1712 @@ + + + + + + +The SSLKEYLOGFILE Format for TLS + + + + + + + + + + + + + + + + + + + + + + + + + +
Internet-DraftSSLKEYLOGFILEApril 2024
ThomsonExpires 7 October 2024[Page]
+
+
+
+
Workgroup:
+
Transport Layer Security
+
Internet-Draft:
+
draft-ietf-tls-keylogfile-latest
+
Published:
+
+ +
+
Intended Status:
+
Informational
+
Expires:
+
+
Author:
+
+
+
M. Thomson
+
Mozilla
+
+
+
+
+

The SSLKEYLOGFILE Format for TLS

+
+

Abstract

+

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 +

+

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 +

+

+ 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 7 October 2024.

+
+
+ +
+
+ ▲

+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 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].

+
+
+

+1.1. 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.

+
+
+
+
+

+1.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.

+
+
+
+
+
+
+

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

+
+
+

+2.1. 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.

+
+
+
+
+

+2.2. 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.

+
+
+
+
+
+
+

+3. Security Considerations +

+

Access to the content of a file in SSLKEYLOGFILE format 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 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.

+
+
+
+
+

+4. 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 3.

+
+
+
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

+
+
+
+
+
+
+

+5. References +

+
+
+

+5.1. Normative References +

+
+
[RFC2119]
+
+Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/rfc/rfc2119>.
+
+
[RFC3629]
+
+Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, , <https://www.rfc-editor.org/rfc/rfc3629>.
+
+
[RFC8174]
+
+Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/rfc/rfc8174>.
+
+
[TLS12]
+
+Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/RFC5246, , <https://www.rfc-editor.org/rfc/rfc5246>.
+
+
[TLS13]
+
+Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", Work in Progress, Internet-Draft, draft-ietf-tls-rfc8446bis-10, , <https://datatracker.ietf.org/doc/html/draft-ietf-tls-rfc8446bis-10>.
+
+
+
+
+
+
+

+5.2. Informative References +

+
+
[DTLS13]
+
+Rescorla, E., Tschofenig, H., and N. Modadugu, "The Datagram Transport Layer Security (DTLS) Protocol Version 1.3", RFC 9147, DOI 10.17487/RFC9147, , <https://www.rfc-editor.org/rfc/rfc9147>.
+
+
[QLOG]
+
+Marx, R., Niccolini, L., Seemann, M., and L. Pardue, "Main logging schema for qlog", Work in Progress, Internet-Draft, draft-ietf-quic-qlog-main-schema-08, , <https://datatracker.ietf.org/doc/html/draft-ietf-quic-qlog-main-schema-08>.
+
+
[RFC0020]
+
+Cerf, V., "ASCII format for network interchange", STD 80, RFC 20, DOI 10.17487/RFC0020, , <https://www.rfc-editor.org/rfc/rfc20>.
+
+
[RFC4492]
+
+Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS)", RFC 4492, DOI 10.17487/RFC4492, , <https://www.rfc-editor.org/rfc/rfc4492>.
+
+
[RFC8446]
+
+Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, , <https://www.rfc-editor.org/rfc/rfc8446>.
+
+
[RFC8471]
+
+Popov, A., Ed., Nystroem, M., Balfanz, D., and J. Hodges, "The Token Binding Protocol Version 1.0", RFC 8471, DOI 10.17487/RFC8471, , <https://www.rfc-editor.org/rfc/rfc8471>.
+
+
[RFC8996]
+
+Moriarty, K. and S. Farrell, "Deprecating TLS 1.0 and TLS 1.1", BCP 195, RFC 8996, DOI 10.17487/RFC8996, , <https://www.rfc-editor.org/rfc/rfc8996>.
+
+
[RFC9000]
+
+Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based Multiplexed and Secure Transport", RFC 9000, DOI 10.17487/RFC9000, , <https://www.rfc-editor.org/rfc/rfc9000>.
+
+
[RFC9001]
+
+Thomson, M., Ed. and S. Turner, Ed., "Using TLS to Secure QUIC", RFC 9001, DOI 10.17487/RFC9001, , <https://www.rfc-editor.org/rfc/rfc9001>.
+
+
[RFC9261]
+
+Sullivan, N., "Exported Authenticators in TLS", RFC 9261, DOI 10.17487/RFC9261, , <https://www.rfc-editor.org/rfc/rfc9261>.
+
+
+
+
+
+
+
+

+Appendix A. 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.

+
+
+
+
+

+Author's Address +

+
+
Martin Thomson
+
Mozilla
+ +
+
+
+ + + diff --git a/multiple-connections/draft-ietf-tls-keylogfile.txt b/multiple-connections/draft-ietf-tls-keylogfile.txt new file mode 100644 index 0000000..73eebb2 --- /dev/null +++ b/multiple-connections/draft-ietf-tls-keylogfile.txt @@ -0,0 +1,480 @@ + + + + +Transport Layer Security M. Thomson +Internet-Draft Mozilla +Intended status: Informational 5 April 2024 +Expires: 7 October 2024 + + + The SSLKEYLOGFILE Format for TLS + draft-ietf-tls-keylogfile-latest + +Abstract + + 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 + + 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 + + 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 7 October 2024. + +Copyright Notice + + Copyright (c) 2024 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 + 1.1. Applicability Statement + 1.2. Conventions and Definitions + 2. The SSLKEYLOGFILE Format + 2.1. Secret Labels for TLS 1.3 + 2.2. Secret Labels for TLS 1.2 + 3. Security Considerations + 4. IANA Considerations + 5. References + 5.1. Normative References + 5.2. Informative References + Appendix A. Example + Acknowledgments + Author's Address + +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 + 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]. + +1.1. 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. + +1.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. + +2. 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. + +2.1. 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. + +2.2. 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. + +3. Security Considerations + + Access to the content of a file in SSLKEYLOGFILE format 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 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. + +4. 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 + (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 3. + 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 + +5. References + +5.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . + + [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November + 2003, . + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, . + + [TLS12] Dierks, T. and E. Rescorla, "The Transport Layer Security + (TLS) Protocol Version 1.2", RFC 5246, + DOI 10.17487/RFC5246, August 2008, + . + + [TLS13] Rescorla, E., "The Transport Layer Security (TLS) Protocol + Version 1.3", Work in Progress, Internet-Draft, draft- + ietf-tls-rfc8446bis-10, 3 March 2024, + . + +5.2. Informative References + + [DTLS13] Rescorla, E., Tschofenig, H., and N. Modadugu, "The + Datagram Transport Layer Security (DTLS) Protocol Version + 1.3", RFC 9147, DOI 10.17487/RFC9147, April 2022, + . + + [QLOG] Marx, R., Niccolini, L., Seemann, M., and L. Pardue, "Main + logging schema for qlog", Work in Progress, Internet- + Draft, draft-ietf-quic-qlog-main-schema-08, 4 March 2024, + . + + [RFC0020] Cerf, V., "ASCII format for network interchange", STD 80, + RFC 20, DOI 10.17487/RFC0020, October 1969, + . + + [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. + Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites + for Transport Layer Security (TLS)", RFC 4492, + DOI 10.17487/RFC4492, May 2006, + . + + [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol + Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, + . + + [RFC8471] Popov, A., Ed., Nystroem, M., Balfanz, D., and J. Hodges, + "The Token Binding Protocol Version 1.0", RFC 8471, + DOI 10.17487/RFC8471, October 2018, + . + + [RFC8996] Moriarty, K. and S. Farrell, "Deprecating TLS 1.0 and TLS + 1.1", BCP 195, RFC 8996, DOI 10.17487/RFC8996, March 2021, + . + + [RFC9000] Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based + Multiplexed and Secure Transport", RFC 9000, + DOI 10.17487/RFC9000, May 2021, + . + + [RFC9001] Thomson, M., Ed. and S. Turner, Ed., "Using TLS to Secure + QUIC", RFC 9001, DOI 10.17487/RFC9001, May 2021, + . + + [RFC9261] Sullivan, N., "Exported Authenticators in TLS", RFC 9261, + DOI 10.17487/RFC9261, July 2022, + . + +Appendix A. 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. + +Author's Address + + Martin Thomson + Mozilla + Email: mt@lowentropy.net diff --git a/multiple-connections/index.html b/multiple-connections/index.html new file mode 100644 index 0000000..18c7938 --- /dev/null +++ b/multiple-connections/index.html @@ -0,0 +1,45 @@ + + + + tlswg/sslkeylogfile multiple-connections preview + + + + +

Editor's drafts for multiple-connections branch of tlswg/sslkeylogfile

+ + + + + + +
SSLKEYLOGFILEplain textsame as main
+ + +