jiebi/TextFlow huggingface dataset:
Original text:
7.2.2. A conventional Diffie-Hellman computation is performed.  The <del> negotiated key (Z) is used as the shared_secret, and is used in the </del>  key schedule as specified above.  Leading bytes of Z that contain all zero bits are stripped before it is used as the input to HKDF.

Reviewer comments:
Just a few things I noticed that I think make it a little bit easier to follow. Name resumption_secret consistently when used Show full legend for each handshake flow Simplify/clarify secret sources table a bit and make text cases consistent The resumption secret naming was also apparently noticed by NAME in issue . (Edited to note: this PR has been pruned down to a smaller list of changes; see commit message)
Ok, to respond to comments I've pushed a new commit. RE: capitalization: Upper or lower is fine, as long as it's consistent. I've switched it to all upper (title case) instead of all lower. RE: legend repetition: If you're just reading one section, e.g. got to it via TOC, you might not have seen the legend (recently). I've made it less wordy now and also added a line to indicate "+" is for extensions, as I realized that wasn't necessarily clear. (and added a "+" where the notation was inconsistent) We do have an extension that was previously a message, now. The basic point is consistency; make each handshake flow make sense on its own. I think repeating the legend is helpful, but if you really don't want to repeat it that I can cut this down to just the little stuff and table. Showing "N/A" instead of repeating things in the table is the most helpful part here, I think. It states that SS=ES in some circumstances elsewhere, but the table isn't clear that these are the exact same values, especially because the extracted ones are not.
Edited again and repushed for some more naming consistency.
Revised & rebased. Of note, I think these changes to the table make it far easier to see what's going on here.
NAME If you're going to be rewriting this, I'll just set those parts aside. The commit here is now just the little stuff: fix the spacing, add a line stating what SS/ES are in the list of derivations, and fix "shared_secret" (there's no such value named that; just drop the underscore).
NAME commit updated with fixes for your comments above
The key derivation process uses the "master secret" as the basis for application traffic keys and both the resumption and exporter secrets. There are lots of other secrets though. I don't have a better name right now, so close this if none better can be found. Also s/resumption master secret/resumption secret/ throughout, it's a little inconsistent.
Now master of more

Revised text:
7.2.2. A conventional Diffie-Hellman computation is performed.  The  <ins> negotiated key (Z) is used as the shared secret, and is used in the </ins> key schedule as specified above.  Leading bytes of Z that contain all zero bits are stripped before it is used as the input to HKDF.
Original text:
tls-resumption-psk shows a pair of handshakes in which the first establishes a PSK and the second uses it: <del> Note that the client supplies a ClientKeyShare to the server as well, which allows the server to decline resumption and fall back to a full handshake.  However, because the server is authenticating via a PSK, it does not send a Certificate or a CertificateVerify.  PSK-based resumption cannot be used to provide a new ServerConfiguration. </del>  The contents and significance of each message will be presented in detail in the following sections.

Reviewer comments:
The current wording at the end of the section on resumption and PSK should be changed to indicate that if a server declines resumption then a full handshake, including the server Certificate and CertificateVerify messages, should take place. In its current state, the comment on omission of these messages is not disjoint from the statement regarding the server's rejection of resumption.

Revised text:
tls-resumption-psk shows a pair of handshakes in which the first establishes a PSK and the second uses it:  <ins> As the server is authenticating via a PSK, it does not send a Certificate or a CertificateVerify.  PSK-based resumption cannot be used to provide a new ServerConfiguration.  Note that the client supplies a ClientKeyShare to the server as well, which allows the server to decline resumption and fall back to a full handshake. </ins> The contents and significance of each message will be presented in detail in the following sections.
Original text:
send a Certificate message and a CertificateVerify message, even if the "known_configuration" extension was used for this handshake, thus requiring a signature over the configuration before it can be used by <del> the client. </del>  6.3.8.

Reviewer comments:
LGTM
Hubert Karlo writes: And how does the client know that the algorithms came from the server. We should have a "client MUST wait for the full handshake to finish before recording this information" or we will have a very nice cipher downgrade. Just having it signed is likely not a good idea, as they may depend on ciphersuites advertised by client.
Since the ServerConfiguration and the suites are covered by the signature the server provides, isn't it safe to use the configuration add soon as you have verified the server identity?
n.b., I have no problem with mandating that clients wait for finished, because it is immediately after the signature, but I wasn't the properties to be clear.

Revised text:
send a Certificate message and a CertificateVerify message, even if the "known_configuration" extension was used for this handshake, thus requiring a signature over the configuration before it can be used by  <ins> the client.  Clients MUST not rely on the ServerConfiguration message until successfully receiving and processing the server's Certificate, CertificateVerify, and Finished.  If there is a failure in processing those messages, the client MUST discard the ServerConfiguration. </ins> 6.3.8.
Original text:
close a connection does not prohibit a session from being resumed. <del> This message notifies the recipient that the sender will not send </del>  any more messages on this connection.  Any data received after a closure MUST be ignored. <del> This message is sent by the client to indicate that all 0-RTT </del>  application_data messages have been transmitted and that the next message will be handshake message protected with the 1-RTT handshake keys.  This alert MUST be at the warning level.  Servers <del> MUST NOT send this message and clients receiving this message MUST </del>  terminate the connection with an "unexpected_message" alert. <del> This message notifies the recipient that the sender is canceling the handshake for some reason unrelated to a protocol failure.  If a user cancels an operation after the handshake is complete, just </del>  closing the connection by sending a "close_notify" is more appropriate.  This alert SHOULD be followed by a "close_notify". This alert is generally a warning.

Reviewer comments:
NAME did a massive message->alert change a while back and I did yet more when we were rebasing his patch. Looks like there's more up here in Closure Alerts. We're referring to alerts, not the messages that carry them. Switch to "alerts" instead to remain consistent with the rest of the document, notably the following section.

Revised text:
close a connection does not prohibit a session from being resumed.  <ins> This alert notifies the recipient that the sender will not send </ins> any more messages on this connection.  Any data received after a closure MUST be ignored.  <ins> This alert is sent by the client to indicate that all 0-RTT </ins> application_data messages have been transmitted and that the next message will be handshake message protected with the 1-RTT handshake keys.  This alert MUST be at the warning level.  Servers  <ins> MUST NOT send this alert and clients receiving this alert MUST </ins> terminate the connection with an "unexpected_message" alert.  <ins> This alert notifies the recipient that the sender is canceling the handshake for some reason unrelated to a protocol failure.  If a user cancels an operation after the handshake is complete, just </ins> closing the connection by sending a "close_notify" is more appropriate.  This alert SHOULD be followed by a "close_notify". This alert is generally a warning.
Original text:
ServerConfiguration format. The semantics of this message are to establish a shared state between <del> the client and server for use with the "known_configuration" extension with the key specified in key and with the handshake </del>  parameters negotiated by this handshake. When the ServerConfiguration message is sent, the server MUST also send a Certificate message and a CertificateVerify message, even if <del> the "known_configuration" extension was used for this handshake, thus </del>  requiring a signature over the configuration before it can be used by the client.  Clients MUST NOT rely on the ServerConfiguration message until successfully receiving and processing the server's Certificate,

Reviewer comments:
Cleaned up references to knownconfiguration extension (merged into earlydata in draft-08)

Revised text:
ServerConfiguration format. The semantics of this message are to establish a shared state between  <ins> the client and server for use with the "early_data" extension with the key specified in "static_key_share" and with the handshake </ins> parameters negotiated by this handshake. When the ServerConfiguration message is sent, the server MUST also send a Certificate message and a CertificateVerify message, even if  <ins> the "early_data" extension was used for this handshake, thus </ins> requiring a signature over the configuration before it can be used by the client.  Clients MUST NOT rely on the ServerConfiguration message until successfully receiving and processing the server's Certificate,
Original text:
"supported_signature_algorithms" value: %%% Signature Algorithm Extension enum { // RSASSA-PKCS-v1_5 <del> algorithms.  rsa_pkcs1_sha1 (0x0201), rsa_pkcs1_sha256 (0x0401), </del>  rsa_pkcs1_sha384 (0x0501), rsa_pkcs1_sha512 (0x0601), Note: This production is named "SignatureScheme" because there is

Reviewer comments:
Minor editorial tweaks. I just noticed the extra line that gets left in there when shown up top (two lines between first two shown blocks, instead of one). This fixes that. Also drops the periods after the comments, as they're not sentences.

Revised text:
"supported_signature_algorithms" value: %%% Signature Algorithm Extension enum { // RSASSA-PKCS-v1_5  <ins> algorithms rsa_pkcs1_sha1 (0x0201), rsa_pkcs1_sha256 (0x0401), </ins> rsa_pkcs1_sha384 (0x0501), rsa_pkcs1_sha512 (0x0601), Note: This production is named "SignatureScheme" because there is
Original text:
described in Section 2.1 of RFC5116.  The key is either the client_write_key or the server_write_key. The type field is identical to TLSPlaintext.type. The version field is identical to TLSPlaintext.version. The length (in bytes) of the following TLSCiphertext.fragment. The length MUST NOT exceed 2^14 + 2048. The AEAD encrypted form of TLSPlaintext.fragment. Each AEAD cipher suite MUST specify how the nonce supplied to the AEAD operation is constructed, and what is the length of the <del> GenericAEADCipher.nonce_explicit part.  In many cases, it is appropriate to use the partially implicit nonce technique described in Section 3.2.1 of RFC5116; with record_iv_length being the length of the explicit part.  In this case, the implicit part SHOULD be derived from key_block as client_write_iv and server_write_iv (as described in key-calculation), and the explicit part is included in </del>  GenericAEAEDCipher.nonce_explicit. The plaintext is the TLSPlaintext.fragment.

Reviewer comments:
The draft was in a sort of halfway state between whether TLSCiphertext has a fragment that is a selection or just embedding the AEAD elements directly. This should normalize it to the embedded view without the extra GenericAEADCipher struct definition. (i don't think this changes the logic of the draft at all)

Revised text:
described in Section 2.1 of RFC5116.  The key is either the client_write_key or the server_write_key. The type field is identical to TLSPlaintext.type. The version field is identical to TLSPlaintext.version. The length (in bytes) of the following TLSCiphertext.fragment. The length MUST NOT exceed 2^14 + 2048. The AEAD encrypted form of TLSPlaintext.fragment. Each AEAD cipher suite MUST specify how the nonce supplied to the AEAD operation is constructed, and what is the length of the  <ins> TLSCiphertext.nonce_explicit part.  In many cases, it is appropriate to use the partially implicit nonce technique described in Section 3.2.1 of RFC5116; with record_iv_length being the length of the explicit part.  In this case, the implicit part SHOULD be derived from key_block as client_write_iv and server_write_iv (as described in key-calculation), and the explicit part is included in </ins> GenericAEAEDCipher.nonce_explicit. The plaintext is the TLSPlaintext.fragment.
Original text:
The server's key exchange parameters. <del> For non-anonymous key exchanges, a signature over the server's key exchange parameters. </del>  If the client has offered the "signature_algorithms" extension, the signature algorithm and hash algorithm MUST be a pair listed in that

Reviewer comments:
This change clarifies that the signature over ServerDHParams data is a signature over the hash of the client + server hello random random data and the ServerDHParams data. I believe this small regression was introduced in TLS1.2 with the result that the TLS1.2 RFC (and current TLS1.3 draft) does not contain sufficient detail to implement TLS + DHE. All TLS1.2 clients and servers that I have tested do include the hello random data (and omitting it would leave implementations open to replay attacks).
Thanks for the PR. Note that the formal PDU definitions here appear to be correct, so there should be enough information to implement things correctly: I agree it wouldn't hurt to have the explanatory text be clearer. However, in TLS 1.2 we stopped explicitly saying that things were hashed before signing (because we are treating signing as a primitive), so we probably don't want to say "hash". Maybe just say a signature over the random values and the params?
Ah, this explains my confusion. After reading section 7.4.1.4.1, I formed the opposite impression about signing; that hashing and signing are explicitly different primitive operations and may be composed in a variety of ways. But I see how that "digitally-signed" seems to be a reserved term that implies both operations.
I'm not trying to discourage you here. If you were confused, others will probably be as well, so if you have some text that you think would clear this up, it would be welcome.
Thanks! I've updated the PR with an even simpler diff that I think would have made me less confused when I got to it.

Revised text:
The server's key exchange parameters.  <ins> For non-anonymous key exchanges, a signature over the client and server hello random data and the server's key exchange parameters. </ins> If the client has offered the "signature_algorithms" extension, the signature algorithm and hash algorithm MUST be a pair listed in that
Original text:
1.2. <del> draft-14 - Allow cookies to be longer. </del>  draft-13

Reviewer comments:
Lack of a blank line after "draft-14" but before the bullet point causes it to render all on one line: URL This is just a quick patch to make the spacing consistent because apparently Markdown (or, at least whatever is interpreting it there) can be picky. ;) This is just a whitespace fix.

Revised text:
1.2.  <ins> draft-14 Allow cookies to be longer. </ins> draft-13
Original text:
6. One of the content types supported by the TLS record layer is the <del> alert type.  Alert messages convey the severity of the message (warning or fatal) and a description of the alert.  Alert messages with a level of fatal result in the immediate termination of the connection.  Like other messages, alert messages are encrypted as </del>  specified by the current connection state.  %%% Alert Messages 6.1.

Reviewer comments:
NAME NAME PTAL
LGTM
lgtm
Don't forget no_certificate.
Not relevant: nocertificateRESERVED(41), / fatal / , Martin Thomson EMAIL wrote:
Right. I just noticed that we send an empty certificate instead.

Revised text:
6. One of the content types supported by the TLS record layer is the  <ins> alert type.  Like other messages, alert messages are encrypted as </ins> specified by the current connection state. <ins> Alert messages convey the severity of the message (warning or fatal) and a description of the alert.  Warning-level messages are used to indicate orderly closure of the connection (see closure-alerts). Upon receiving a warning-level alert, the TLS implementation SHOULD indicate end-of-data to the application and, if appropriate for the alert type, send a closure alert in response. Fatal-level messages are used to indicate abortive closure of the connection (See error-alerts).  Upon receiving a fatal-level alert, the TLS implementation SHOULD indicate an error to the application and MUST NOT allow any further data to be sent or received on the connection.  Servers and clients MUST forget keys and secrets associated with a failed connection.  Stateful implementations of session tickets (as in many clients) SHOULD discard tickets associated with failed connections. All the alerts listed in error-alerts MUST be sent as fatal and MUST be treated as fatal regardless of the AlertLevel in the message. Unknown alert types MUST be treated as fatal. </ins> %%% Alert Messages 6.1.
Original text:
6.2. <del> Error handling in TLS is very simple.  When an error is detected, the detecting party sends a message to its peer.  Upon transmission or receipt of a fatal alert message, both parties immediately close the connection.  Servers and clients MUST forget keys, and secrets associated with a failed connection.  Stateful implementations of session tickets (as in many clients) SHOULD discard tickets associated with failed connections. Whenever an implementation encounters a condition which is defined as a fatal alert, it MUST send the appropriate alert prior to closing the connection.  For all errors where an alert level is not explicitly specified, the sending party MAY determine at its discretion whether to treat this as a fatal error or not.  If the implementation chooses to send an alert but intends to close the connection immediately afterwards, it MUST send that alert at the fatal alert level. If an alert with a level of warning is sent and received, generally the connection can continue normally.  If the receiving party decides not to proceed with the connection (e.g., after having received a "user_canceled" alert that it is not willing to accept), it SHOULD send a fatal alert to terminate the connection.  Given this, the sending peer cannot, in general, know how the receiving party will behave.  Therefore, warning alerts are not very useful when the sending party wants to continue the connection, and thus are sometimes omitted.  For example, if a party decides to accept an expired certificate (perhaps after confirming this with the user) and wants to continue the connection, it would not generally send a "certificate_expired" alert. </del>  The following error alerts are defined:

Reviewer comments:
NAME NAME PTAL
LGTM
lgtm
Don't forget no_certificate.
Not relevant: nocertificateRESERVED(41), / fatal / , Martin Thomson EMAIL wrote:
Right. I just noticed that we send an empty certificate instead.

Revised text:
6.2.  <ins> Error handling in the TLS Handshake Protocol is very simple.  When an error is detected, the detecting party sends a message to its peer. Upon transmission or receipt of a fatal alert message, both parties immediately close the connection.  Whenever an implementation encounters a condition which is defined as a fatal alert, it MUST send the appropriate alert prior to closing the connection. </ins> The following error alerts are defined:
Original text:
Upon transmission or receipt of a fatal alert message, both parties immediately close the connection.  Whenever an implementation encounters a condition which is defined as a fatal alert, it MUST <del> send the appropriate alert prior to closing the connection. </del>  The following error alerts are defined: <del> An inappropriate message was received.  This alert is always fatal and should never be observed in communication between proper implementations. </del>  This alert is returned if a record is received which cannot be deprotected.  Because AEAD algorithms combine decryption and verification, this alert is used for all deprotection failures. <del> This alert is always fatal and should never be observed in communication between proper implementations (except when messages were corrupted in the network). </del>  A TLSCiphertext record was received that had a length more than 2^14 + 256 bytes, or a record decrypted to a TLSPlaintext record <del> with more than 2^14 bytes.  This alert is always fatal and should never be observed in communication between proper implementations (except when messages were corrupted in the network). </del>  Reception of a "handshake_failure" alert message indicates that the sender was unable to negotiate an acceptable set of security <del> parameters given the options available.  This alert is always fatal. </del>  A certificate was corrupt, contained signatures that did not verify correctly, etc.

Reviewer comments:
As all error alerts are now considered fatal (PR ), we no longer need "This alert is always fatal" explicitly stated everywhere in that section.

Revised text:
Upon transmission or receipt of a fatal alert message, both parties immediately close the connection.  Whenever an implementation encounters a condition which is defined as a fatal alert, it MUST  <ins> send the appropriate alert prior to closing the connection.  All alerts defined in this section below, as well as all unknown alerts are universally considered fatal as of TLS 1.3 (see alert-protocol). </ins> The following error alerts are defined:  <ins> An inappropriate message was received.  This alert should never be observed in communication between proper implementations. </ins> This alert is returned if a record is received which cannot be deprotected.  Because AEAD algorithms combine decryption and verification, this alert is used for all deprotection failures.  <ins> This alert should never be observed in communication between proper implementations, except when messages were corrupted in the network. </ins> A TLSCiphertext record was received that had a length more than 2^14 + 256 bytes, or a record decrypted to a TLSPlaintext record  <ins> with more than 2^14 bytes.  This alert should never be observed in communication between proper implementations, except when messages were corrupted in the network. </ins> Reception of a "handshake_failure" alert message indicates that the sender was unable to negotiate an acceptable set of security  <ins> parameters given the options available. </ins> A certificate was corrupt, contained signatures that did not verify correctly, etc.
Original text:
Sent by servers when a retrieved object does not have the correct hash provided by the client via the "client_certificate_url" <del> extension RFC6066.  This alert is always fatal. </del>  Sent by servers when a PSK cipher suite is selected but no acceptable PSK identity is provided by the client.  Sending this

Reviewer comments:
As all error alerts are now considered fatal (PR ), we no longer need "This alert is always fatal" explicitly stated everywhere in that section.

Revised text:
Sent by servers when a retrieved object does not have the correct hash provided by the client via the "client_certificate_url"  <ins> extension RFC6066. </ins> Sent by servers when a PSK cipher suite is selected but no acceptable PSK identity is provided by the client.  Sending this