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

Commentary: For consistency sake .
Paragraph (version A):
In the following example, mandatory is a vector that must contain
between 300 and 400 bytes of type opaque.  It can never be empty.
The actual length field consumes two bytes, a uint16, which is
sufficient to represent the value 400 (see numbers).  On the other
hand, longer can represent up to 800 bytes of data, or 400 uint16
elements, and it may be empty.  Its encoding will include a two-byte
actual length field prepended to the vector.  The length of an
encoded vector must be an even multiple of the length of a single
element (for example, a 17-byte vector of uint16 would be illegal).
Paragraph (version B):
In the following example, mandatory is a vector that must contain
between 300 and 400 bytes of type opaque.  It can never be empty.
The actual length field consumes two bytes, a uint16, which is
sufficient to represent the value 400 (see numbers).  On the other
hand, longer can represent up to 800 bytes of data, or 400 uint16
elements, and it may be empty.  Its encoding will include a two-byte
actual length field prepended to the vector.  The length of an
encoded vector must be an even multiple of the length of a single
element (e.g., a 17-byte vector of uint16 would be illegal).
Draft: draft-ietf-tls-tls13

Commentary: A potential minor tweak to the 1st para in s2 .
Paragraph (version A):
The cryptographic parameters of the session state are produced by the
TLS handshake protocol.  When a TLS client and server first start
communicating, they agree on a protocol version, select cryptographic
algorithms, optionally authenticate each other, and establish shared
secret keying material.  Once the handshake is complete, the peers
use the established keys to protect application layer traffic.
Paragraph (version B):
The cryptographic parameters of the session state are produced by the
TLS handshake protocol, which a TLS client and server use when first
communicating to agree on a protocol version, select cryptographic
algorithms, optionally authenticate each other, and establish shared
secret keying material.  Once the handshake is complete, the peers
use the established keys to protect application layer traffic.
Draft: draft-ietf-tls-tls13

Commentary: At least to me , the KE phase description currently reads like the DH share and PSK are always sent . It 's DH , PSK , or both .
Paragraph (version A):
In the Key Exchange phase, the client sends the ClientHello (client-
hello) message, which contains a random nonce (ClientHello.random),
its offered protocol version, a list of symmetric cipher/HKDF hash
pairs, some set of Diffie-Hellman key shares (in the "key_share"
extension key-share), one or more pre-shared key labels (in the
"pre_shared_key" extension pre-shared-key-extension), or both, and
potentially some other extensions.
Paragraph (version B):
In the Key Exchange phase, the client sends the ClientHello (client-
hello) message, which contains a random nonce (ClientHello.random);
its offered protocol version; a list of symmetric cipher/HKDF hash
pairs; some set of Diffie-Hellman key shares (in the "key_share"
extension key-share), one or more pre-shared key labels (in the
"pre_shared_key" extension pre-shared-key-extension), or both; and
potentially some other extensions.
Draft: draft-ietf-tls-tls13

Commentary: Some suggested edits for s2 .
Paragraph (version A):
Diffie-Hellman (of both the finite field and elliptic curve
varieties).
Paragraph (version A):
The handshake can be thought of as having three phases, indicated in
the diagram above.
Paragraph (version B):
Diffie-Hellman (both the finite field and elliptic curve
varieties),
Paragraph (version B):
A combination of a symmetric key and Diffie-Hellman.
Paragraph (version B):
Server Parameters: Establish other handshake parameters (whether
the client is authenticated, application layer protocol support,
etc.).
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 will contain 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 will contain
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 A):
if certificate-based client authentication is desired, the desired
parameters for that certificate.  This message will be omitted if
client authentication is not desired.
Paragraph (version B):
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.
Draft: draft-ietf-tls-tls13

Commentary: Some suggested nits for s1 : adding a semi - colon and swapping two whichs for that s.
Paragraph (version A):
The primary goal of TLS is to provide a secure channel between two
communicating peers.  Specifically, the channel should provide the
following properties.
Paragraph (version A):
A handshake protocol (handshake-protocol) which authenticates the
communicating parties, negotiates cryptographic modes and
parameters, and establishes shared keying material.  The handshake
protocol is designed to resist tampering; an active attacker
should not be able to force the peers to negotiate different
parameters than they would if the connection were not under
attack.
Paragraph (version B):
A handshake protocol (handshake-protocol) that authenticates the
communicating parties, negotiates cryptographic modes and
parameters, and establishes shared keying material.  The handshake
protocol is designed to resist tampering; an active attacker
should not be able to force the peers to negotiate different
parameters than they would if the connection were not under
attack.
Paragraph (version A):
A record protocol (record-protocol) which uses the parameters
established by the handshake protocol to protect traffic between
the communicating peers.  The record protocol divides traffic up
into a series of records, each of which is independently protected
using the traffic keys.
Paragraph (version B):
A record protocol (record-protocol) that uses the parameters
established by the handshake protocol to protect traffic between
the communicating peers.  The record protocol divides traffic up
into a series of records, each of which is independently protected
using the traffic keys.
Paragraph (version A):
TLS is application protocol independent; higher-level protocols can
layer on top of TLS transparently.  The TLS standard, however, does
not specify how protocols add security with TLS; the decisions on how
to initiate TLS handshaking and how to interpret the authentication
certificates exchanged are left to the judgment of the designers and
implementors of protocols that run on top of TLS.
Paragraph (version B):
TLS is application protocol independent; higher-level protocols can
layer on top of TLS transparently.  The TLS standard, however, does
not specify how protocols add security with TLS; how to initiate TLS
handshaking and how to interpret the authentication certificates
exchanged are left to the judgment of the designers and implementors
of protocols that run on top of TLS.
Draft: draft-ietf-tls-tls13

Commentary: ClientHello mentions that earlydata should be removed , but earlydata does n't mention it . Editorial .
Paragraph (version A):
Removing the EarlyDataIndication early-data-indication extension
if one was present.  Early data is not permitted after
HelloRetryRequest.
Paragraph (version B):
Removing the "early_data" extension (early-data-indication) if one
was present.  Early data is not permitted after HelloRetryRequest.
Paragraph (version B):
Request that the client send another ClientHello by responding
with a HelloRetryRequest.  A client MUST NOT include the
"early_data" extension in its followup ClientHello.
Draft: draft-ietf-tls-tls13

Commentary: draft - ietf - tls - negotiated - ff - dhe is now RFC 7919 . draft - mattsson - tls - ecdhe - psk - aead is now draft - ietf - tls - ecdhe - psk - aead . 
 Do we even need a reference to draft - ietf - tls - ecdhe - psk - aead with the new negotiation syntax ? 
 I removed it from the reference section . It was used in previous versions . But it is no longer referenced to by any text in the spec since version 15 .
Paragraph (version A):
Note: In versions of TLS prior to TLS 1.3, this extension was named
"elliptic_curves" and only contained elliptic curve groups.  See
RFC4492 and I-D.ietf-tls-negotiated-ff-dhe.  This extension was also
used to negotiate ECDSA curves.  Signature algorithms are now
negotiated independently (see signature-algorithms).
Paragraph (version B):
Note: In versions of TLS prior to TLS 1.3, this extension was named
"elliptic_curves" and only contained elliptic curve groups.  See
RFC4492 and RFC7919.  This extension was also used to negotiate ECDSA
curves.  Signature algorithms are now negotiated independently (see
signature-algorithms).
Paragraph (version A):
Indicates support of the corresponding finite field group, defined
in I-D.ietf-tls-negotiated-ff-dhe.  Values 0x01FC through 0x01FF
are reserved for private use.
Paragraph (version B):
Indicates support of the corresponding finite field group, defined
in RFC7919.  Values 0x01FC through 0x01FF are reserved for private
use.
Draft: draft-ietf-tls-tls13

Commentary: PTAL quickly . 
 +1
Paragraph (version B):
Handshake messages MUST NOT span key changes.  Because the
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
send a fatal "unexpected_message" alert.
Draft: draft-ietf-tls-tls13

Commentary: Noticed these while reviewing the negotiation PR : handshakefailure means " the sender was unable to negotiate an acceptable set of security parameters given the options available " , but these are all protocol errors that should only occur with a buggy server . Switch them to more appropriate ones : If the HelloRetryRequest makes no sense , it is an illegalparameter . If we get a second HelloRetryRequest , it 's an unexpectedmessage ( the client is in a state where it expects a ServerHello and will likely just fall through to the generic message - mismatch codepath ) . If  and ServerHello are inconsistent , it is an illegalparameter . If an anonymous server sends a CertificateRequest , it 's an unexpected_message ( this too will likely use the generic message - mismatch codepath ) .
Paragraph (version A):
Upon receipt of a HelloRetryRequest, the client MUST first verify
that the selected_group field corresponds to a group which was
provided in the "supported_groups" extension in the original
ClientHello.  It MUST then verify that the selected_group field does
not correspond to a group which was provided in the "key_share"
extension in the original ClientHello.  If either of these checks
fails, then the client MUST abort the handshake with a fatal
"handshake_failure" alert.  Clients SHOULD also abort with
"handshake_failure" in response to any second HelloRetryRequest which
was sent in the same connection (i.e., where the ClientHello was
itself in response to a HelloRetryRequest).
Paragraph (version B):
Upon receipt of a HelloRetryRequest, the client MUST first verify
that the selected_group field corresponds to a group which was
provided in the "supported_groups" extension in the original
ClientHello.  It MUST then verify that the selected_group field does
not correspond to a group which was provided in the "key_share"
extension in the original ClientHello.  If either of these checks
fails, then the client MUST abort the handshake with a fatal
"illegal_parameter" alert.  Clients SHOULD also abort with
"unexpected_message" in response to any second HelloRetryRequest
which was sent in the same connection (i.e., where the ClientHello
was itself in response to a HelloRetryRequest).
Paragraph (version A):
Upon re-sending the ClientHello and receiving the server's
ServerHello/KeyShare, the client MUST verify that the selected
CipherSuite and NamedGroup match that supplied in the
HelloRetryRequest.  If either of these values differ, the client MUST
abort the connection with a fatal "handshake_failure" alert.
Paragraph (version B):
Upon re-sending the ClientHello and receiving the server's
ServerHello/KeyShare, the client MUST verify that the selected
CipherSuite and NamedGroup match that supplied in the
HelloRetryRequest.  If either of these values differ, the client MUST
abort the connection with a fatal "illegal_parameter" alert.
Paragraph (version A):
Note: It is a fatal "handshake_failure" alert for an anonymous server
to request client authentication.
Paragraph (version B):
Note: It is a fatal "unexpected_message" alert for an anonymous
server to request client authentication.
Draft: draft-ietf-tls-tls13

Commentary: No sender could possibly need to send half of a message interleaved with application data in TLS , so forbid this . This cuts down on the state - space a receiver needs to worry about . This also means one can not force the peer to buffer all but one byte of a giant post - handshake message , and then never complete it for the lifetime of the connection . ( Although it does not remove all steady state buffering DoS - type concerns . )
Paragraph (version B):
Handshake messages sent after the handshake MUST NOT be interleaved
with other record types.  That is, if a message is split over two or
more handshake records, there MUST NOT be any other records between
them.
Draft: draft-ietf-tls-tls13

Commentary: From the past three times we 've bumped the version , reality has unequivocally told us that the TLS version negotiation , as described in previous specifications , has been a collossal failure . The working group decided not to replace the mechanism with a more sustainable one , so do the next best thing in trying to save TLS from itself . If the fields are renamed to what they actually are ( ' serverversion ' is the true version and ' clientversion ' is a maximum ) , then perhaps we 'll have some hope of future implementors getting it right , if we ever clear through the prior iterations of the bug . While I 'm here , remove the mention of ' The protocol version the current record is compatible with ' for recordversion . recordversion is purely vestigial . 
 +1 
 This sounds like a good idea , however for the server version I 'd go with " negotiatedversion " to be more precise . For " recordversion " , we could also extend the " legacy " prefix convention we 've started using and change it to " legacyrecordversion " to remind that it 's a deprecated field . 
 Hrm . We do n't name other fields like ServerHello.negotiatedciphersuite and such . Though if we wanted to be consistent with those fields , it should be ClientHello.maxversion rather than ClientHello.maxsupportedversion . Dunno , maybe that would be better ... maxsupportedversion is a bit wordy . ( Though I do think breaking pattern on the ClientHello version is justified because that field is already inconsistent with everything else in TLS . The version is the only place where the client does n't offer a list , so everything else already self - describes as a " pick one of these " type of field . ) Done .
Paragraph (version A):
The record_version field is identical to
TLSPlaintext.record_version and is always { 3, 1 }.  Note that the
handshake protocol including the ClientHello and ServerHello
messages authenticates the protocol version, so this value is
redundant.
Paragraph (version B):
The legacy_record_version field is identical to
TLSPlaintext.legacy_record_version and is always { 3, 1 }.  Note
that the handshake protocol including the ClientHello and
ServerHello messages authenticates the protocol version, so this
value is redundant.
Draft: draft-ietf-tls-tls13

Commentary: It 's only useful during the handshake , so avoid forcing the client save that field for the in - handshake version . 
 I went back and forth on this , but on balance I think you 're right .
Paragraph (version A):
An opaque string which identifies the certificate request and
which will be echoed in the client's Certificate message.  The
certificate_request_context MUST be unique within the scope of
this connection (thus preventing replay of client
CertificateVerify messages).
Paragraph (version B):
An opaque string which identifies the certificate request and
which will be echoed in the client's Certificate message.  The
certificate_request_context MUST be unique within the scope of
this connection (thus preventing replay of client
CertificateVerify messages).  Within the handshake, this field
MUST be empty.
Draft: draft-ietf-tls-tls13

Commentary: ( My impression from the list is that we 're not doing post - handshake key separation . If I 'm wrong and we are , this will need to be slightly tweaked . Anyway , the current state of the world is we do n't do it , so I 've worded it accordingly . ) As the Finished message is an implicit ChangeCipherSpec , it 's worth clarifying that this is the point at which the cipher state changes . Should an implementation not send half - RTT data , it may defer switching traffic keys until both Finished messages have been exchanged . This will not work well , as alerts sent in response to a bad client certificate will be unreadable . The outgoing traffic keys must be switched early .
Paragraph (version B):
Any records following a 1-RTT Finished message MUST be encrypted
under the application traffic key.  In particular, this includes any
alerts sent by the server in response to client Certificate and
CertificateVerify messages.
Draft: draft-ietf-tls-tls13

Commentary: Trivial cleanup of a cleanup of a cleanup . Yay typos . :p
Paragraph (version A):
Versions of TLS before 1.3 supported compression with the list of
supported compression methods being send in this field.  For every
TLS 1.3 ClientHello, this vector MUST contain exactly one byte set
to 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
"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.
Paragraph (version B):
Versions of TLS before 1.3 supported compression with the list of
supported compression methods being sent in this field.  For every
TLS 1.3 ClientHello, this vector MUST contain exactly one byte set
to 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
"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.
Draft: draft-ietf-tls-tls13

Commentary: This is inconsistent with session tickets and people do n't do it
Paragraph (version A):
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.  Servers and clients MUST forget
any session-identifiers, keys, and secrets associated with a failed
connection.  Thus, any connection terminated with a fatal alert MUST
NOT be resumed.
Paragraph (version B):
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.  Servers and clients MUST forget
keys, and secrets associated with a failed connection.
Draft: draft-ietf-tls-tls13

Commentary: This recent commit left a few jumbled sentences .
Paragraph (version A):
Clients offer an arbitrary number of KeyShareEntry values, each
representing a single set of key exchange parameters.  For instance,
a client might offer shares for several elliptic curves or multiple
FFDHE groups.  The key_exchange values for each KeyShareEntry MUST by
generated independently.  Clients MUST NOT offer multiple
KeyShareEntry values for the same group and servers receiving
multiple KeyShareEntry values for the same group.  Clients and
servers MUST NOT offer any KeyShareEntry values for groups not listed
in the client's "supported_groups" extension Servers MUST NOT offer a
KeyShareEntry value for a group not offered by the client in its
corresponding KeyShare.  Implementations MAY check for violations of
these rules and and MAY abort the connection with a fatal
"illegal_parameter" alert if one is violated.
Paragraph (version B):
Clients offer an arbitrary number of KeyShareEntry values, each
representing a single set of key exchange parameters.  For instance,
a client might offer shares for several elliptic curves or multiple
FFDHE groups.  The key_exchange values for each KeyShareEntry MUST by
generated independently.  Clients MUST NOT offer multiple
KeyShareEntry values for the same group.  Clients and servers MUST
NOT offer any KeyShareEntry values for groups not listed in the
client's "supported_groups" extension.  Servers MUST NOT offer a
KeyShareEntry value for a group not offered by the client in its
corresponding KeyShare.  Implementations MAY check for violations of
these rules and and MAY abort the connection with a fatal
"illegal_parameter" alert if one is violated.
Draft: draft-ietf-tls-tls13

Commentary: This sentence in general seems redundant , but if it 's going to be included it should be correct .
Paragraph (version A):
The plaintext is the concatenation of TLSPlaintext.fragment and
TLSPlaintext.type.
Paragraph (version B):
The plaintext is the concatenation of TLSPlaintext.fragment,
TLSPlaintext.type, and any padding bytes (zeros).
Draft: draft-ietf-tls-tls13

Commentary: Lack of a blank line after " draft-14 " but before the bullet point causes it to render all on one line : This is just a quick patch to make the spacing consistent because apparently  ( or , at least whatever is interpreting it there ) can be picky . ;) This is just a whitespace fix .
Paragraph (version A):
draft-14 - Allow cookies to be longer.
Paragraph (version B):
Allow cookies to be longer.
Draft: draft-ietf-tls-tls13

Commentary: Nitpick I noticed while reading through the spec again .
Paragraph (version A):
indicating which if the client's offered PSKs was selected.
Paragraph (version B):
indicating which of the client's offered PSKs was selected.