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

Commentary: Use refs for HKDF & HMAC in the document and drop the unused AES CBC RFC ref in favor of the AES GCM RFCs ( refs already in use ) . Caught via Travis warnings that they were all unused . It also notes that RFC 2246 ( TLS 1.0 ) is n't referenced directly and RFC 5705 is n't used , either . You probably wanted to reference RFC 5705 somewhere in your recent work , but it 's not currently used .  also complains about I - D.ietf - tls - session - hash , though that is referenced in the credits . It probably should be referenced somewhere too . 
 I 've also an update to the " obsoletes " line . We do n't need to list TLS 1.1 ( TLS 1.2 & 1.3 do n't list 1.0 ) , its extensions RFC , or AES CBC , as they 've already been obsoleted by TLS 1.2 ( also obsoleted old AES RFC ) and the newer extensions RFC .
Paragraph (version A):
HMAC(finished_secret, finished_label + '\0' + handshake_hash)
where HMAC uses the Hash algorithm for the handshake.  See the-
handshake-hash for the definition of handshake_hash.
Paragraph (version B):
HMAC(finished_secret, finished_label + '\0' + handshake_hash)
where HMAC RFC2104 uses the Hash algorithm for the handshake.  See
the-handshake-hash for the definition of handshake_hash.
Paragraph (version A):
The derivation process is as follows, where L denotes the length of
the underlying hash function for HKDF.
Paragraph (version B):
The derivation process is as follows, where L denotes the length of
the underlying hash function for HKDF RFC5869.
Draft: draft-ietf-tls-tls13

Commentary: This revises " The Cipher Suites " section to simplify redundant language , actually explain the de facto naming convention , and add all currently available AEAD cipher suites . It also drops the appendix table that has already had its section whittled down quite a bit , in favor of the explanation and new table in the main section . Note that this is all of the AEAD ciphers available in the current IANA registry [ 0 ] , plus ChaChaPoly ( which has to be a normative reference [ 1 ] , so must reach RFC status before this does ) . Issue just said " standards track AEAD ciphers " , but as the registry lists them all , adding them was n't difficult . If we 'd rather not cite them here then they can of course be cut out ( ARIA , Camellia , & ECDHE AES - CCM are informational ; the rest are standards track , including DHE AES - CCM ) . Alternatively , the table could be annotated to note which are on what track or split in two . This has no changes to any requirements . [ 0 ] [ 1 ] 
 I addressed your comments in this new commit . I switched to a table to make things easier to read and explicitly clarified the constant string bits so as to be more clear . I also dropped the confusing sentence fragment . 
 looks good . 
 AES - OCB will also be addable to this list , but its codepoints are all completely TBD still . 
 Rebased , squashed , & updated for recent changes to draft . 
 Ok , all comments addressed with that last commit . I 've split the table into standards and non - standards and simplified the note to just mention ECDHE AES GCM being widely deployed . 
 Rebased . 
 Ok , reworded that bit too . 
 I only the GCM AEAD ciphers . We should add all the standards track AEAD ciphers . 
 This was dealt with in PR and can be closed .
Paragraph (version B):
Revise list of currently available AEAD cipher suites.
Paragraph (version A):
This is a list of the cryptographic options supported by the
client, with the client's first preference first.  Values are
defined in the-cipher-suite.
Paragraph (version B):
This is a list of the cryptographic options supported by the
client, with the client's first preference first.  Values are
defined in cipher-suites.
Paragraph (version A):
Security issues are discussed throughout this memo, especially in
Appendices C, D, and E.
Paragraph (version B):
Security issues are discussed throughout this memo, especially in
Appendices B, C, and D.
Draft: draft-ietf-tls-tls13

Commentary: Small editorial change : The document currently goes back and forth between " SSLv3 " & " SSL 3.0 " . Stick with the latter for consistency and clarity .
Paragraph (version A):
This alert was used in SSLv3 but not any version of TLS.  It MUST
NOT be sent by compliant implementations.  This message is always
fatal.
Paragraph (version B):
This alert was used in SSL 3.0 but not any version of TLS.  It
MUST NOT be sent by compliant implementations.  This message is
always fatal.
Paragraph (version A):
Note: Values listed as RESERVED MUST NOT be used.  They were used in
SSLv3.
Paragraph (version B):
Note: Values listed as RESERVED MUST NOT be used.  They were used in
SSL 3.0.
Draft: draft-ietf-tls-tls13

Commentary: RFC2119 - ify a few little bits to be more clear
Paragraph (version A):
Each connection state contains a sequence number, which is
maintained separately for read and write states.  The sequence
number MUST be set to zero whenever a connection state is made the
active state.  Sequence numbers are of type uint64 and may not
exceed 2^64-1.  Sequence numbers do not wrap.  If a TLS
implementation would need to wrap a sequence number, it must
terminate the connection.  A sequence number is incremented after
each record: specifically, the first record transmitted under a
particular connection state MUST use sequence number 0.
Paragraph (version B):
Each connection state contains a sequence number, which is
maintained separately for read and write states.  The sequence
number MUST be set to zero whenever a connection state is made the
active state.  Sequence numbers are of type uint64 and MUST NOT
exceed 2^64-1.  Sequence numbers do not wrap.  If a TLS
implementation would need to wrap a sequence number, it MUST
terminate the connection.  A sequence number is incremented after
each record: specifically, the first record transmitted under a
particular connection state MUST use sequence number 0.
Paragraph (version A):
Note: Values listed as RESERVED may not be used.  They were used in
SSLv3.
Paragraph (version B):
Note: Values listed as RESERVED MUST NOT be used.  They were used in
SSLv3.
Draft: draft-ietf-tls-tls13

Commentary: Removal of the glossary re - assigned the appendix letters , so the ones referenced here are all one earlier .
Paragraph (version A):
Security issues are discussed throughout this memo, especially in
Appendices D, E, and F.
Paragraph (version B):
Security issues are discussed throughout this memo, especially in
Appendices C, D, and E.
Draft: draft-ietf-tls-tls13

Commentary: Added because git became sad somehow
Paragraph (version B):
client: The endpoint initiating the TLS connection.
Paragraph (version B):
connection: A transport-layer connection between two endpoints.
Paragraph (version B):
endpoint: Either the client or server of the connection.
Paragraph (version B):
handshake: An initial negotiation between client and server that
establishes the parameters of their transactions.
Paragraph (version B):
peer: An endpoint.  When discussing a particular endpoint, "peer"
refers to the endpoint that is remote to the primary subject of
discussion.
Paragraph (version B):
receiver: An endpoint that is receiving records.
Paragraph (version B):
sender: An endpoint that is transmitting records.
Paragraph (version B):
session: An association between a client and a server resulting from
a handshake.
Paragraph (version B):
server: The endpoint which did not initiate the TLS connection.
Draft: draft-ietf-tls-tls13

Commentary: ( includes ) 
 I 'll let native speakers fix the typos next time xD 
 Your intuition on how to treat that last one was not wrong , but you need to know the specifics of the terminology to handle it properly . If that were n't a specific term , you 'd have been correct , though usage of the word " compatible " there would 've been strange . As to hyphenation , tech terminology turns hyphenated words into compound words way faster than natural language evolution . In other words , we tend to make up new words frequently and write them shorter each time . ;) 
 In my experience , native speakers are usually far from the best :) 
 Native speakers can muddle through free - form usage easily , so they do n't notice how bad things might be to others . Non - native speakers ca n't intuitively piece together words as easily , and thus follow the rules more , which can be problematic because no verbal language actually follows its own rules fully , especially ones with lots of borrowed words . We all screw up language in different and interesting ways . :p I think a rebase is needed , as the whitespace changes were merged via your other PR . A squash of these commits into one to drop the reverted bits is probably a good idea , while you 're at it . 
 Done , ready for merge ... =)
Paragraph (version A):
The record protection functions translate a TLSPlaintext structure
into a TLSCiphertext.  The deprotection functions reverse the
process.  In TLS 1.3 as opposed to previous versions of TLS, all
ciphers are modelled as "Authenticated Encryption with Additional
Data" (AEAD) RFC5116.  AEAD functions provide a unified encryption
and authentication operation which turns plaintext into authenticated
ciphertext and back again.
Paragraph (version B):
The record protection functions translate a TLSPlaintext structure
into a TLSCiphertext.  The deprotection functions reverse the
process.  In TLS 1.3 as opposed to previous versions of TLS, all
ciphers are modeled as "Authenticated Encryption with Additional
Data" (AEAD) RFC5116.  AEAD functions provide a unified encryption
and authentication operation which turns plaintext into authenticated
ciphertext and back again.
Paragraph (version A):
Servers MUST NOT send the EarlyData extension.  Negotiating TLS 1.3
serves as acknowledgement that it was processed as described above.
Paragraph (version B):
Servers MUST NOT send the EarlyData extension.  Negotiating TLS 1.3
serves as acknowledgment that it was processed as described above.
Draft: draft-ietf-tls-tls13

Commentary: Expands on improvements . The obsolete alerts were previously fatal and still are .  them as such . Also fix one of their names which is missing the " _ RESERVED " in the descriptions list .
Paragraph (version A):
This alert was used in some earlier versions of TLS, and may have
permitted certain attacks against the CBC mode CBCATT.  It MUST
NOT be sent by compliant implementations.
Paragraph (version B):
This alert was used in some earlier versions of TLS, and may have
permitted certain attacks against the CBC mode CBCATT.  It MUST
NOT be sent by compliant implementations.  This message is always
fatal.
Paragraph (version A):
This alert was used in previous versions of TLS.  TLS 1.3 does not
include compression and TLS 1.3 implementations MUST NOT send this
alert when in TLS 1.3 mode.
Paragraph (version B):
This alert was used in previous versions of TLS.  TLS 1.3 does not
include compression and TLS 1.3 implementations MUST NOT send this
alert when in TLS 1.3 mode.  This message is always fatal.
Paragraph (version A):
This alert was used in SSLv3 but not any version of TLS.  It MUST
NOT be sent by compliant implementations.
Paragraph (version B):
This alert was used in SSLv3 but not any version of TLS.  It MUST
NOT be sent by compliant implementations.  This message is always
fatal.
Paragraph (version A):
This alert was used in some earlier versions of TLS.  It MUST NOT
be sent by compliant implementations.
Paragraph (version B):
This alert was used in some earlier versions of TLS.  It MUST NOT
be sent by compliant implementations.  This message is always
fatal.
Draft: draft-ietf-tls-tls13

Commentary: Sorry 'bout all that me re - learning git again . 
 Assuming I 've learned git properly , fixing the above should just be : git reset --hard HEAD~2 git push -f ( done on this branch , of course ; check branch log before pushing ! ) 
 Whenever you do a , always , ALWAYS specify a destination . You can be screwed by your config if you do n't . The alternative is to do this : and open a new pull request . No force pushes that way ( just a dead branch somewhere ) .
Paragraph (version A):
no_renegotiation Sent by the client in response to a ServerHello or
by the server in response to a ClientHello after initial handshaking.
Versions of TLS prior to TLS 1.3 supported renegotiation of a
previously established connection; TLS 1.3 removes this feature.
This message is always fatal.
Paragraph (version B):
no_renegotiation Sent by the client in response to a HelloRequest or
by the server in response to a ClientHello after initial handshaking.
Versions of TLS prior to TLS 1.3 supported renegotiation of a
previously established connection; TLS 1.3 removes this feature.
This message is always fatal.
Draft: draft-ietf-tls-tls13

Commentary: These two notes are leftover from TLS 1.2 and not needed anymore in TLS 1.3 . The first may not even be valid anymore .
Paragraph (version A):
Note: this is a change from TLS 1.1 where there are no explicit
rules, but as a practical matter one can assume that the peer
supports MD5 and SHA-1.
Paragraph (version A):
If the client provided a "signature_algorithms" extension, then all
certificates provided by the server MUST be signed by a hash/
signature algorithm pair that appears in that extension.  Note that
this implies that a certificate containing a key for one signature
algorithm MAY be signed using a different signature algorithm (for
instance, an RSA key signed with a DSA key).  This is a departure
from TLS 1.1, which required that the algorithms be the same.
Paragraph (version B):
If the client provided a "signature_algorithms" extension, then all
certificates provided by the server MUST be signed by a hash/
signature algorithm pair that appears in that extension.  Note that
this implies that a certificate containing a key for one signature
algorithm MAY be signed using a different signature algorithm (for
instance, an RSA key signed with a DSA key).
Draft: draft-ietf-tls-tls13

Commentary: TLS has never before done this .
Paragraph (version A):
The named group for the key share offer.  This identifies the
specific key exchange method that the ClientKeyShareOffer
describes.  Finite Field Diffie-Hellman parameters are described
in ffdhe-param; Elliptic Curve Diffie-Hellman parameters are
described in ecdhe-param.
Paragraph (version B):
The named group for the key share offer.  This identifies the
specific key exchange method that the ClientKeyShareOffer
describes.  Finite Field Diffie-Hellman DH parameters are
described in ffdhe-param; Elliptic Curve Diffie-Hellman parameters
are described in ecdhe-param.
Paragraph (version A):
Diffie-Hellman parameters for both clients and servers are encoded in
the opaque key_exchange field of the ClientKeyShareOffer or
ServerKeyShare structures.  The opaque value contains the Diffie-
Hellman public value (dh_Y = g^X mod p), encoded as a big-endian
integer.
Paragraph (version B):
Diffie-Hellman DH parameters for both clients and servers are encoded
in the opaque key_exchange field of the ClientKeyShareOffer or
ServerKeyShare structures.  The opaque value contains the Diffie-
Hellman public value (dh_Y = g^X mod p), encoded as a big-endian
integer.
Paragraph (version A):
A conventional Diffie-Hellman computation is performed.  The
negotiated key (Z) is used as the pre_master_secret, and is converted
into the master_secret, as specified above.  Leading bytes of Z that
contain all zero bits are stripped before it is used as the
pre_master_secret.
Paragraph (version B):
A conventional Diffie-Hellman computation is performed DH.  The
negotiated key (Z) is used as the pre_master_secret, and is converted
into the master_secret, as specified above.  Leading bytes of Z that
contain all zero bits are stripped before it is used as the
pre_master_secret.
Draft: draft-ietf-tls-tls13

Commentary: The TLS 1.2 RFC cited WIP extension definitions at time of publish . Update current draft to point the final RFC 6066 . 
 Fix merged . This should be closable now .
Paragraph (version A):
The initial set of extensions is defined in a companion document
TLSEXT.  The list of extension types is maintained by IANA as
described in iana-considerations.
Paragraph (version B):
The initial set of extensions is defined in RFC6066.  The list of
extension types is maintained by IANA as described in iana-
considerations.
Paragraph (version A):
Note: this extension is not meaningful for TLS versions prior to 1.2.
Clients MUST NOT offer it if they are offering prior versions.
However, even if clients do offer it, the rules specified in TLSEXT
require servers to ignore extensions they do not understand.
Paragraph (version B):
Note: this extension is not meaningful for TLS versions prior to 1.2.
Clients MUST NOT offer it if they are offering prior versions.
However, even if clients do offer it, the rules specified in RFC6066
require servers to ignore extensions they do not understand.
Paragraph (version A):
The "server_name" and "trusted_ca_keys" extensions TLSEXT are used
to guide certificate selection.
Paragraph (version B):
The "server_name" and "trusted_ca_keys" extensions RFC6066 are
used to guide certificate selection.
Draft: draft-ietf-tls-tls13

Commentary: I think I found a straggling reference to renegotiation .
Paragraph (version A):
The hello phase messages are used to exchange security enhancement
capabilities between the client and server.  When a new session
begins, the record layer's connection state AEAD algorithm is
initialized to NULL_NULL.  The current connection state is used for
renegotiation messages.
Paragraph (version B):
The hello phase messages are used to exchange security enhancement
capabilities between the client and server.  When a new session
begins, the record layer's connection state AEAD algorithm is
initialized to NULL_NULL.
Draft: draft-ietf-tls-tls13

Commentary: I have seen multiple implementations with messages marked as warning instead of fatal .. It might be more explicit this way ? B. 
 I like this because some folks never read the text they just look at the code .
Paragraph (version A):
Reception of a handshake_failure alert message indicates that the
sender was unable to negotiate an acceptable set of security
parameters given the options available.  This is a fatal error.
Paragraph (version B):
Reception of a handshake_failure alert message indicates that the
sender was unable to negotiate an acceptable set of security
parameters given the options available.  This message is always
fatal.
Draft: draft-ietf-tls-tls13

Commentary: Four instead of three ? ( hs , alert , app_data ) Allusion to CCS ... ? Cheers , B.
Paragraph (version A):
Four protocols that use the record protocol are described in this
document: the handshake protocol, the alert protocol, and the
application data protocol.  In order to allow extension of the TLS
protocol, additional record content types can be supported by the
record protocol.  New record content type values are assigned by IANA
in the TLS Content Type Registry as described in iana-considerations.
Paragraph (version B):
Three protocols that use the record protocol are described in this
document: the handshake protocol, the alert protocol, and the
application data protocol.  In order to allow extension of the TLS
protocol, additional record content types can be supported by the
record protocol.  New record content type values are assigned by IANA
in the TLS Content Type Registry as described in iana-considerations.
Draft: draft-ietf-tls-tls13

Commentary: Just fixing up something should have been deleted in pull request .
Paragraph (version A):
Four protocols that use the record protocol are described in this
document: the handshake protocol, the alert protocol, the change
cipher spec protocol, and the application data protocol.  In order to
allow extension of the TLS protocol, additional record content types
can be supported by the record protocol.  New record content type
values are assigned by IANA in the TLS Content Type Registry as
described in iana-considerations.
Paragraph (version B):
Four protocols that use the record protocol are described in this
document: the handshake protocol, the alert protocol, and the
application data protocol.  In order to allow extension of the TLS
protocol, additional record content types can be supported by the
record protocol.  New record content type values are assigned by IANA
in the TLS Content Type Registry as described in iana-considerations.
Draft: draft-ietf-tls-tls13

Commentary: This applies to TLS 1.3 draft 4 . The ffdhe groups in Section 7.3.2.5.2 are n't up - to - date with draft - ietf - tls - negotiated - ff - dhe-04 :  ) has been replaced with ffdhe2048(256 ) . ffdhe6144(259 ) is no more . ffdhe8192(260 ) has been renumbered to ffdhe8192(259 ) . The note in Section 8.1.3 has text that refers to the old TLS 1.2 and earlier key exchange method , where the server could select any DH - parameters it liked . NamedGroup and NamedGroupList should be to somewhere in appendix A. 
 Thanks . WRT to the appendix , I am going to let it get out of date for a draft or two and then do a mass update . 
 I am now auto - generating the appendix , so it will hopefully get less out of sync 
 Grubba , PTAL at the Pull Request above . 
 Looks good to me . 
 The latest FFDHE - draft ( 06 ) has reintroduced FFDHE-6144 , and replaced FFDHE-2048 with FFDHE-2432 , so this issue should probably be reopened .
Paragraph (version A):
Note: Diffie-Hellman parameters are specified by the server and may
be either ephemeral or contained within the server's certificate.
Draft: draft-ietf-tls-tls13

Commentary: The appendix kept getting out of sync , so autogenerate it 
 Not how I would have done it , but if it works , then it 's fine .
Paragraph (version B):
For Finished messages sent by the client, the string "client
finished".  For Finished messages sent by the server, the string
"server finished".
Draft: draft-ietf-tls-tls13

Commentary: PR for suggestion for issue . 
 Is this helping ? 
 Glossaries are usually a good thing , but pretty much everything in there is either in need of pruning out or is better explained in its relevant section . The HTTP/2 spec just includes a really short glossary of basic terms up top : This seems like a better way to do this . 
 Not sure if this is the best route , but creating a PR for it was quick to do . 
 I 'm in favor of removing the glossary . I do n't think there 's any need to explain what AES , DSA , etc . is in this document . Maybe it was needed when it first came out but it 's not needed now . The only definition I thought might be needed is application layer / application layer protocol , but if you read s1 ( right before where these terms will go ) the concepts of layering on top of TLS is explained well enough in my mind . I could see adding a definition for " resumption " though . 
 Define resumption in - line with the text when it is first used , maybe . But I like  's change . 
 I can live with that too . Having it defined will hopefully stop these kind of things : 
 Merged .
Paragraph (version B):
client: The endpoint initiating the TLS connection.
Paragraph (version B):
connection: A transport-layer connection between two endpoints.
Paragraph (version B):
endpoint: Either the client or server of the connection.
Paragraph (version B):
handshake: An initial negotiation between client and server that
establishes the parameters of their transactions.
Paragraph (version B):
peer: An endpoint.  When discussing a particular endpoint, "peer"
refers to the endpoint that is remote to the primary subject of
discussion.
Paragraph (version B):
receiver: An endpoint that is receiving records.
Paragraph (version B):
sender: An endpoint that is transmitting records.
Paragraph (version B):
session: An association between a client and a server resulting from
a handshake.
Paragraph (version B):
server: The endpoint which did not initiate the TLS connection.