From 87d804db1fd1654f91725f0da4416d0bac8655ff Mon Sep 17 00:00:00 2001 From: ID Bot Date: Mon, 24 Jun 2024 14:10:08 +0000 Subject: [PATCH] Script updating gh-pages from 54e0f6d. [ci skip] --- .../draft-rosomakho-tls-ech-keylogfile.html | 1340 +++++++++++++++++ .../draft-rosomakho-tls-ech-keylogfile.txt | 231 +++ hannestschofenig-patch-1/index.html | 45 + index.html | 8 + 4 files changed, 1624 insertions(+) create mode 100644 hannestschofenig-patch-1/draft-rosomakho-tls-ech-keylogfile.html create mode 100644 hannestschofenig-patch-1/draft-rosomakho-tls-ech-keylogfile.txt create mode 100644 hannestschofenig-patch-1/index.html diff --git a/hannestschofenig-patch-1/draft-rosomakho-tls-ech-keylogfile.html b/hannestschofenig-patch-1/draft-rosomakho-tls-ech-keylogfile.html new file mode 100644 index 0000000..68758f0 --- /dev/null +++ b/hannestschofenig-patch-1/draft-rosomakho-tls-ech-keylogfile.html @@ -0,0 +1,1340 @@ + + + + + + +SSLKEYLOGFILE extensions for Encrypted Client Hello + + + + + + + + + + + + + + + + + + + + + + + + +
Internet-DraftSSLKEYLOGFILE extensions for Encrypted CJune 2024
RosomakhoExpires 26 December 2024[Page]
+
+
+
+
Workgroup:
+
Transport Layer Security
+
Internet-Draft:
+
draft-rosomakho-tls-ech-keylogfile-latest
+
Published:
+
+ +
+
Intended Status:
+
Informational
+
Expires:
+
+
Author:
+
+
+
Y. Rosomakho
+
Zscaler
+
+
+
+
+

SSLKEYLOGFILE extensions for Encrypted Client Hello

+
+

Abstract

+

This document specifies an extension to the SSLKEYLOGFILE format to support the logging information about Encrypted Client Hello (ECH) related secrets. Specifically, it introduces two new labels: ECH_SECRET and ECH_CONFIG, which respectively log the HPKE [RFC9180] shared secret and the ECHConfig used for the ECH. This extension aims to facilitate debugging and analysis of TLS connections employing ECH.

+
+
+

+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://yaroslavros.github.io/tls-ech-keylog/draft-rosomakho-tls-ech-keylogfile.html. + Status information for this document may be found at https://datatracker.ietf.org/doc/draft-rosomakho-tls-ech-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/yaroslavros/tls-ech-keylog.

+
+
+
+

+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 26 December 2024.

+
+
+ +
+
+ ▲

+Table of Contents +

+ +
+
+
+
+

+1. Introduction +

+

Debugging protocols with TLS can be difficult due to encrypted communications. Analyzing these messages in diagnostic and debug tools requires inspecting the encrypted content. Various TLS implementations have informally adopted a file format to log the secret values generated by the TLS key schedule, aiding in this analysis.

+

In many implementations, the file that the secrets are logged to is specified in an environment variable named +"SSLKEYLOGFILE". [I-D.ietf-tls-keylogfile] standardizes this format. With the introduction of [I-D.ietf-tls-esni] additional secrets are derived during the handshake to encrypt the ClientHello message. This document extends the SSLKEYLOGFILE format to also offer support for the ECH extension to enable debugging aof ECH-enabled connections. The proposed extension can also be used with all protocols that support ECH, including TLS 1.3 [RFC8446], DTLS 1.3 [RFC9147] and QUIC [RFC9000][RFC9001].

+
+
+
+
+

+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. SSLKEYLOGFILE Labels for ECH +

+

This document defines two new labels for SSLKEYLOGFILE format: ECH_SECRET and ECH_CONFIG. Client SHOULD log those labels if it offered ECH regardless of server acceptance. Server can log those labels only if it decrypted and accepted ECH from the client. The 32-byte Random from the Outer ClientHello message is used as client_random for these log records. Client MUST NOT log those labels for connections that use GREASE ECH extension.

+
+
+

+3.1. ECH_SECRET +

+

This label corresponds to KEM shared secret derived during HPKE key schedule process. Length of the secret is defined by KEM that was used for ECH.

+
+
+
+
+

+3.2. ECH_CONFIG +

+

This label is used to log ECHConfig that was used for construction of ECH extension. Note that the value is logged in hexadecimal, similarly to other entries in SSLKEYLOGFILE.

+
+
+
+
+
+
+

+4. Client_random for other TLS 1.3 SSLKEYLOGFILE entries +

+

SSLKEYLOGFILE is using Random from ClientHello as the connection identifier. This creates ambiguity since TLS handshake with ECH contains two different Random values in Outer ClientHello and Inner ClientHello.

+

SSLKEYLOGFILE entries corresponding to TLS 1.3 secrets for connections that successfully negotiated ECH MUST use Random from Inner ClientHello. In all other cases Random from Outer ClientHello is to be used.

+
+
+
+
+

+5. Security Considerations +

+

The applicability statement of [I-D.ietf-tls-keylogfile] also applies to this document: if unauthorized entities gain access to the logged secrets then the core guarantees that TLS provides are completely undermined. This extension is intended for use in systems where TLS only protects test data.

+

Access to ECH_SECRET record in SSLKEYLOGFILE allows attacker to decrypt ECH extension and defeat privacy benefits offered by the ECH. Security considerations described in SSLKEYLOGFILE are fully applicable to this extension.

+

Ability to log KEM shared secret from HPKE key schedule introduces potential attack surface against HPKE process. Implementers need to secure relevant APIs accordingly to ensure that no unauthorised party can extract the KEM shared secret.

+
+
+
+
+

+6. IANA Considerations +

+

This document has no IANA actions.

+
+
+
+

+7. References +

+
+
+

+7.1. Normative References +

+
+
[I-D.ietf-tls-esni]
+
+Rescorla, E., Oku, K., Sullivan, N., and C. A. Wood, "TLS Encrypted Client Hello", Work in Progress, Internet-Draft, draft-ietf-tls-esni-18, , <https://datatracker.ietf.org/doc/html/draft-ietf-tls-esni-18>.
+
+
[I-D.ietf-tls-keylogfile]
+
+Thomson, M., "The SSLKEYLOGFILE Format for TLS", Work in Progress, Internet-Draft, draft-ietf-tls-keylogfile-02, , <https://datatracker.ietf.org/doc/html/draft-ietf-tls-keylogfile-02>.
+
+
[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>.
+
+
[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>.
+
+
+
+
+
+
+

+7.2. Informative References +

+
+
[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>.
+
+
[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>.
+
+
[RFC9147]
+
+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>.
+
+
[RFC9180]
+
+Barnes, R., Bhargavan, K., Lipp, B., and C. Wood, "Hybrid Public Key Encryption", RFC 9180, DOI 10.17487/RFC9180, , <https://www.rfc-editor.org/rfc/rfc9180>.
+
+
+
+
+
+
+
+

+Acknowledgments +

+

TODO acknowledge.

+
+
+
+
+

+Author's Address +

+
+
Yaroslav Rosomakho
+
Zscaler
+ +
+
+
+ + + diff --git a/hannestschofenig-patch-1/draft-rosomakho-tls-ech-keylogfile.txt b/hannestschofenig-patch-1/draft-rosomakho-tls-ech-keylogfile.txt new file mode 100644 index 0000000..8db5fa4 --- /dev/null +++ b/hannestschofenig-patch-1/draft-rosomakho-tls-ech-keylogfile.txt @@ -0,0 +1,231 @@ + + + + +Transport Layer Security Y. Rosomakho +Internet-Draft Zscaler +Intended status: Informational 24 June 2024 +Expires: 26 December 2024 + + + SSLKEYLOGFILE extensions for Encrypted Client Hello + draft-rosomakho-tls-ech-keylogfile-latest + +Abstract + + This document specifies an extension to the SSLKEYLOGFILE format to + support the logging information about Encrypted Client Hello (ECH) + related secrets. Specifically, it introduces two new labels: + ECH_SECRET and ECH_CONFIG, which respectively log the HPKE [RFC9180] + shared secret and the ECHConfig used for the ECH. This extension + aims to facilitate debugging and analysis of TLS connections + employing ECH. + +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://yaroslavros.github.io/tls-ech-keylog/draft-rosomakho-tls-ech- + keylogfile.html. Status information for this document may be found + at https://datatracker.ietf.org/doc/draft-rosomakho-tls-ech- + 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/yaroslavros/tls-ech-keylog. + +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 26 December 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 + 2. Conventions and Definitions + 3. SSLKEYLOGFILE Labels for ECH + 3.1. ECH_SECRET + 3.2. ECH_CONFIG + 4. Client_random for other TLS 1.3 SSLKEYLOGFILE entries + 5. Security Considerations + 6. IANA Considerations + 7. References + 7.1. Normative References + 7.2. Informative References + Acknowledgments + Author's Address + +1. Introduction + + Debugging protocols with TLS can be difficult due to encrypted + communications. Analyzing these messages in diagnostic and debug + tools requires inspecting the encrypted content. Various TLS + implementations have informally adopted a file format to log the + secret values generated by the TLS key schedule, aiding in this + analysis. + + In many implementations, the file that the secrets are logged to is + specified in an environment variable named "SSLKEYLOGFILE". + [I-D.ietf-tls-keylogfile] standardizes this format. With the + introduction of [I-D.ietf-tls-esni] additional secrets are derived + during the handshake to encrypt the ClientHello message. This + document extends the SSLKEYLOGFILE format to also offer support for + the ECH extension to enable debugging aof ECH-enabled connections. + The proposed extension can also be used with all protocols that + support ECH, including TLS 1.3 [RFC8446], DTLS 1.3 [RFC9147] and QUIC + [RFC9000][RFC9001]. + +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. SSLKEYLOGFILE Labels for ECH + + This document defines two new labels for SSLKEYLOGFILE format: + ECH_SECRET and ECH_CONFIG. Client SHOULD log those labels if it + offered ECH regardless of server acceptance. Server can log those + labels only if it decrypted and accepted ECH from the client. The + 32-byte Random from the Outer ClientHello message is used as + client_random for these log records. Client MUST NOT log those + labels for connections that use GREASE ECH extension. + +3.1. ECH_SECRET + + This label corresponds to KEM shared secret derived during HPKE key + schedule process. Length of the secret is defined by KEM that was + used for ECH. + +3.2. ECH_CONFIG + + This label is used to log ECHConfig that was used for construction of + ECH extension. Note that the value is logged in hexadecimal, + similarly to other entries in SSLKEYLOGFILE. + +4. Client_random for other TLS 1.3 SSLKEYLOGFILE entries + + SSLKEYLOGFILE is using Random from ClientHello as the connection + identifier. This creates ambiguity since TLS handshake with ECH + contains two different Random values in Outer ClientHello and Inner + ClientHello. + + SSLKEYLOGFILE entries corresponding to TLS 1.3 secrets for + connections that successfully negotiated ECH MUST use Random from + Inner ClientHello. In all other cases Random from Outer ClientHello + is to be used. + +5. Security Considerations + + The applicability statement of [I-D.ietf-tls-keylogfile] also applies + to this document: if unauthorized entities gain access to the logged + secrets then the core guarantees that TLS provides are completely + undermined. This extension is intended for use in systems where TLS + only protects test data. + + Access to ECH_SECRET record in SSLKEYLOGFILE allows attacker to + decrypt ECH extension and defeat privacy benefits offered by the ECH. + Security considerations described in SSLKEYLOGFILE are fully + applicable to this extension. + + Ability to log KEM shared secret from HPKE key schedule introduces + potential attack surface against HPKE process. Implementers need to + secure relevant APIs accordingly to ensure that no unauthorised party + can extract the KEM shared secret. + +6. IANA Considerations + + This document has no IANA actions. + +7. References + +7.1. Normative References + + [I-D.ietf-tls-esni] + Rescorla, E., Oku, K., Sullivan, N., and C. A. Wood, "TLS + Encrypted Client Hello", Work in Progress, Internet-Draft, + draft-ietf-tls-esni-18, 4 March 2024, + . + + [I-D.ietf-tls-keylogfile] + Thomson, M., "The SSLKEYLOGFILE Format for TLS", Work in + Progress, Internet-Draft, draft-ietf-tls-keylogfile-02, 29 + April 2024, . + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, . + +7.2. Informative References + + [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol + Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, + . + + [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, + . + + [RFC9147] 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, + . + + [RFC9180] Barnes, R., Bhargavan, K., Lipp, B., and C. Wood, "Hybrid + Public Key Encryption", RFC 9180, DOI 10.17487/RFC9180, + February 2022, . + +Acknowledgments + + TODO acknowledge. + +Author's Address + + Yaroslav Rosomakho + Zscaler + Email: yrosomakho@zscaler.com diff --git a/hannestschofenig-patch-1/index.html b/hannestschofenig-patch-1/index.html new file mode 100644 index 0000000..1de3d81 --- /dev/null +++ b/hannestschofenig-patch-1/index.html @@ -0,0 +1,45 @@ + + + + yaroslavros/tls-ech-keylog hannestschofenig-patch-1 preview + + + + +

Editor's drafts for hannestschofenig-patch-1 branch of yaroslavros/tls-ech-keylog

+ + + + + + +
SSLKEYLOGFILE extensions for Encrypted Client Helloplain textsame as main
+ + + diff --git a/index.html b/index.html index d1eef59..25bb88c 100644 --- a/index.html +++ b/index.html @@ -24,6 +24,14 @@

Editor's drafts for main branch of hannestschofenig-patch-1

+ + + + + + +
SSLKEYLOGFILE extensions for Encrypted Client Helloplain textdiff with main