jiebi/ids-paragraph-commentary-corpus huggingface dataset:
Draft: draft-ietf-tls-tls13

Commentary: 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 . 
 Please provide a PR to add yourself to acknowledgements .
Paragraph (version A):
As the server is authenticating via a PSK, it does not send a
Certificate or a CertificateVerify message.  When a client offers
resumption via PSK, it SHOULD also supply a "key_share" extension to
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
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
(EC)DHE key establishment, thus providing forward secrecy.
Paragraph (version B):
As the server is authenticating via a PSK, it does not send a
Certificate or a CertificateVerify message.  When a client offers
resumption via PSK, it SHOULD also supply a "key_share" extension to
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
and can (as shown here) respond with a "key_share" extension to do
(EC)DHE key establishment, thus providing forward secrecy.
Paragraph (version A):
As shown in tls-0-rtt, the Zero-RTT data is just added to the 1-RTT
handshake in the first flight.  The rest of the handshake uses the
same messages as with a 1-RTT handshake with PSK resumption.
Paragraph (version B):
As shown in tls-0-rtt, the 0-RTT data is just added to the 1-RTT
handshake in the first flight.  The rest of the handshake uses the
same messages as with a 1-RTT handshake with PSK resumption.
Paragraph (version A):
Future extension or additions to the protocol may define new values.
Implementations need to be able to parse and ignore unknown values
unless the definition of the field states otherwise.
Paragraph (version B):
Future extensions or additions to the protocol may define new values.
Implementations need to be able to parse and ignore unknown values
unless the definition of the field states otherwise.
Paragraph (version A):
A list of extensions.  The ServerHello MUST only include
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
contain one of these two extensions.
Paragraph (version B):
A list of extensions.  The ServerHello MUST only include
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
contain one of these two extensions, or both when using a PSK with
(EC)DHE key establishment.
Draft: draft-ietf-tls-tls13

Commentary: 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 .
Paragraph (version A):
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.
Paragraph (version B):
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.
Draft: draft-ietf-tls-tls13

Commentary: This is a redo of PR now that PR has removed the appending rule and resolved issue .
Paragraph (version A):
A list of offered KeyShareEntry values in descending order of
client preference.  This vector MAY be empty if the client is
requesting a HelloRetryRequest.  The ordering of values here
SHOULD match that of the ordering of offered support in the
"supported_groups" extension.
Paragraph (version B):
A list of offered KeyShareEntry values in descending order of
client preference.  This vector MAY be empty if the client is
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.
Draft: draft-ietf-tls-tls13

Commentary: 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
Paragraph (version A):
The server processes the ClientHello and determines the appropriate
cryptographic parameters for the connection.  It then responds with
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.
Paragraph (version B):
The server processes the ClientHello and determines the appropriate
cryptographic parameters for the connection.  It then responds with
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.
Paragraph (version B):
Sent by a server in response to an invalid connection retry
attempt from a client RFC7507.
Draft: draft-ietf-tls-tls13

Commentary: 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 " " cruft that is n't part of a reword . 
 In previous versions of TLS , passing no context was different to passing an empty context . TLS 1.3 does n't distinguish between these . I do n'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 .
Paragraph (version A):
Where Secret is either the early_exporter_secret or the
exporter_secret.  Implementations MUST use the exporter_secret unless
explicitly specified by the application.  When adding TLS 1.3 to TLS
interface.
Paragraph (version A):
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.
Paragraph (version B):
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
remains the same.
Paragraph (version B):
Where Secret is either the early_exporter_secret or the
exporter_secret.  Implementations MUST use the exporter_secret unless
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.
Paragraph (version B):
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.
Draft: draft-ietf-tls-tls13

Commentary: This is how NSS behaves as well . This seems like a reasonable argument . 
 the changes previously discussed . 
 I did not verify that the moved text is only move and no edits , but the other chunks seem okay . 
 are you OK with this SHOULD ? 
 Sounds reasonable . Mostly I just do n't want to encourage servers to enforce anything about this .
Paragraph (version A):
This is a list of the symmetric cipher options supported by the
client, specifically the record protection algorithm (including
secret key length) and a hash to be used with HKDF, in descending
order of client preference.  If the list contains cipher suites
the server does not recognize, support, or wish to use, the server
MUST ignore those cipher suites, and process the remaining ones as
usual.  Values are defined in cipher-suites.
Paragraph (version B):
This is a list of the symmetric cipher options supported by the
client, specifically the record protection algorithm (including
secret key length) and a hash to be used with HKDF, in descending
order of client preference.  If the list contains cipher suites
the server does not recognize, support, or wish to use, the server
MUST ignore those cipher suites, and process the remaining ones as
usual.  Values are defined in cipher-suites.  If the client is
attempting a PSK key establishment, it SHOULD advertise at least
one cipher suite containing a Hash associated with the PSK.
Paragraph (version A):
Clients MUST verify that the server's selected_identity is within the
range supplied by the client, that the server selected the cipher
suite associated with the PSK, and that the "key_share", and
"signature_algorithms" extensions are consistent with the indicated
ke_modes and auth_modes values.  If these values are not consistent,
the client MUST abort the handshake with an "illegal_parameter"
alert.
Paragraph (version B):
Clients MUST verify that the server's selected_identity is within the
range supplied by the client, that the server selected a cipher suite
containing a Hash associated with the PSK, and that the "key_share",
and "signature_algorithms" extensions are consistent with the
indicated ke_modes and auth_modes values.  If these values are not
consistent, the client MUST abort the handshake with an
"illegal_parameter" alert.
Paragraph (version A):
The cleartext of TLSPlaintext.fragment.
Paragraph (version B):
The byte encoding of a handshake or an alert message, or the the
raw bytes of the application's data to send.
Draft: draft-ietf-tls-tls13

Commentary: extension , as suggested by      . 
 LGTM
Paragraph (version B):
Consolidate "ticket_early_data_info" and "early_data" into a
single extension (*).
Paragraph (version B):
The "extension_data" field of this extension contains an
"EarlyDataIndication" value.
Paragraph (version B):
See ticket-establishment for the use of the max_early_data_size
field.
Draft: draft-ietf-tls-tls13

Commentary: This is my fault . Sorry about that .
Paragraph (version A):
A label for a key.  For instance, a ticket defined in ticket-
establishment, or a label for a pre-shraed key established
externally.
Paragraph (version B):
A label for a key.  For instance, a ticket defined in ticket-
establishment, or a label for a pre-shared key established
externally.
Draft: draft-ietf-tls-tls13

Commentary: Ticket is a term that refers to a PSK identity established using an handshake . For out - of - band PSK , we do not use the term .
Paragraph (version A):
For each ticket, the time since the client learned about the
server configuration that it is using, in milliseconds.  This
value is added modulo 2^32 to with the "ticket_age_add" value that
was included with the ticket, see NewSessionTicket.  This addition
prevents passive observers from correlating sessions unless
tickets are reused.  Note: because ticket lifetimes are restricted
to a week, 32 bits is enough to represent any plausible age, even
in milliseconds.  External tickets SHOULD use an
obfuscated_ticket_age of 0; servers MUST ignore this value for
external tickets.
Paragraph (version B):
For each ticket, the time since the client learned about the
server configuration that it is using, in milliseconds.  This
value is added modulo 2^32 to with the "ticket_age_add" value that
was included with the ticket, see NewSessionTicket.  This addition
prevents passive observers from correlating sessions unless
tickets are reused.  Note: because ticket lifetimes are restricted
to a week, 32 bits is enough to represent any plausible age, even
in milliseconds.  For identities established externally an
obfuscated_ticket_age of 0 SHOULD be used, and servers MUST ignore
the value.
Draft: draft-ietf-tls-tls13

Commentary: The alert is described as being part of the first flight , but it is really sent when the server Finished is received , per the processing order section . Notably , servers MUST NOT wait for endofearlydata before sending ServerHello through Finished . Group it with the client Finished flight , and fix the text about it terminating the first flight . ( The division between the first and second client flight is n't especially well - defined because early data may flow in parallel with the ServerHello flight . But if there is to be a division , endofearlydata certainly falls into the second one . ) 
 Yes , this should help avoid one of the most common mistakes in 0 - RTT implementations . 
 LGTM .
Paragraph (version A):
0-RTT messages sent in the first flight have the same content types
as their corresponding messages sent in other flights (handshake,
application_data, and alert respectively) but are protected under
different keys.  After all the 0-RTT application data messages (if
any) have been sent, an "end_of_early_data" alert of type "warning"
is sent to indicate the end of the flight.  0-RTT MUST always be
followed by an "end_of_early_data" alert, which will be encrypted
with the 0-RTT traffic keys.
Paragraph (version B):
0-RTT messages sent in the first flight have the same content types
as their corresponding messages sent in other flights (handshake,
application_data, and alert respectively) but are protected under
different keys.  After receiving the server's Finished message, if
the server has accepted early data, an "end_of_early_data" alert of
type "warning" MUST be sent to indicate the key change.  This message
will be encrypted with the 0-RTT traffic keys.
Paragraph (version A):
This alert is sent by the client to indicate that all 0-RTT
application_data messages have been transmitted (or none will be
sent at all) and that this is the end of the flight.  This alert
MUST be at the warning level.  Servers MUST NOT send this alert
and clients receiving it MUST terminate the connection with an
"unexpected_message" alert.
Paragraph (version B):
This alert is sent by the client to indicate that all 0-RTT
application_data messages have been transmitted (or none will be
sent at all) and that the following records are protected under
handshake traffic keys.  This alert MUST be at the warning level.
Servers MUST NOT send this alert and clients receiving it MUST
terminate the connection with an "unexpected_message" alert.
Draft: draft-ietf-tls-tls13

Commentary: I think this explanation is missing .
Paragraph (version A):
A list of the identities (labels for keys) that the client is
willing to negotiate with the server.  If sent alongside the
"early_data" extension (see early-data-indication), the first
identity is the one used for 0-RTT data.
Paragraph (version B):
A label for a key.  For instance, a ticket defined in ticket-
establishment, or a label for a pre-shraed key established
externally.
Paragraph (version B):
A list of the identities that the client is willing to negotiate
with the server.  If sent alongside the "early_data" extension
(see early-data-indication), the first identity is the one used
for 0-RTT data.
Draft: draft-ietf-tls-tls13

Commentary: This would help to understand what extensions should be encrypted .
Paragraph (version A):
A list of extensions.
Paragraph (version B):
A list of extensions.  For more information, see the table in
iana-considerations.
Draft: draft-ietf-tls-tls13

Commentary: " Clients " is plural , so " It " does n't make sense here .
Paragraph (version A):
Indicates the lifetime in seconds as a 32-bit unsigned integer in
network byte order from the time of ticket issuance.  Servers MUST
NOT use any value more than 604800 seconds (7 days).  The value of
zero indicates that the ticket should be discarded immediately.
Clients MUST NOT cache session tickets for longer than 7 days,
regardless of the ticket_lifetime.  It MAY delete the ticket
earlier based on local policy.  A server MAY treat a ticket as
valid for a shorter period of time than what is stated in the
ticket_lifetime.
Paragraph (version B):
Indicates the lifetime in seconds as a 32-bit unsigned integer in
network byte order from the time of ticket issuance.  Servers MUST
NOT use any value more than 604800 seconds (7 days).  The value of
zero indicates that the ticket should be discarded immediately.
Clients MUST NOT cache session tickets for longer than 7 days,
regardless of the ticket_lifetime and MAY delete the ticket
earlier based on local policy.  A server MAY treat a ticket as
valid for a shorter period of time than what is stated in the
ticket_lifetime.
Draft: draft-ietf-tls-tls13

Commentary: Fix incorrect suggestion that of NST affects extension . 
 merged . Please provide a PR adding yourself to the acknowledgements list in alphabetical order .
Paragraph (version A):
A randomly generated 32-bit value that is used to obscure the age
of the ticket that the client includes in the "early_data"
extension.  The client-side ticket age is added to this value
modulo 2^32 to obtain the value that is transmitted by the client.
Paragraph (version B):
A randomly generated 32-bit value that is used to obscure the age
of the ticket that the client includes in the "pre_shared_key"
extension.  The client-side ticket age is added to this value
modulo 2^32 to obtain the value that is transmitted by the client.
Draft: draft-ietf-tls-tls13

Commentary: This commit fixes several typos .
Paragraph (version A):
If the server selects a PSK, then it MUST also select a key
establishment mode from the set indicated by client's
"psk_key_exchange_modes extension (PSK alone or with (EC)DHE).  Note
that if the PSK can be used without (EC)DHE then non-overlap in the
"supported_groups" parameters need not be fatal.
Paragraph (version B):
If the server selects a PSK, then it MUST also select a key
establishment mode from the set indicated by client's
"psk_key_exchange_modes" extension (PSK alone or with (EC)DHE).  Note
that if the PSK can be used without (EC)DHE then non-overlap in the
"supported_groups" parameters need not be fatal.
Paragraph (version A):
A clients MUST provide a "psk_key_exchange_modes" extension if it
offers a "pre_shared_key" extension.  If clients offer
"pre_shared_key" without a "psk_key_exchange_modes" extension,
servers MUST abort the handshake.  Servers MUST NOT select a key
exchange mode that is not listed by the client.  This extension also
restricts the modes for use with PSK resumption; servers SHOULD NOT
send NewSessionTicket with tickets that are not compatible with the
advertised modes; however if it does so, the impact will just be that
the client's attempts at resumption fail.
Paragraph (version B):
A client MUST provide a "psk_key_exchange_modes" extension if it
offers a "pre_shared_key" extension.  If clients offer
"pre_shared_key" without a "psk_key_exchange_modes" extension,
servers MUST abort the handshake.  Servers MUST NOT select a key
exchange mode that is not listed by the client.  This extension also
restricts the modes for use with PSK resumption; servers SHOULD NOT
send NewSessionTicket with tickets that are not compatible with the
advertised modes; however if it does so, the impact will just be that
the client's attempts at resumption fail.
Paragraph (version A):
A set of extension values for the CertificateEntry.  The
"Extension" format is defined in extensions.  Valid extensions
include OCSP Status extensions (RFC6066 and RFC6961) and
SignedCertificateTimestamps (RFC6962).  Any extension presented in
a Certificate message must only be presented if the corresponding
ClientHello extension was presented in the initial handshake.  If
an extension applies the the entire chain, it SHOULD be included
in the first CertificateEntry.
Paragraph (version B):
A set of extension values for the CertificateEntry.  The
"Extension" format is defined in extensions.  Valid extensions
include OCSP Status extensions (RFC6066 and RFC6961) and
SignedCertificateTimestamps (RFC6962).  Any extension presented in
a Certificate message must only be presented if the corresponding
ClientHello extension was presented in the initial handshake.  If
an extension applies to the entire chain, it SHOULD be included in
the first CertificateEntry.
Draft: draft-ietf-tls-tls13

Commentary: Yes . There is a fair amount of other cleanup needed in this area ; I have lots of red pen markings on a printout but have n't translated them into a patch yet . 
 Yes . There is a fair amount of other cleanup needed in this area ; I have lots of red pen markings on a printout but have n't translated them into a patch yet . 
  ,  was angry - unicorning on me and did not indicate that the comment went through . I guess github does n't like me this week ...
Paragraph (version A):
The length (in bytes) of the following TLSCiphertext.fragment,
which is the sum of the lengths of the content and the padding,
plus one for the inner content type.  The length MUST NOT exceed
2^14 + 256.  An endpoint that receives a record that exceeds this
length MUST terminate the connection with a "record_overflow"
alert.
Paragraph (version B):
The length (in bytes) of the following
TLSCiphertext.encrypted_record, which is the sum of the lengths of
the content and the padding, plus one for the inner content type.
The length MUST NOT exceed 2^14 + 256.  An endpoint that receives
a record that exceeds this length MUST terminate the connection
with a "record_overflow" alert.
Draft: draft-ietf-tls-tls13

Commentary: … Request . To match 4.2.6.1 .
Paragraph (version B):
Updating the PSK binder values if the "pre_shared_key" extension
was present.