jiebi/TextFlow huggingface dataset:
Original text:
RFC5705 defines keying material exporters for TLS in terms of the TLS pseudorandom function (PRF).  This document replaces the PRF with HKDF, thus requiring a new construction.  The exporter interface <del> remains the same.  If context is provided, the value is computed as: </del>  Where Secret is either the early_exporter_secret or the exporter_secret.  Implementations MUST use the exporter_secret unless <del> explicitly specified by the application.  When adding TLS 1.3 to TLS 1.2 stacks, the exporter_secret MUST be for the existing exporter interface. If no context is provided, the value is computed as above but with a zero-length context_value.  Note that providing no context computes the same value as providing an empty context.  As of this document's publication, no allocated exporter label is used with both modes. Future specifications MUST NOT provide an empty context and no context with the same label and SHOULD provide a context, possibly empty, in all exporter computations. </del>  8.

Reviewer comments:
I found the wording a little hard to follow. This also by being very explicit about the presence of the change.
This changeset includes some "URL" cruft that isn't part of a reword.
In previous versions of TLS, passing no context was different to passing an empty context. TLS 1.3 doesn't distinguish between these. I don't know how important it is to highlight that minor difference, but it's probably worth mentioning.
So I should read more carefully: there is text about this, but it's not clear that this is a change from previous versions.

Revised text:
RFC5705 defines keying material exporters for TLS in terms of the TLS pseudorandom function (PRF).  This document replaces the PRF with HKDF, thus requiring a new construction.  The exporter interface  <ins> remains the same. The exporter value is computed as: </ins> Where Secret is either the early_exporter_secret or the exporter_secret.  Implementations MUST use the exporter_secret unless  <ins> explicitly specified by the application.  A separate interface for the early exporter is RECOMMENDED, especially on a server where a single interface can make the early exporter inaccessible. If no context is provided, the context_value is zero-length. Consequently, providing no context computes the same value as providing an empty context.  This is a change from previous versions of TLS where an empty context produced a different output to an absent context.  As of this document's publication, no allocated exporter label is used both with and without a context.  Future specifications MUST NOT define a use of exporters that permit both an empty context and no context with the same label.  New uses of exporters SHOULD provide a context in all exporter computations, though the value could be empty. </ins> 8.
Original text:
The server processes the ClientHello and determines the appropriate cryptographic parameters for the connection.  It then responds with <del> its own ServerHello, which indicates the negotiated connection parameters. [server-hello].  The combination of the ClientHello and the ServerHello determines the shared keys.  If (EC)DHE key establishment is in use, then the ServerHello contains a "key_share" extension with the server's ephemeral Diffie-Hellman share which MUST be in the same group as one of the client's shares.  If PSK key establishment is in use, then the ServerHello contains a "pre_shared_key" extension indicating which of the client's offered PSKs was selected.  Note that implementations can use (EC)DHE and PSK together, in which case both extensions will be supplied. </del>  The server then sends two messages to establish the Server Parameters: to continue. Sent by a server in response to an invalid connection retry <del> attempt from a client. (see [RFC7507]) </del>  Sent by endpoints that receive a hello message not containing an extension that is mandatory to send for the offered TLS version or

Reviewer comments:
Most of these are simple enough, kramdown treats all bracketed text as a reference. So these can be replaced with and the warnings go away. The biggest change here is slightly stylistic: a few places had , which kramdown complained about, but rendered correctly. However, this produced a non-sentence. Also, I fixed some inconsistent use of references and s/data/date in one of the references.
See comment

Revised text:
The server processes the ClientHello and determines the appropriate cryptographic parameters for the connection.  It then responds with  <ins> its own ServerHello (server-hello), which indicates the negotiated connection parameters.  The combination of the ClientHello and the ServerHello determines the shared keys.  If (EC)DHE key establishment is in use, then the ServerHello contains a "key_share" extension with the server's ephemeral Diffie-Hellman share which MUST be in the same group as one of the client's shares.  If PSK key establishment is in use, then the ServerHello contains a "pre_shared_key" extension indicating which of the client's offered PSKs was selected.  Note that implementations can use (EC)DHE and PSK together, in which case both extensions will be supplied. </ins> The server then sends two messages to establish the Server Parameters: to continue. Sent by a server in response to an invalid connection retry  <ins> attempt from a client RFC7507. </ins> Sent by endpoints that receive a hello message not containing an extension that is mandatory to send for the offered TLS version or
Original text:
A list of offered KeyShareEntry values in descending order of client preference.  This vector MAY be empty if the client is <del> requesting a HelloRetryRequest.  The ordering of values here SHOULD match that of the ordering of offered support in the "supported_groups" extension. </del>  The mutually supported group the server intends to negotiate and is requesting a retried ClientHello/KeyShare for.

Reviewer comments:
This is a redo of PR now that PR has removed the appending rule and resolved issue .

Revised text:
A list of offered KeyShareEntry values in descending order of client preference.  This vector MAY be empty if the client is  <ins> requesting a HelloRetryRequest.  Each KeyShareEntry value MUST correspond to a group offered in the "supported_groups" extension and MUST appear in the same order.  However, the values MAY be a non-contiguous subset of the "supported_groups" extension and MAY omit the most preferred groups. </ins> The mutually supported group the server intends to negotiate and is requesting a retried ClientHello/KeyShare for.
Original text:
PSK (a pre-shared key established externally or a resumption_master_secret value from a previous connection) <del> (EC)DHE shared secret </del>  This produces a full key derivation schedule shown in the diagram below.  In this diagram, the following formatting conventions apply: Secret changes (e.g., when changing from the handshake to application data keys or upon a key update). <del> 7.3.1. </del>  <del> A conventional Diffie-Hellman computation is performed.  The negotiated key (Z) is converted to byte string by encoding in big- endian, padded with zeros up to the size of the prime.  This byte string is used as the shared secret, and is used in the key schedule as specified above. </del>  Note that this construction differs from previous versions of TLS which remove leading zeros. <del> 7.3.2. </del>  For secp256r1, secp384r1 and secp521r1, ECDH calculations (including parameter and key generation as well as the shared secret For X25519 and X448, see RFC7748. <del> 7.3.3. </del>  RFC5705 defines keying material exporters for TLS in terms of the TLS pseudorandom function (PRF).  This document replaces the PRF with

Reviewer comments:
Exporters and (EC)DHE secrets are not traffic secrets. Group the two (EC)DHE sections under a name which matches what the key schedule section calls it (the "(EC)DHE shared secret") and link to it from the key schedule.

Revised text:
PSK (a pre-shared key established externally or a resumption_master_secret value from a previous connection)  <ins> (EC)DHE shared secret (ecdhe-shared-secret-calculation) </ins> This produces a full key derivation schedule shown in the diagram below.  In this diagram, the following formatting conventions apply: Secret changes (e.g., when changing from the handshake to application data keys or upon a key update).  <ins> 7.4. </ins>  <ins> 7.4.1. For finite field groups, a conventional Diffie-Hellman computation is performed.  The negotiated key (Z) is converted to byte string by encoding in big-endian, padded with zeros up to the size of the prime.  This byte string is used as the shared secret, and is used in the key schedule as specified above. </ins> Note that this construction differs from previous versions of TLS which remove leading zeros.  <ins> 7.4.2. </ins> For secp256r1, secp384r1 and secp521r1, ECDH calculations (including parameter and key generation as well as the shared secret For X25519 and X448, see RFC7748.  <ins> 7.5. </ins> RFC5705 defines keying material exporters for TLS in terms of the TLS pseudorandom function (PRF).  This document replaces the PRF with
Original text:
the server to allow the server to decline resumption and fall back to a full handshake, if needed.  The server responds with a "pre_shared_key" extension to negotiate use of PSK key establishment <del> and can (as shown here) to negotiate use of PSK key establishment and can (as shown here) respond with a "key_share" extension to do </del>  (EC)DHE key establishment, thus providing forward secrecy. When PSKs are provisioned out of band, the PSK identity and the KDF The Server Name Indication (SNI), if any is to be used <del> As shown in tls-0-rtt, the Zero-RTT data is just added to the 1-RTT </del>  handshake in the first flight.  The rest of the handshake uses the same messages as with a 1-RTT handshake with PSK resumption. the elements of the enumerated are not ordered, they can be assigned any unique value, in any order. <del> Future extension or additions to the protocol may define new values. </del>  Implementations need to be able to parse and ignore unknown values unless the definition of the field states otherwise. extensions which are required to establish the cryptographic context.  Currently the only such extensions are "key_share" and "pre_shared_key".  All current TLS 1.3 ServerHello messages will <del> contain one of these two extensions. </del>  TLS 1.3 has a downgrade protection mechanism embedded in the server's random value.  TLS 1.3 servers which negotiate TLS 1.2 or below in

Reviewer comments:
Reading through the spec again I found a few tiny things to fix. I'm suggesting to replace "Zero-RTT" with "0-RTT" in the paragraph because I found "Zero-RTT" used only in headlines, but "0-RTT" consistently in paragraphs.
NAME Please provide a PR to add yourself to acknowledgements.

Revised text:
the server to allow the server to decline resumption and fall back to a full handshake, if needed.  The server responds with a "pre_shared_key" extension to negotiate use of PSK key establishment  <ins> and can (as shown here) respond with a "key_share" extension to do </ins> (EC)DHE key establishment, thus providing forward secrecy. When PSKs are provisioned out of band, the PSK identity and the KDF The Server Name Indication (SNI), if any is to be used  <ins> As shown in tls-0-rtt, the 0-RTT data is just added to the 1-RTT </ins> handshake in the first flight.  The rest of the handshake uses the same messages as with a 1-RTT handshake with PSK resumption. the elements of the enumerated are not ordered, they can be assigned any unique value, in any order.  <ins> Future extensions or additions to the protocol may define new values. </ins> Implementations need to be able to parse and ignore unknown values unless the definition of the field states otherwise. extensions which are required to establish the cryptographic context.  Currently the only such extensions are "key_share" and "pre_shared_key".  All current TLS 1.3 ServerHello messages will  <ins> contain one of these two extensions, or both when using a PSK with (EC)DHE key establishment. </ins> TLS 1.3 has a downgrade protection mechanism embedded in the server's random value.  TLS 1.3 servers which negotiate TLS 1.2 or below in
Original text:
This structure is intended to prevent an attack on previous versions of TLS in which the ServerKeyExchange format meant that attackers <del> could obtain a signature of a message with a chosen, 32-byte prefix. The initial 64 byte pad clears that prefix. </del>  The context string for a server signature is "TLS 1.3, server CertificateVerify" and for a client signature is "TLS 1.3, client <del> CertificateVerify". </del>  For example, if Hash(Handshake Context + Certificate) was 32 bytes of 01 (this length would make sense for SHA-256), the content covered by

Reviewer comments:
minor additions, the context string wasn't explained anywhere as well so I thought a mini-line would help.

Revised text:
This structure is intended to prevent an attack on previous versions of TLS in which the ServerKeyExchange format meant that attackers  <ins> could obtain a signature of a message with a chosen 32-byte prefix (ClientHello.random).  The initial 64 byte pad clears that prefix. </ins> The context string for a server signature is "TLS 1.3, server CertificateVerify" and for a client signature is "TLS 1.3, client  <ins> CertificateVerify".  It is used to provide separation between signatures made in different contexts, helping against potential cross-protocol attacks. </ins> For example, if Hash(Handshake Context + Certificate) was 32 bytes of 01 (this length would make sense for SHA-256), the content covered by
Original text:
4.1.3. The server will send this message in response to a ClientHello <del> message when it was able to find an acceptable set of algorithms and the client's "key_share" extension was acceptable.  If it is not able to find an acceptable set of parameters, the server will respond with a "handshake_failure" fatal alert. </del>  Structure of this message: 4.1.4. <del> Servers send this message in response to a ClientHello message if they were able to find an acceptable set of algorithms and groups that are mutually supported, but the client's ClientHello did not contain sufficient information to proceed with the handshake.  If a server cannot successfully select algorithms and groups, it MUST abort the handshake with a "handshake_failure" alert. </del>  Structure of this message:

Reviewer comments:
This is a giant pile of nitpicks, loosely inspired by the FFDHE alert discussion. The old text specifies a handshakefailure which is redundant with and contradicts the Cryptographic Negotiation section. The old text says only handshakefailure is allowed while Cryptographic Negotiation allows both handshakefailure and insufficientsecurity. Fix this by avoiding redundancy as the failure cases are global to the overall negotiation algorithm. Next, align the tense with itself and the rest of the text. Most of the text appears to be written in present tense. The old text for SH said: The server will send [...] when it was able to [...] which is a little odd. Also align the wording between the two. Talk about a server (singular) to match Cryptographic Negotiation and say "parameters" rather than "algorithms" or "algorithms and groups". Also be consistent about the SH vs. HRR condition. The SH section said "the client’s key_share extension was acceptable" while the HRR section said "the client’s ClientHello did not contain sufficient information to proceed with the handshake". Use the more general one.
Seems reasonable. I a little bit wondered whether to replace "it" with "the server", but the pronoun's meaning should be clear, here.
Seems clear enough to me, but I'm equally happy with the other wording. shrug
This does seem clearer. And shorter!

Revised text:
4.1.3. The server will send this message in response to a ClientHello  <ins> message if it is able to find an acceptable set of parameters and the ClientHello contains sufficient information to proceed with the handshake. </ins> Structure of this message: 4.1.4.  <ins> The server will send this message in response to a ClientHello message if it is able to find an acceptable set of parameters but the ClientHello does not contain sufficient information to proceed with the handshake. </ins> Structure of this message:
Original text:
data in the extensions field.  The actual "Extension" format is defined in extensions.  In TLS 1.3, use of certain extensions is mandatory, as functionality is moved into extensions to preserve <del> ClientHello compatibility with previous versions of TLS. </del>  In the event that a client requests additional functionality using extensions, and this functionality is not supplied by the server, the An optional set of extensions describing the parameters of the certificate being requested.  The "signature_algorithms" extension <del> MUST be specified. </del>  In prior versions of TLS, the CertificateRequest message carried a list of signature algorithms and certificate authorities which the

Reviewer comments:
Per the recent thread. I could have sworn this was in here, but can't find it... The NewSessionTicket section explicitly says to ignore unknown extensions, so I've added the analogous text to ClientHello and CertificateRequest.

Revised text:
data in the extensions field.  The actual "Extension" format is defined in extensions.  In TLS 1.3, use of certain extensions is mandatory, as functionality is moved into extensions to preserve  <ins> ClientHello compatibility with previous versions of TLS.  Servers MUST ignore unrecognized extensions. </ins> In the event that a client requests additional functionality using extensions, and this functionality is not supplied by the server, the An optional set of extensions describing the parameters of the certificate being requested.  The "signature_algorithms" extension  <ins> MUST be specified.  Clients MUST ignore unrecognized extensions. </ins> In prior versions of TLS, the CertificateRequest message carried a list of signature algorithms and certificate authorities which the
Original text:
exporters SHOULD provide a context in all exporter computations, though the value could be empty.  8. 8.1.

Reviewer comments:
Add reference to label format in 5705. address issue
refer the reader to exporter requirements in RFC 5705 "Requirements for the format of Exporter labels are defined in section 4 of RFC5705." Creating pull request.
NAME should we expect a PR?
This appears to be done.
yes I submitted PR which has been merged already.

Revised text:
exporters SHOULD provide a context in all exporter computations, though the value could be empty. <ins> Requirements for the format of exporter labels are defined in section 4 of RFC5705. </ins> 8. 8.1.
Original text:
Note: For a given Diffie-Hellman group, the padding results in all public keys having the same length. <del> Peers SHOULD validate each other's public key Y by ensuring that 1 < Y < p-1.  This check ensures that the remote peer is properly behaved </del>  and isn't forcing the local system into a small subgroup. 4.2.5.2.

Reviewer comments:
I wonder why this was only a before. Am I right to assume that this is because TLS 1.3 has removed support for static DH and leaking an ephemeral key is not considered to be a security problem?
Gotta say, I don't know why this was SHOULD. That check is very easy to implement.
says .
This text was adapted from some old draft of 7919 which had should and never got updated (see for instance: URL). Good catch.
NAME Please provide a PR adding yourself to contributors.

Revised text:
Note: For a given Diffie-Hellman group, the padding results in all public keys having the same length.  <ins> Peers MUST validate each other's public key Y by ensuring that 1 < Y < p-1.  This check ensures that the remote peer is properly behaved </ins> and isn't forcing the local system into a small subgroup. 4.2.5.2.
Original text:
records, there MUST NOT be any other records between them. Handshake messages MUST NOT span key changes.  Because the <del> ServerHello, Finished, and KeyUpdate messages signal a key change, upon receiving these messages a receiver MUST verify that the end of these messages aligns with a record boundary; if not, then it MUST terminate the connection with an "unexpected_message" alert. </del>  Implementations MUST NOT send zero-length fragments of Handshake types, even if those fragments contain padding.

Reviewer comments:
An EndOfEarlyData message signals a key change. A ClientHello can be the last message read before a key is changed, and it never makes sense for a ClientHello to have more data after it in the record.

Revised text:
records, there MUST NOT be any other records between them. Handshake messages MUST NOT span key changes.  Because the  <ins> ClientHello, EndOfEarlyData, ServerHello, Finished, and KeyUpdate messages can arrive immediately prior to a key change, upon receiving these messages a receiver MUST verify that the end of these messages aligns with a record boundary; if not, then it MUST terminate the connection with an "unexpected_message" alert. </ins> Implementations MUST NOT send zero-length fragments of Handshake types, even if those fragments contain padding.
Original text:
When (EC)DHE is in use, the server will also provide a "key_share" extension. <del> When authenticating via a certificate (i.e., when a PSK is not in use), the server will send the Certificate (certificate) and CertificateVerify (certificate-verify) messages. </del>  If the server is unable to negotiate a supported set of parameters (i.e., there is no overlap between the client and server parameters),

Reviewer comments:
I think this addresses the issue raised by Russ Housley without changing the semantics of the protocol.
I will give a post-merge "seems fine", since I was so vocal in trying to nail down what Russ wanted.
Mentions of non-existent yet RFCs look weird to me but heh

Revised text:
When (EC)DHE is in use, the server will also provide a "key_share" extension.  <ins> When authenticating via a certificate, the server will send the Certificate (certificate) and CertificateVerify (certificate- verify) messages.  In TLS 1.3 as defined by this document, either a PSK or a certificate is always used, but not both.  Future documents may define how to use them together. </ins> If the server is unable to negotiate a supported set of parameters (i.e., there is no overlap between the client and server parameters),