From 2ffb20fac2730877c7d05abb018efef7c1c0e476 Mon Sep 17 00:00:00 2001 From: Hannes Tschofenig Date: Mon, 24 Jun 2024 15:45:11 +0200 Subject: [PATCH 1/4] Update draft-rosomakho-tls-ech-keylogfile.md --- draft-rosomakho-tls-ech-keylogfile.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/draft-rosomakho-tls-ech-keylogfile.md b/draft-rosomakho-tls-ech-keylogfile.md index 3745e5c..3122ccc 100644 --- a/draft-rosomakho-tls-ech-keylogfile.md +++ b/draft-rosomakho-tls-ech-keylogfile.md @@ -35,23 +35,21 @@ informative: --- abstract -This document specifies an extension to the SSLKEYLOGFILE format {{!I-D.ietf-tls-keylogfile}} to support the logging information about Encrypted Client Hello (ECH) {{!I-D.ietf-tls-esni}} 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. +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. --- middle # Introduction -The SSLKEYLOGFILE format, used for information about the secrets used in a TLS connection, is instrumental in debugging and analyzing TLS traffic. With the introduction of Encrypted Client Hello (ECH), additional secret is used during the handshake process. This document extends the SSLKEYLOGFILE format to include relevant information to decrypt ECH extension, enabling comprehensive analysis of ECH-enabled connections. This document also clarifies logging of TLS 1.3 secrets if ECH was successfully negotiated. - -Proposed extensions can also be used with all protocols that support ECH including TLS 1.3 {{?RFC8446}}, DTLS 1.3 {{?RFC9147}} and QUIC {{?RFC9000}}{{?RFC9001}}. +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}}. # Conventions and Definitions - {::boilerplate bcp14-tagged} - # 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. @@ -76,11 +74,12 @@ SSLKEYLOGFILE entries corresponding to TLS 1.3 secrets for connections that succ # 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. - # IANA Considerations This document has no IANA actions. From 54e0f6da5a15059dd37a382e0e518ea76f514715 Mon Sep 17 00:00:00 2001 From: Hannes Tschofenig Date: Mon, 24 Jun 2024 16:09:19 +0200 Subject: [PATCH 2/4] Fix whitespaces --- draft-rosomakho-tls-ech-keylogfile.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-rosomakho-tls-ech-keylogfile.md b/draft-rosomakho-tls-ech-keylogfile.md index 3122ccc..4241f6f 100644 --- a/draft-rosomakho-tls-ech-keylogfile.md +++ b/draft-rosomakho-tls-ech-keylogfile.md @@ -74,7 +74,7 @@ SSLKEYLOGFILE entries corresponding to TLS 1.3 secrets for connections that succ # 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. +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. From ade53f0dbed8c60b8069eca340ad6b5fce2c5afc Mon Sep 17 00:00:00 2001 From: Hannes Tschofenig Date: Mon, 24 Jun 2024 16:26:27 +0200 Subject: [PATCH 3/4] Further wording changes. --- draft-rosomakho-tls-ech-keylogfile.md | 34 ++++++++++++++++----------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/draft-rosomakho-tls-ech-keylogfile.md b/draft-rosomakho-tls-ech-keylogfile.md index 4241f6f..3d46dbb 100644 --- a/draft-rosomakho-tls-ech-keylogfile.md +++ b/draft-rosomakho-tls-ech-keylogfile.md @@ -1,5 +1,5 @@ --- -title: "SSLKEYLOGFILE extensions for Encrypted Client Hello" +title: "SSLKEYLOGFILE Extension for Encrypted Client Hello (ECH)" category: info docname: draft-rosomakho-tls-ech-keylogfile-latest @@ -35,8 +35,9 @@ informative: --- 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. +This document specifies an extension to the SSLKEYLOGFILE format to support the logging of information about Encrypted Client Hello (ECH) related secrets. Two new labels are introduced, namely ECH_SECRET and ECH_CONFIG, which log the Hybrid Public Key Encryption (HPKE)-derived shared secret and the ECHConfig used for the ECH, respectively. +This extension aims to facilitate debugging of TLS connections employing ECH. --- middle @@ -44,41 +45,46 @@ This document specifies an extension to the SSLKEYLOGFILE format to support the 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}}. +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 using Hybrid Public Key Encryption (HPKE) {{?RFC9180}}. 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}}. # Conventions and Definitions + {::boilerplate bcp14-tagged} # 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. +This document defines two new labels for SSLKEYLOGFILE format: ECH_SECRET and ECH_CONFIG. The client SHOULD log the labels if it offered ECH regardless of server acceptance. The server MAY log the labels only if it successfully decrypted and accepted ECH offered by the client. The 32-byte random value from the Outer ClientHello message is used as the client_random value for these log records. The client MUST NOT log the labels for connections that use the GREASE ECH extension (see Section 6.2 of {{!I-D.ietf-tls-esni}}). ## 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. +This label corresponds to the KEM shared secret derived during the HPKE key schedule process. Length of the secret is defined by the KEM negotiated for use with ECH. ## 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. - +This label is used to log the ECHConfig used for construction of the ECH extension. Note that the value is logged in hexadecimal representation, similarly to other entries in the SSLKEYLOGFILE. -# 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. +# Client_random for other TLS 1.3 SSLKEYLOGFILE Entries -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. +The SSLKEYLOGFILE uses the random value from the ClientHello message as a "connection identifier". This creates ambiguity since the TLS handshake with ECH contains two different random values, one in the Outer ClientHello structure and the second one in the Inner ClientHello. +The SSLKEYLOGFILE entries corresponding to TLS 1.3 secrets for connections that successfully negotiated ECH MUST use the random from the Inner ClientHello structure. In all other cases the random value from the Outer ClientHello structure MUST be used. # 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. +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 specification extends the SSLKEYLOGFILE specification {{!I-D.ietf-tls-keylogfile}} and therefore introduces the following threats: + +- Access to the ECH_SECRET record in the SSLKEYLOGFILE allows the attacker to decrypt the ECH extension and thereby reveal the content of the ClientHello message, including the payload of the Server Name Indication (SNI) extension. + +- Access to the HPKE-established shared secret introduces potential attack surface against the HPKE process. -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. +Implementers MUST take measures to prevent unauthorized access to the SSLKEYLOGFILE text file. -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. +This extension is intended for use in systems where TLS only protects test data. # IANA Considerations From 836d35e260079340de383d2b486cf203b4f30812 Mon Sep 17 00:00:00 2001 From: yaroslavros Date: Thu, 4 Jul 2024 10:42:28 +0100 Subject: [PATCH 4/4] Fixed typo --- draft-rosomakho-tls-ech-keylogfile.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-rosomakho-tls-ech-keylogfile.md b/draft-rosomakho-tls-ech-keylogfile.md index 3d46dbb..cc2b26a 100644 --- a/draft-rosomakho-tls-ech-keylogfile.md +++ b/draft-rosomakho-tls-ech-keylogfile.md @@ -45,7 +45,7 @@ This extension aims to facilitate debugging of TLS connections employing ECH. 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 using Hybrid Public Key Encryption (HPKE) {{?RFC9180}}. 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}}. +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 using Hybrid Public Key Encryption (HPKE) {{?RFC9180}}. This document extends the SSLKEYLOGFILE format to also offer support for the ECH extension to enable debugging of 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}}. # Conventions and Definitions