jiebi/TextFlow huggingface dataset:
Original text:
zero, which corresponds to the "null" compression method in prior versions of TLS.  If a TLS 1.3 ClientHello is received with any other value in this field, the server MUST generate a fatal <del> "illegal_parameter" alert.  Note that TLS 1.3 servers may receive TLS 1.2 or prior ClientHellos which contain other compression methods and MUST follow the procedures for the appropriate prior version of TLS. </del>  Clients MAY request extended functionality from servers by sending that is not advertised as being supported in the signature_algorithms extension. <del> Note: TLS 1.3 servers MAY receive TLS 1.2 ClientHellos which do not </del>  contain this extension.  If those servers are willing to negotiate TLS 1.2, they MUST behave in accordance with the requirements of RFC5246 when negotiating that version.

Reviewer comments:
When talking about handling downlevel clients, the spec variously says a server "MAY" receive such messages, or "may" receive such messages. Since this is discussing a possibility (not a permitted behavior), the normative language isn't correct; lower-case versions of the RFC2119 terms have the potential to confuse readers. Suggest changing all of these to "might" to denote a possible occurrence server implementers will need to handle.
Yes, this looks like an improvement.
LGTM

Revised text:
zero, which corresponds to the "null" compression method in prior versions of TLS.  If a TLS 1.3 ClientHello is received with any other value in this field, the server MUST generate a fatal  <ins> "illegal_parameter" alert.  Note that TLS 1.3 servers might receive TLS 1.2 or prior ClientHellos which contain other compression methods and MUST follow the procedures for the appropriate prior version of TLS. </ins> Clients MAY request extended functionality from servers by sending that is not advertised as being supported in the signature_algorithms extension.  <ins> Note: TLS 1.3 servers might receive TLS 1.2 ClientHellos which do not </ins> contain this extension.  If those servers are willing to negotiate TLS 1.2, they MUST behave in accordance with the requirements of RFC5246 when negotiating that version.
Original text:
The certificate MUST allow the key to be used for signing (i.e., the digitalSignature bit MUST be set if the key usage extension is present) with the signature scheme and hash algorithm that will be <del> employed in the server's KeyShare extension. </del>  An ECDSA or EdDSA public key MUST use a curve and point format supported by the client, as described in RFC4492.

Reviewer comments:
This section has a strange table that looked a little messy. So I cleaned that up. However, I noticed that it used to say this: Which doesn't make any sense. Should this be signature_algorithms extension instead?

Revised text:
The certificate MUST allow the key to be used for signing (i.e., the digitalSignature bit MUST be set if the key usage extension is present) with the signature scheme and hash algorithm that will be  <ins> employed in the server's signature_algorithms extension. </ins> An ECDSA or EdDSA public key MUST use a curve and point format supported by the client, as described in RFC4492.
Original text:
1-RTT handshake keys until it finds one that decrypts properly, and then pick up the handshake from that point.  [[TODO: How does the client behave if the indication is rejected.]] [[OPEN ISSUE: This just specifies the signaling for 0-RTT but not the

Reviewer comments:
Proposed clarification based on mailing list discussion. Explicitly state that 0-RTT records MUST NOT get special treatment and 1-RTT fallback on decryption errors is prohibited. This may technically already be the intended situation, however any ambiguity here will undoubtedly lead to some implementations falling back to avoid breakage in this scenario, which risks 0-RTT data stripping attacks. As I agree with the expected behavior stated by NAME on-list, this is just a matter of adding some clarification here (even if it might be redundant; someone interpreting the text the way I initially did could do something dangerous if they don't also notice the risk).

Revised text:
1-RTT handshake keys until it finds one that decrypts properly, and then pick up the handshake from that point. <ins> Servers MUST comply with the same error handling requirements specified for all records when processing early data records and MUST NOT fall back to 1-RTT on any such errors.  Specifically, decryption failure of any 0-RTT record following an accepted "early_data" extension MUST produce a fatal "bad_record_mac" alert as per record- payload-protection. </ins> [[TODO: How does the client behave if the indication is rejected.]] [[OPEN ISSUE: This just specifies the signaling for 0-RTT but not the
Original text:
1-RTT handshake keys until it finds one that decrypts properly, and then pick up the handshake from that point. <del> If the server choosed to accept the "early_data" extension, then it </del>  MUST comply with the same error handling requirements specified for all records when processing early data records.  Specifically, decryption failure of any 0-RTT record following an accepted The cipher suite identifier. <del> If (EC)DHE is being used, the server's version of "key_share". </del>  If PSK is being used, the server's version of the "pre_shared_key" <del> (indicating the PSK the client is using). </del>  6.3.2.5.2. exception of the end-entity certificate which MUST be first. The server's certificate list MUST always be non-empty.  A client <del> will MAY send an empty certificate list if it does not have an </del>  appropriate certificate to send in response to the server's authentication request.

Reviewer comments:
This should be "chose" not "choosed", which isn't really an accepted word.
Added another commit here for a minor wording fix that snuck in with changing all extensions to be referred to by type ID name.
Ok, I switched it to "chooses" instead & squashed my little fixes together here. There's also a fix for the "will MAY" bit that I think we discussed at some point but its fix didn't get in.

Revised text:
1-RTT handshake keys until it finds one that decrypts properly, and then pick up the handshake from that point.  <ins> If the server chooses to accept the "early_data" extension, then it </ins> MUST comply with the same error handling requirements specified for all records when processing early data records.  Specifically, decryption failure of any 0-RTT record following an accepted The cipher suite identifier.  <ins> If (EC)DHE is being used, the server's version of the "key_share" extension. </ins> If PSK is being used, the server's version of the "pre_shared_key"  <ins> extension (indicating the PSK the client is using). </ins> 6.3.2.5.2. exception of the end-entity certificate which MUST be first. The server's certificate list MUST always be non-empty.  A client  <ins> will send an empty certificate list if it does not have an </ins> appropriate certificate to send in response to the server's authentication request.
Original text:
in CertificateVerify, regardless of whether SHA-1 appears in "signature_algorithms". <del> Note: when used with non-certificate-based handshakes (e.g., PSK), </del>  the client's signature does not cover the server's certificate directly, although it does cover the server's Finished message, which transitively includes the server's certificate when the PSK derives may be updated throughout the connection as described in updating- traffic-keys. <del> Note: although the steps above are phrased as individual HKDF-Extract </del>  and HKDF-Expand operations, because each HKDF-Expand operation is paired with an HKDF-Extract, it is possible to implement this key schedule with a black-box HKDF API, albeit at some loss of efficiency

Reviewer comments:
One more minor fix I just noticed when diffing the latest draft. Just capitalization fixes to match the other notes.

Revised text:
in CertificateVerify, regardless of whether SHA-1 appears in "signature_algorithms".  <ins> Note: When used with non-certificate-based handshakes (e.g., PSK), </ins> the client's signature does not cover the server's certificate directly, although it does cover the server's Finished message, which transitively includes the server's certificate when the PSK derives may be updated throughout the connection as described in updating- traffic-keys.  <ins> Note: Although the steps above are phrased as individual HKDF-Extract </ins> and HKDF-Expand operations, because each HKDF-Expand operation is paired with an HKDF-Extract, it is possible to implement this key schedule with a black-box HKDF API, albeit at some loss of efficiency
Original text:
at the end of the ClientHello.  Note that this method of detecting optional data differs from the normal TLS method of having a variable-length field, but it is used for compatibility with TLS <del> before extensions were defined. </del>  The version of the TLS protocol by which the client wishes to appropriate prior version of TLS. <del> Clients MAY request extended functionality from servers by sending </del>  data in the extensions field.  The actual "Extension" format is defined in hello-extensions. Structure of this message: %%% Key Exchange Messages struct { ProtocolVersion server_version; <del> Random random; CipherSuite cipher_suite; select (extensions_present) { case false: struct {}; case true: Extension extensions<0..2^16-1>; }; } ServerHello; </del>  <del> The presence of extensions can be detected by determining whether there are bytes following the cipher_suite field at the end of the ServerHello. </del>  This field will contain the lower of that suggested by the client

Reviewer comments:
Small simplification & clarification. Now that the server key share is in an extension, all TLS 1.3 endpoints will have at least one extension in their hello, either "keyshare" or "preshared_key", at minimum. This changeset simplifies the ServerHello struct in the same manner as was previously done for ClientHello and adds short notes explicitly stating this.

Revised text:
at the end of the ClientHello.  Note that this method of detecting optional data differs from the normal TLS method of having a variable-length field, but it is used for compatibility with TLS  <ins> before extensions were defined.  As of TLS 1.3, all clients and servers will send at least one extension (at least "key_share" or "pre_shared_key"). </ins> The version of the TLS protocol by which the client wishes to appropriate prior version of TLS.  <ins> Clients request extended functionality from servers by sending </ins> data in the extensions field.  The actual "Extension" format is defined in hello-extensions. Structure of this message: %%% Key Exchange Messages struct { ProtocolVersion server_version;  <ins> Random random; CipherSuite cipher_suite; Extension extensions<0..2^16-1>; } ServerHello; </ins>  <ins> In prior versions of TLS, the extensions field could be omitted entirely if not needed, similar to ClientHello.  As of TLS 1.3, all clients and servers will send at least one extension (at least "key_share" or "pre_shared_key"). </ins> This field will contain the lower of that suggested by the client
Original text:
For X25519 and X448, see RFC7748.  8. 8.1.

Reviewer comments:
NAME sanity check?
This isn't going to change a great deal, but we need to identify how exporters are constructed with the change to a HKDF-based PRF and the new key schedule.

Revised text:
For X25519 and X448, see RFC7748. <ins> 7.3.4. RFC5705 defines keying material exporters for TLS in terms of the TLS PRF.  This document replaces the PRF with HKDF, thus requiring a new construction.  The exporter interface remains the same, however the value is computed as: Note: the inner HKDF-Extract is strictly unnecessary, but it maintains the invariant that HKDF Extract and Expand calls are paired. </ins> 8. 8.1.
Original text:
generation of keys until it receives the KeyUpdate from the other side.  7. In order to begin connection protection, the TLS Record Protocol

Reviewer comments:
The current wording of KeyUpdate a bit ambiguous, and leaves out certain areas needed for enforcement and might result in a security issue if not implemented correctly A sender of the keyupdate has no choice of which key to encrypt the keyupdate with, however the recipient does. It has 2 choices: a. Use old key and reset the sequence number after acking the keyupdate b. Use the new key for the key update and reset the sequence number before acking the keyupdate. This distinction is very important for security. If a client uses option b), this causes a security vuln. Because the sequence numbers are reset after a key update, an attacker could truncate (application data) records from the old stream, wait for the key update from the client, and then let new packets through. The client or server has no way of figuring out this has happened. If a receiver verifies that the KeyUpdate is received with the old key before accepting messages encrypted with the new key, then this attack is prevented.
Excellent point. I will merge this. Please also file a PR adding yourself to acknowledgements.

Revised text:
generation of keys until it receives the KeyUpdate from the other side. <ins> Both sender and receiver must encrypt their KeyUpdate messages with the old keys.  Additionally, both sides MUST enforce that a KeyUpdate with the old key is received before accepting any messages encrypted with the new key.  Failure to do so may allow message truncation attacks. </ins> 7. In order to begin connection protection, the TLS Record Protocol
Original text:
Diffie-Hellman DH parameters for both clients and servers are encoded in the opaque key_exchange field of a KeyShareEntry in a KeyShare structure.  The opaque value contains the Diffie-Hellman public value <del> (dh_Y = g^X mod p), encoded as a big-endian integer. </del>  %%% Key Exchange Messages opaque dh_Y<1..2^16-1>;

Reviewer comments:
TLS 1.2 did not specify this and some implementations have sporadic interoperability issues as a result. Specify that, in TLS 1.3, public keys should be zero-padded. This is believed to be the more compatible TLS 1.2 variant, and having cryptographic messages be fixed-width fields where possible (not that it matters for public keys) seems preferable to saving one byte 1/256 of the time.
(Er, that should say "DHE public keys". I'll go do a force-push to fix the commit description.)
We seem to have reached consensus that the record layer will use the AEAD form only. The stream and CBC forms will be removed.
Fixed.

Revised text:
Diffie-Hellman DH parameters for both clients and servers are encoded in the opaque key_exchange field of a KeyShareEntry in a KeyShare structure.  The opaque value contains the Diffie-Hellman public value  <ins> (dh_Y = g^X mod p), encoded as a big-endian integer, padded with zeros to the size of p. Note: For a given Diffie-Hellman group, the padding results in all public keys having the same length. </ins> %%% Key Exchange Messages opaque dh_Y<1..2^16-1>;
Original text:
takes as input an arbitrary-length message, rather than a digest. Algorithms which traditionally act on a digest should be defined in TLS to first hash the input with a specified hash function and then <del> proceed as usual. </del>  Indicates a signature algorithm using RSASSA-PKCS1-v1_5 RFC3447

Reviewer comments:
The definition is all "etcetera" currently. We should not assume that readers can parse out the hash algorithm from the enum label.

Revised text:
takes as input an arbitrary-length message, rather than a digest. Algorithms which traditionally act on a digest should be defined in TLS to first hash the input with a specified hash function and then  <ins> proceed as usual.  The code point groups listed above have the following meanings: </ins> Indicates a signature algorithm using RSASSA-PKCS1-v1_5 RFC3447
Original text:
transmitted as specified by the current active session state. %%% Handshake Protocol enum { hello_request_RESERVED(0), <del> client_hello(1), server_hello(2), session_ticket(4), </del>  hello_retry_request(6), encrypted_extensions(8), certificate(11), server_key_exchange_RESERVED(12), certificate_request(13), server_hello_done_RESERVED(14), certificate_verify(15), Action RFC2434. TLS HandshakeType Registry: Future values are allocated via <del> Standards Action RFC2434. </del>  This document also uses a registry originally created in RFC4366. IANA has updated it to reference this document.  The registry and its

Reviewer comments:
This is purely aesthetic, but apparently no one realizes the name is different, not even IANA, so we may as well go fix it. (I don't know how to write IANA considerations, so I've left it a TODO. But if you give me text, I'll update this PR to include it.) For consistency. At a glance, it seems most TLS implementations did not realize the HandshakeType value was actually named sessionticket and assumed it was named newsession_ticket anyway. Moreover, the IANA entry was named neither and actually named NewSessionTicket since RFC 4507's IANA considerations used the wrong name.

Revised text:
transmitted as specified by the current active session state. %%% Handshake Protocol enum { hello_request_RESERVED(0),  <ins> client_hello(1), server_hello(2), new_session_ticket(4), </ins> hello_retry_request(6), encrypted_extensions(8), certificate(11), server_key_exchange_RESERVED(12), certificate_request(13), server_hello_done_RESERVED(14), certificate_verify(15), Action RFC2434. TLS HandshakeType Registry: Future values are allocated via  <ins> Standards Action RFC2434.  IANA [SHALL update/has updated] this registry to rename item 4 from "NewSessionTicket" to "new_session_ticket". </ins> This document also uses a registry originally created in RFC4366. IANA has updated it to reference this document.  The registry and its
Original text:
"key_share" or "pre_shared_key"). <del> This field will contain the lower of that suggested by the client in the ClientHello and the highest supported by the server. Servers MUST accept ClientHello versions higher than those supported.  For this version of the specification, the version is { 3, 4 }.  (See backward-compatibility for details about backward compatibility.) </del>  This structure is generated by the server and MUST be generated

Reviewer comments:
People will continue getting this wrong until the end of time, but add an extra MUST in the serverversion half on the off chance someone reads it. Also clarify that clientversion is a maximum version. ("The version of the TLS protocol by which the client wishes to communicate during this session" suggests it should be an exact match.)

Revised text:
"key_share" or "pre_shared_key").  <ins> This field contains the version of TLS negotiated for this session.  Servers MUST select the lower of the highest supported version and the version offered by the client in the ClientHello. In particular, servers MUST accept ClientHello messages with versions higher than those supported and negotiate the highest mutually supported version.  For this version of the specification, the version is { 3, 4 }.  (See backward- compatibility for details about backward compatibility.) </ins> This structure is generated by the server and MUST be generated
Original text:
The connection is reliable.  Messages include an authentication tag which protects them against modification. <del> Note: The TLS Record Protocol can operate in an insecure mode but is generally only used in this mode while another protocol is using the TLS Record Protocol as a transport for negotiating security parameters. </del> The TLS Record Protocol is used for encapsulation of various higher- level protocols.  One such encapsulated protocol, the TLS Handshake Protocol, allows the server and client to authenticate each other and

Reviewer comments:
and arguably should never be used in that fashion. I know that this stuff badly needs a rewrite, but this is just egregious.

Revised text:
The connection is reliable.  Messages include an authentication tag which protects them against modification.  The TLS Record Protocol is used for encapsulation of various higher- level protocols.  One such encapsulated protocol, the TLS Handshake Protocol, allows the server and client to authenticate each other and
Original text:
designated digitally-signed, and aead-ciphered, respectively.  A field's cryptographic processing is specified by prepending an appropriate key word designation before the field's type <del> specification.  Cryptographic keys are implied by the current session state (see connection-states). </del>  4.8.1. Specifies the authentication and key establishment algorithms, the hash for use with HKDF to generate keying material, and the record <del> protection algorithm (See the-security-parameters for formal definition.) </del>  a secret shared between the client and server that can be used as a pre-shared symmetric key (PSK) in future connections.

Reviewer comments:
The section on connection states was almost all cruft. I made a new section for nonce construction and moved the piece on sequence numbers there. The only text I modified was the first three paragraphs of the nonce section, which needed to be scrubbed for references to "connection state", and the lead-in section on the AEAD, which I moved to where the other AEAD stuff was and expanded a little to include some forward references.
LGTM NAME Did you still want to replace any of this? The stuff being cut here is very obsolete and must confuse anyone who attempts to read through the whole spec.
Yes, I'm working on it this week. , Dave Garrett EMAIL wrote:

Revised text:
designated digitally-signed, and aead-ciphered, respectively.  A field's cryptographic processing is specified by prepending an appropriate key word designation before the field's type  <ins> specification. </ins> 4.8.1. Specifies the authentication and key establishment algorithms, the hash for use with HKDF to generate keying material, and the record  <ins> protection algorithm </ins> a secret shared between the client and server that can be used as a pre-shared symmetric key (PSK) in future connections.
Original text:
The "extension_data" field of this extension contains a "supported_signature_algorithms" value: <del> %%% Signature Algorithm Extension enum { /* RSASSA-PKCS-v1_5 </del>  algorithms */ rsa_pkcs1_sha1 (0x0201), rsa_pkcs1_sha256 (0x0401), rsa_pkcs1_sha384 (0x0501), rsa_pkcs1_sha512 (0x0601), In addition, the signature algorithm MUST be compatible with the key in the sender's end-entity certificate.  RSA signatures MUST <del> use an RSASSA-PSS algorithm, regardless of whether RSASSA-PKCS- v1_5 algorithms appear in "signature_algorithms".  SHA-1 MUST NOT be used in any signatures in CertificateVerify.  (Note that rsa_pkcs1_sha1 and dsa_sha1, the only defined SHA-1 signature </del>  algorithms, are undefined for CertificateVerify signatures.) Note: When used with non-certificate-based handshakes (e.g., PSK),

Reviewer comments:
RFC 3447 refers to it as RSASSA-PKCS1-v15, not RSASSA-PKCS-v15.

Revised text:
The "extension_data" field of this extension contains a "supported_signature_algorithms" value:  <ins> %%% Signature Algorithm Extension enum { /* RSASSA-PKCS1-v1_5 </ins> algorithms */ rsa_pkcs1_sha1 (0x0201), rsa_pkcs1_sha256 (0x0401), rsa_pkcs1_sha384 (0x0501), rsa_pkcs1_sha512 (0x0601), In addition, the signature algorithm MUST be compatible with the key in the sender's end-entity certificate.  RSA signatures MUST  <ins> use an RSASSA-PSS algorithm, regardless of whether RSASSA- PKCS1-v1_5 algorithms appear in "signature_algorithms".  SHA-1 MUST NOT be used in any signatures in CertificateVerify.  (Note that rsa_pkcs1_sha1 and dsa_sha1, the only defined SHA-1 signature </ins> algorithms, are undefined for CertificateVerify signatures.) Note: When used with non-certificate-based handshakes (e.g., PSK),