jiebi/TextFlow huggingface dataset:
Original text:
alert" and "abort the handshake with a X alert" mean that the implementation MUST send alert X if it sends any alert.  All alerts defined in this section below, as well as all unknown alerts, are <del> universally considered fatal as of TLS 1.3 (see alert-protocol). The following error alerts are defined: </del>  An inappropriate message (e.g., the wrong handshake message, premature application data, etc.) was received.  This alert should

Reviewer comments:
I disagree with this. Equally valid advice is to do as little as possible except abort the connection when receiving an alert. Some implementations will not send alerts at all.
NAME can you please raise this on the list in response to Kathleen's comments? Thanks
Per Kathleen's AD review

Revised text:
alert" and "abort the handshake with a X alert" mean that the implementation MUST send alert X if it sends any alert.  All alerts defined in this section below, as well as all unknown alerts, are  <ins> universally considered fatal as of TLS 1.3 (see alert-protocol).  The implementation SHOULD provide a way to facilitate logging the sending and receiving of alerts. </ins> An inappropriate message (e.g., the wrong handshake message, premature application data, etc.) was received.  This alert should
Original text:
The cipher suite for use with this PSK <del> The Application-Layer Protocol Negotiation (ALPN) protocol, if any is to be used </del>  The Server Name Indication (SNI), if any is to be used

Reviewer comments:
The reference to [RFC7301] is after the third mention of ALPN. It should instead be at the first reference to ALPN.

Revised text:
The cipher suite for use with this PSK  <ins> The Application-Layer Protocol Negotiation (ALPN) protocol RFC7301, if any is to be used </ins> The Server Name Indication (SNI), if any is to be used
Original text:
Add a per-ticket nonce so that each ticket is associated with a different PSK (*).  Add discussion of 0-RTT and replay.  Recommend that implementations implement some anti-replay mechanism. Servers MAY send data after sending their first flight, but because the handshake is not yet complete, they have no assurance <del> of either the peer's identity or of it's liveness (i.e., the </del>  ClientHello might have been replayed). The key used to compute the finished message is computed from the

Reviewer comments:
NAME NAME I would appreciate a sanity check here.
Maybe remove the "arguably" statement and the *

Revised text:
Add a per-ticket nonce so that each ticket is associated with a different PSK (*). <ins> Clarify that clients should change to sending with handshake keys immediately upon reading ServerHello.  Arguably a wire format change. (*). Update state machine to show rekeying events </ins> Add discussion of 0-RTT and replay.  Recommend that implementations implement some anti-replay mechanism. Servers MAY send data after sending their first flight, but because the handshake is not yet complete, they have no assurance  <ins> of either the peer's identity or of its liveness (i.e., the </ins> ClientHello might have been replayed). The key used to compute the finished message is computed from the
Original text:
Messages are the concatenation of the indicated handshake messages, including the handshake message type and length fields, but not including record layer headers.  Note that in some cases a zero- <del> length HashValue (indicated by "") is passed to HKDF-Expand-Label. </del>  Note: with common hash functions, any label longer than 12 characters requires an additional iteration of the hash function to compute.

Reviewer comments:
This is no longer a hash value throughout, using a different name might reduce confusion a little.
Seems like an improvement.+1

Revised text:
Messages are the concatenation of the indicated handshake messages, including the handshake message type and length fields, but not including record layer headers.  Note that in some cases a zero-  <ins> length Context (indicated by "") is passed to HKDF-Expand-Label. </ins> Note: with common hash functions, any label longer than 12 characters requires an additional iteration of the hash function to compute.
Original text:
For secp256r1, secp384r1 and secp521r1, the contents are the serialized value of the following struct:  X and Y respectively are the binary representations of the X and Y values in network byte order.  There are no internal length markers, so each number representation occupies as many octets as implied by

Reviewer comments:
Fix the spacing in and add it to Appendix B.3.1. Add missing space in .

Revised text:
For secp256r1, secp384r1 and secp521r1, the contents are the serialized value of the following struct: <ins> %%% Key Exchange Messages </ins> X and Y respectively are the binary representations of the X and Y values in network byte order.  There are no internal length markers, so each number representation occupies as many octets as implied by
Original text:
removing any PSKs which are incompatible with the server's indicated cipher suite.  Because TLS 1.3 forbids renegotiation, if a server has negotiated TLS 1.3 and receives a ClientHello at any other time, it MUST terminate the connection with an "unexpected_message" alert.

Reviewer comments:
The padding extension is typically computed as part of serializing the ClientHello, in hopes of targetting a particular size. As specified right now, the second ClientHello must not use this same logic and instead must retain the previous extension sizethough this would likely not hit the same target size. The server's going to ignore it anyway, so allow it to be recalcuated. This avoids unnecessary state in clients and extra logic to serialize the first and second ClientHellos differently.
Good catch; +1

Revised text:
removing any PSKs which are incompatible with the server's indicated cipher suite. <ins> Optionally adding, removing, or changing the length of the "padding" extension RFC7685. </ins> Because TLS 1.3 forbids renegotiation, if a server has negotiated TLS 1.3 and receives a ClientHello at any other time, it MUST terminate the connection with an "unexpected_message" alert.
Original text:
single connection, either immediately after each other or after specific events.  For instance, the server might send a new ticket after post-handshake authentication in order to encapsulate the <del> additional client authentication state.  Clients SHOULD attempt to use each ticket no more than once, with more recent tickets being used first. </del>  Any ticket MUST only be resumed on connections where the following values match the values negotiated in the connection during which the

Reviewer comments:
Currently, the draft says that servers MAY send multiple tickets to clients without further discussion. It might help to be concrete and provide an example for when more than one ticket is useful. This PR provides one example.

Revised text:
single connection, either immediately after each other or after specific events.  For instance, the server might send a new ticket after post-handshake authentication in order to encapsulate the  <ins> additional client authentication state.  Multiple tickets are useful for clients for a variety of purposes, including: Opening multiple parallel HTTP connections. Performing connection racing across interfaces and address families via, e.g., Happy Eyeballs RFC6555 or related techniques. Clients SHOULD attempt to use each ticket no more than once, with more recent tickets being used first. </ins> Any ticket MUST only be resumed on connections where the following values match the values negotiated in the connection during which the
Original text:
validate each other's public value Y by ensuring that the point is a valid point on the elliptic curve.  The appropriate validation procedures are defined in Section 4.3.7 of X962 and alternatively in <del> Section 5.6.2.6 of KEYAGREEMENT.  This process consists of three </del>  steps: (1) verify that Y is not the point at infinity (O), (2) verify that for Y = (x, y) both integers are in the correct interval, (3) ensure that (x, y) is a correct solution to the elliptic curve

Reviewer comments:
The RFC editor found a few errors in a draft that used the same references. This updates the draft to use the automatically generated DOI references from URL rather than manual references. This isn't perfect, but it should help the RFC editor when it comes time to publish.
This changes: to LGTM (Dang is the author according to URL)

Revised text:
validate each other's public value Y by ensuring that the point is a valid point on the elliptic curve.  The appropriate validation procedures are defined in Section 4.3.7 of X962 and alternatively in  <ins> Section 5.6.2.3 of KEYAGREEMENT.  This process consists of three </ins> steps: (1) verify that Y is not the point at infinity (O), (2) verify that for Y = (x, y) both integers are in the correct interval, (3) ensure that (x, y) is a correct solution to the elliptic curve
Original text:
All implementations MUST send and use these extensions when offering applicable features: <del> "supported_versions" is REQUIRED for all ClientHello messages. </del>  "signature_algorithms" is REQUIRED for certificate authentication.

Reviewer comments:
This is mentioned throughout the document, but not in the "Mandatory-to-Implement" section.
This is the same as , just without the extra new line additions, etc
In the section it states: In the section we have: However, this is not mentioned in the "Mandatory-to-Implement" extensions section.

Revised text:
All implementations MUST send and use these extensions when offering applicable features:  <ins> "supported_versions" is REQUIRED for all ClientHello, ServerHello and HelloRetryRequest messages. </ins> "signature_algorithms" is REQUIRED for certificate authentication.
Original text:
If the corresponding certificate type extension ("server_certificate_type" or "client_certificate_type") was not negotiated in Encrypted Extensions, or the X.509 certificate type was <del> negotiated, then each CertificateEntry contains an X.509 certificate. The sender's certificate MUST come in the first CertificateEntry in the list.  Each following certificate SHOULD directly certify one preceding it.  Because certificate validation requires that trust anchors be distributed independently, a certificate that specifies a trust anchor MAY be omitted from the chain, provided that supported peers are known to possess any omitted certificates. </del>  Note: Prior to TLS 1.3, "certificate_list" ordering required each certificate to certify the one immediately preceding it; however,

Reviewer comments:
Without specifying the encoding, I don't think it's actually defined how you transit the certificates. RFC 5280 only says that the TBSCertificate is DER-encoded for computing the signature, which still allows insanity like XER-encoded everything with the receiver re-encoding the TBSCertificate to DER before verifying the signature.

Revised text:
If the corresponding certificate type extension ("server_certificate_type" or "client_certificate_type") was not negotiated in Encrypted Extensions, or the X.509 certificate type was  <ins> negotiated, then each CertificateEntry contains a DER-encoded X.509 certificate.  The sender's certificate MUST come in the first CertificateEntry in the list.  Each following certificate SHOULD directly certify one preceding it.  Because certificate validation requires that trust anchors be distributed independently, a certificate that specifies a trust anchor MAY be omitted from the chain, provided that supported peers are known to possess any omitted certificates. </ins> Note: Prior to TLS 1.3, "certificate_list" ordering required each certificate to certify the one immediately preceding it; however,
Original text:
backward-compatibility for details about backward compatibility.) <del> This structure is generated by the server and MUST be independently generated from the ClientHello.random. </del>  This is the identity of the session corresponding to this

Reviewer comments:
Server Hello is slightly confusing english. Must this be generated from the URL I'm pretty sure the opposite is the intent. A clearer form of words might be: or
Merged.

Revised text:
backward-compatibility for details about backward compatibility.)  <ins> This structure is generated by the server and MUST be generated independently of the ClientHello.random. </ins> This is the identity of the session corresponding to this
Original text:
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and <del> "OPTIONAL" in this document are to be interpreted as described in RFC 2119 RFC2119. </del>  The following terms are used:

Reviewer comments:
RFC 8174 updates RFC 2119 so the boilerplate words have changed slightly according to s2 of RFC 8174. Just trying to save us another GENART comment.

Revised text:
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and  <ins> "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. </ins> The following terms are used:
Original text:
A list of extensions.  The ServerHello MUST only include extensions which are required to establish the cryptographic <del> context.  Currently the only such extensions are "key_share" and "pre_shared_key".  All current TLS 1.3 ServerHello messages will contain one of these two extensions, or both when using a PSK with (EC)DHE key establishment.  The remaining extensions are sent separately in the EncryptedExtensions message. </del>  For backward compatibility reasons with middleboxes (see middlebox) the HelloRetryRequest message uses the same structure as the HelloRetryRequest and otherwise abort the handshake with an "illegal_parameter" alert.  4.2. A number of TLS messages contain tag-length-value encoded extensions

Reviewer comments:
Issue 1: supportedversions is required in TLS 1.3 SH. Issue 2: supportedversions.selected_version must be identical in HRR and SH
NAME please submit a PR to add yourself to acknowledgements
Thanks for the fixup.

Revised text:
A list of extensions.  The ServerHello MUST only include extensions which are required to establish the cryptographic  <ins> context and negotiate the protocol version.  All TLS 1.3 ServerHello messages MUST contain the "supported_versions" extension.  Current ServerHello messages contain either the "pre_shared_key" or "key_share" extensions, or both when using a PSK with (EC)DHE key establishment.  The remaining extensions are sent separately in the EncryptedExtensions message. </ins> For backward compatibility reasons with middleboxes (see middlebox) the HelloRetryRequest message uses the same structure as the HelloRetryRequest and otherwise abort the handshake with an "illegal_parameter" alert. <ins> The value of selected_version in the HelloRetryRequest "supported_versions" extension MUST be retained in the ServerHello, and a client MUST abort the handshake with an "illegal_parameter" alert if the value changes. </ins> 4.2. A number of TLS messages contain tag-length-value encoded extensions
Original text:
cipher suites.  (see cipher-suites) A TLS-compliant application MUST support digital signatures with <del> rsa_pkcs1_sha256 (for certificates), rsa_pss_rsae_sha256_ (for </del>  CertificateVerify and certificates), and ecdsa_secp256r1_sha256.  A TLS-compliant application MUST support key exchange with secp256r1 (NIST P-256) and SHOULD support key exchange with X25519 RFC7748.

Reviewer comments:
remove extra _ at the end of name -- the name in SignatureScheme enum lacks it

Revised text:
cipher suites.  (see cipher-suites) A TLS-compliant application MUST support digital signatures with  <ins> rsa_pkcs1_sha256 (for certificates), rsa_pss_rsae_sha256 (for </ins> CertificateVerify and certificates), and ecdsa_secp256r1_sha256.  A TLS-compliant application MUST support key exchange with secp256r1 (NIST P-256) and SHOULD support key exchange with X25519 RFC7748.
Original text:
This document describes TLS 1.3, which uses the version 0x0304.  This version value is historical, deriving from the use of 0x0301 for TLS 1.0 and 0x0300 for SSL 3.0.  In order to maximize backwards <del> compatibility, records containing an initial ClientHello MUST have </del>  version 0x0301 and a record containing a second ClientHello or a ServerHello MUST have version 0x0303, reflecting TLS 1.0 and TLS 1.2 respectively.  When negotiating prior versions of TLS, endpoints

Reviewer comments:
says: But the following text follows: MAY and MUST mismatch. Let's s/MUST/SHOULD/

Revised text:
This document describes TLS 1.3, which uses the version 0x0304.  This version value is historical, deriving from the use of 0x0301 for TLS 1.0 and 0x0300 for SSL 3.0.  In order to maximize backwards  <ins> compatibility, records containing an initial ClientHello SHOULD have </ins> version 0x0301 and a record containing a second ClientHello or a ServerHello MUST have version 0x0303, reflecting TLS 1.0 and TLS 1.2 respectively.  When negotiating prior versions of TLS, endpoints
Original text:
(*) indicates changes to the wire protocol which may require implementations to update.  draft-25 - Add the header to additional data (*) Minor clarifications. ClientHellos that include this extension but do not include 0x0304 in the list of versions. <del> A server which negotiates TLS 1.3 MUST respond by sending a "supported_versions" extension containing the selected version value (0x0304).  It MUST set the ServerHello.legacy_version field to 0x0303 (TLS 1.2).  Clients MUST check for this extension prior to processing the rest of the ServerHello (although they will have to parse the ServerHello in order to read the extension).  If this extension is present, clients MUST ignore the ServerHello.legacy_version value and MUST use only the "supported_versions" extension to determine the selected version.  If the "supported_versions" extension contains a version not offered by the client, the client MUST abort the handshake with an "illegal_parameter" alert. </del>  4.2.1.1.

Reviewer comments:
LGTM!
This is natural, since if you negotiate prior to 1.3 you must use the ServerHello rules for the negotiated URL

Revised text:
(*) indicates changes to the wire protocol which may require implementations to update. <ins> draft-26 - Clarify that you can't negotiate pre-TLS 1.3 with supported_versions. </ins> draft-25 - Add the header to additional data (*) Minor clarifications. ClientHellos that include this extension but do not include 0x0304 in the list of versions.  <ins> A server which negotiates a version of TLS prior to TLS 1.3 MUST set ServerHello.version and MUST NOT send the "supported_versions" extension.  A server which negotiates TLS 1.3 MUST respond by sending a "supported_versions" extension containing the selected version value (0x0304).  It MUST set the ServerHello.legacy_version field to 0x0303 (TLS 1.2).  Clients MUST check for this extension prior to processing the rest of the ServerHello (although they will have to parse the ServerHello in order to read the extension).  If this extension is present, clients MUST ignore the ServerHello.legacy_version value and MUST use only the "supported_versions" extension to determine the selected version.  If the "supported_versions" extension contains a version not offered by the client or contains a version prior to TLS 1.3, the client MUST abort the handshake with an "illegal_parameter" alert. </ins> 4.2.1.1.
Original text:
"OPTIONAL" in this document are to be interpreted as described in RFC 2119 RFC2119.  1.2. draft-06

Reviewer comments:
PR for suggestion for issue .
Is this helping?
Glossaries are usually a good thing, but pretty much everything in there is either in need of pruning out or is better explained in its relevant section. The HTTP/2 spec just includes a really short glossary of basic terms up top: URL This seems like a better way to do this.
Not sure if this is the best route, but creating a PR for it was quick to do.
I'm in favor of removing the glossary. I don't think there's any need to explain what AES, DSA, etc. is in this document. Maybe it was needed when it first came out but it's not needed now. The only definition I thought might be needed is application layer/application layer protocol, but if you read s1 (right before where these terms will go) the concepts of layering on top of TLS is explained well enough in my mind. I could see adding a definition for "resumption" though.
Define resumption in-line with the text when it is first used, maybe. But I like Dave's change.
I can live with that too. Having it defined will hopefully stop these kind of things: URL
Merged.

Revised text:
"OPTIONAL" in this document are to be interpreted as described in RFC 2119 RFC2119. <ins> The following terms are used: client: The endpoint initiating the TLS connection. connection: A transport-layer connection between two endpoints. endpoint: Either the client or server of the connection. handshake: An initial negotiation between client and server that establishes the parameters of their transactions. peer: An endpoint.  When discussing a particular endpoint, "peer" refers to the endpoint that is remote to the primary subject of discussion. receiver: An endpoint that is receiving records. sender: An endpoint that is transmitting records. session: An association between a client and a server resulting from a handshake. server: The endpoint which did not initiate the TLS connection. </ins> 1.2. draft-06
Original text:
exporter_master_secret unless explicitly specified by the application.  The early_exporter_master_secret is defined for use in settings where an exporter is needed for 0-RTT data.  A separate <del> interface for the early exporter is RECOMMENDED. </del>  If no context is provided, the context_value is zero-length. Consequently, providing no context computes the same value as

Reviewer comments:
We currently have which is a little confusing, since it doesn't note that the server has the non-early exporter available once it has generated its first flight, and doubly so since the actual motivation for separate interfaces is for security reasons of not accidentally using the early exporter when the main one is needed. (Split out from )

Revised text:
exporter_master_secret unless explicitly specified by the application.  The early_exporter_master_secret is defined for use in settings where an exporter is needed for 0-RTT data.  A separate  <ins> interface for the early exporter is RECOMMENDED; this avoids the exporter user accidentally using an early exporter when a regular one is desired or vice versa. </ins> If no context is provided, the context_value is zero-length. Consequently, providing no context computes the same value as