Merge pull request #1 from yaroslavros/hannestschofenig-patch-1

Update draft-rosomakho-tls-ech-keylogfile.md

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,51 +35,56 @@ 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 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
 
 # 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 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
 
 {::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
 
-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.
+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.
 
-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.
+Implementers MUST take measures to prevent unauthorized access to the SSLKEYLOGFILE text file.
 
+This extension is intended for use in systems where TLS only protects test data.
 
 # IANA Considerations