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

Commentary: When I was implementing the key schedule , it was unclear to me what stands for . This additional note would help other implementors . Kazuho Oku pointed out the similarity to Handshake Context . So , I updated that part , too .
Paragraph (version A):
In all cases, the handshake context is formed by concatenating the
indicated handshake messages, including the handshake message type
and length fields.
Paragraph (version B):
In all cases, the handshake context is formed by concatenating the
indicated handshake messages, including the handshake message type
and length fields, but not including record layer headers.
Paragraph (version A):
The Hash function and the HKDF hash are the cipher suite hash
algorithm.  Hash.length is its output length.
Paragraph (version B):
The Hash function and the HKDF hash are the cipher suite hash
algorithm.  Hash.length is its output length.  Messages are the
concatenation of the indicated handshake messages, including the
handshake message type and length fields, but not including record
layer headers.
Draft: draft-ietf-tls-tls13

Commentary: .fragment is undefined . I guess it should be " TLSCiphertext.encrypted_record " ? sentence " due to the inclusion of and however much padding is supplied by the sender " is unclear to me . Does it mean " due to the inclusion of and the padding " ?
Paragraph (version A):
The AEAD output consists of the ciphertext output by the AEAD
encryption operation.  The length of the plaintext is greater than
TLSPlaintext.length due to the inclusion of TLSPlaintext.type and
however much padding is supplied by the sender.  The length of the
AEAD output will generally be larger than the plaintext, but by an
amount that varies with the AEAD algorithm.  Since the ciphers might
incorporate padding, the amount of overhead could vary with different
lengths of plaintext.  Symbolically,
Paragraph (version B):
The AEAD output consists of the ciphertext output by the AEAD
encryption operation.  The length of the plaintext is greater than
TLSPlaintext.length due to the inclusion of TLSPlaintext.type and any
padding supplied by the sender.  The length of the AEAD output will
generally be larger than the plaintext, but by an amount that varies
with the AEAD algorithm.  Since the ciphers might incorporate
padding, the amount of overhead could vary with different lengths of
plaintext.  Symbolically,
Draft: draft-ietf-tls-tls13

Commentary: I think this is a typo . But I 'm not sure since I 'm not a native English speaker . Please check it out .
Paragraph (version A):
This structure is intended to prevent an attack on previous versions
of previous versions of TLS in which the ServerKeyExchange format
meant that attackers could obtain a signature of a message with a
chosen, 32-byte prefix.  The initial 64 byte pad clears that prefix.
Paragraph (version B):
This structure is intended to prevent an attack on previous versions
of TLS in which the ServerKeyExchange format meant that attackers
could obtain a signature of a message with a chosen, 32-byte prefix.
The initial 64 byte pad clears that prefix.
Draft: draft-ietf-tls-tls13

Commentary: and fix also not needed comma 
 : +1 : was about to fix this too . Change was introduced by in ( included with draft 16 ) . 
 Hi , I have update the change !
Paragraph (version A):
TLS Alert Registry: Future values are allocated via Standards
Action RFC5226.  IANA [SHALL update/has updated] this registry to
include values for "end_of_early_data" and "missing_extension".
Paragraph (version B):
TLS Alert Registry: Future values are allocated via Standards
Action RFC5226.  IANA [SHALL update/has updated] this registry to
include values for "end_of_early_data", "missing_extension", and
"certificate_required".
Draft: draft-ietf-tls-tls13

Commentary: The current text works , but tweaking it to be more general for issue is simple . 
 In the Client Hello ( 4.1.2 ) it says : As of TLS 1.3 , all clients and servers will send at least one extension ( at least " keyshare " or " presharedkey " ) . I believe that at least the supportedversions extension is also required for a client . 
 Rather than enumerating everything here , I 've pushed a PR to just change " at least " to " e.g. " . 
 I changed this separately .
Paragraph (version A):
TLS allows extensions to follow the compression_methods field in an
extensions block.  The presence of extensions can be detected by
determining whether there are bytes following the compression_methods
at the end of the ClientHello.  Note that this method of detecting
optional data differs from the normal TLS method of having a
variable-length field, but it is used for compatibility with TLS
before extensions were defined.  As of TLS 1.3, all clients and
servers will send at least one extension (at least "key_share" or
"pre_shared_key").
Paragraph (version B):
TLS allows extensions to follow the compression_methods field in an
extensions block.  The presence of extensions can be detected by
determining whether there are bytes following the compression_methods
at the end of the ClientHello.  Note that this method of detecting
optional data differs from the normal TLS method of having a
variable-length field, but it is used for compatibility with TLS
before extensions were defined.  As of TLS 1.3, all clients and
servers will send at least one extension (e.g. "key_share" or
"pre_shared_key").
Draft: draft-ietf-tls-tls13

Commentary: Fix a reference to a section that 's directly citing a section number in plain text . ( not linkified and will break if sections change ) I assume this is a copy / paste error .
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).  This field SHALL be zero length
unless used for the post-handshake authentication exchanges
described in Section 4.5.2.
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).  This field SHALL be zero length
unless used for the post-handshake authentication exchanges
described in post-handshake-authentication.
Draft: draft-ietf-tls-tls13

Commentary: Adding " itself " makes the sentence much easier to understand . Actually , two Japanese , who are implementing TLS 1.3 independently , took a long time to understand this .
Paragraph (version A):
The client uses the "signature_algorithms" extension to indicate to
the server which signature algorithms may be used in digital
signatures.  Clients which desire the server to authenticate via a
certificate MUST send this extension.  If a server is authenticating
via a certificate and the client has not sent a
"signature_algorithms" extension then the server MUST abort the
handshake with a "missing_extension" alert (see mti-extensions).
Paragraph (version B):
The client uses the "signature_algorithms" extension to indicate to
the server which signature algorithms may be used in digital
signatures.  Clients which desire the server to authenticate itself
via a certificate MUST send this extension.  If a server is
authenticating via a certificate and the client has not sent a
"signature_algorithms" extension then the server MUST abort the
handshake with a "missing_extension" alert (see mti-extensions).
Draft: draft-ietf-tls-tls13

Commentary: please double - check 
 The 1 - RTT annotations are redundant and you also do n't need [ sender ] in brackets because we can just fill in the values , as client / server have separate tables lines
Paragraph (version A):
The [sender] in this table denotes the sending side.
Draft: draft-ietf-tls-tls13

Commentary: I think this aside is out - of - date : extensions can not be empty , and there are now defined extensions to put here .
Paragraph (version A):
The version and extensions fields have the same meanings as their
corresponding values in the ServerHello.  The server SHOULD send only
the extensions necessary for the client to generate a correct
ClientHello pair (currently no such extensions exist).  As with
ServerHello, a HelloRetryRequest MUST NOT contain any extensions that
were not first offered by the client in its ClientHello, with the
exception of optionally the "cookie" (see cookie) extension.
Paragraph (version B):
The version and extensions fields have the same meanings as their
corresponding values in the ServerHello.  The server SHOULD send only
the extensions necessary for the client to generate a correct
ClientHello pair.  As with ServerHello, a HelloRetryRequest MUST NOT
contain any extensions that were not first offered by the client in
its ClientHello, with the exception of optionally the "cookie" (see
cookie) extension.
Draft: draft-ietf-tls-tls13

Commentary: Just noticed that the MTI suites section did n't link to the suites , so here 's a minor PR with some reference fiddling for this section : Add a link in MTI suites to the suites section , now that they 're defined in this document . Nitpick ordering of extensions in MTI extensions to have them in same order as sections ( so numbers in links are consistient ) . Change plaintext reference to appendices in Security Considerations to actual references .
Paragraph (version A):
In the absence of an application profile standard specifying
otherwise, a TLS-compliant application MUST implement the
TLS_AES_128_GCM_SHA256 cipher suite and SHOULD implement the
TLS_AES_256_GCM_SHA384 and TLS_CHACHA20_POLY1305_SHA256 cipher
suites.
Paragraph (version A):
Security issues are discussed throughout this memo, especially in
Appendices B, C, and D.
Paragraph (version B):
Security issues are discussed throughout this memo, especially in
implementation-notes, backward-compatibility, and security-analysis.
Draft: draft-ietf-tls-tls13

Commentary: This extension is now empty . Minor cleanup . 
 I think " it 's own " is useful , but my instinct is that having the empty struct makes life easier . 
 If you would rather keep the empty struct , I do n't have a strong objection . Repushed with just the minor wording tweak .
Paragraph (version A):
Return an empty extension, indicating that it intends to process
the early data.  It is not possible for the server to accept only
a subset of the early data messages.
Paragraph (version B):
Return its own extension, indicating that it intends to process
the early data.  It is not possible for the server to accept only
a subset of the early data messages.
Draft: draft-ietf-tls-tls13

Commentary: We do n't actually use this syntax , and having it in here just adds useless complexity . Defining syntax we do n't actually use just risks confusing people reading the document for the first time .
Paragraph (version A):
For enumerateds that are never converted to external representation,
the numerical information may be omitted.
Draft: draft-ietf-tls-tls13

Commentary: I believe that these are just cleanup , though you might want to check the PSK one a little more carefully ( happy to separate it if it is a problem ) . 
 We seem to have reached consensus that the record layer will use the AEAD form only . The stream and CBC forms will be removed . 
 Fixed .
Paragraph (version A):
RFC6066 and RFC6961 provide extensions to negotiate the server
sending OCSP responses to the client.  In TLS 1.2 and below, the
server sends an empty extension to indicate negotiation of this
extension and the OCSP information is carried in a CertificateStatus
message.  In TLS 1.3, the server's OCSP information is carried in an
extension in the CertificateEntry containing the assoiciated
certificate.  Specifically: The body of the "status_request" or
"status_request_v2" extension from the server MUST be a
CertificateStatus structure as defined in RFC6066 and RFC6961
respectively.
Paragraph (version B):
RFC6066 and RFC6961 provide extensions to negotiate the server
sending OCSP responses to the client.  In TLS 1.2 and below, the
server sends an empty extension to indicate negotiation of this
extension and the OCSP information is carried in a CertificateStatus
message.  In TLS 1.3, the server's OCSP information is carried in an
extension in the CertificateEntry containing the associated
certificate.  Specifically: The body of the "status_request" or
"status_request_v2" extension from the server MUST be a
CertificateStatus structure as defined in RFC6066 and RFC6961
respectively.
Draft: draft-ietf-tls-tls13

Commentary: The caveats at the beginning are silly We do n't seem to every use Foo = { A , B } but we do use Foo = A ; 
 Fixed , thanks
Paragraph (version A):
This document deals with the formatting of data in an external
representation.  The following very basic and somewhat casually
defined presentation syntax will be used.  The syntax draws from
several sources in its structure.  Although it resembles the
programming language "C" in its syntax and XDR RFC4506 in both its
syntax and intent, it would be risky to draw too many parallels.  The
purpose of this presentation language is to document TLS only; it has
no general application beyond that particular goal.
Paragraph (version B):
This document deals with the formatting of data in an external
representation.  The following very basic and somewhat casually
defined presentation syntax will be used.
Paragraph (version A):
Typed constants can be defined for purposes of specification by
declaring a symbol of the desired type and assigning values to it.
Paragraph (version A):
Under-specified types (opaque, variable-length vectors, and
structures that contain opaque) cannot be assigned values.  No fields
of a multi-element structure or vector may be omitted.
Draft: draft-ietf-tls-tls13

Commentary: Some extension names are incorrect .
Paragraph (version A):
A "supported_group" (negotiated-groups) extension which indicates
the (EC)DHE groups which the client supports and a "key_share"
(key-share) extension which contains (EC)DHE shares for some or
all of these groups.
Paragraph (version B):
A "supported_groups" (negotiated-groups) extension which indicates
the (EC)DHE groups which the client supports and a "key_share"
(key-share) extension which contains (EC)DHE shares for some or
all of these groups.
Paragraph (version A):
If the server does not select a PSK, then the first three of these
options are entirely orthogonal: the server independently selects a
cipher suite, an (EC)DHE group and key share for key establishment,
and a signature algorithm/certificate pair to authenticate itself to
the client.  If there is overlap in the "supported_group" extension
but the client did not offer a compatible "key_share" extension, then
the server will respond with a HelloRetryRequest (hello-retry-
request) message.
Paragraph (version B):
If the server does not select a PSK, then the first three of these
options are entirely orthogonal: the server independently selects a
cipher suite, an (EC)DHE group and key share for key establishment,
and a signature algorithm/certificate pair to authenticate itself to
the client.  If there is overlap in the "supported_groups" extension
but the client did not offer a compatible "key_share" extension, then
the server will respond with a HelloRetryRequest (hello-retry-
request) message.
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_group" 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.
Draft: draft-ietf-tls-tls13

Commentary: This patch clarifies the presentation language to fix issue 700 .
Paragraph (version A):
Defined structures may have variants based on some knowledge that is
available within the environment.  The selector must be an enumerated
type that defines the possible variants the structure defines.  There
must be a case arm for every element of the enumeration declared in
the select.  Case arms have limited fall-through: if two case arms
follow in immediate succession with no fields in between, then they
both contain the same fields.  Thus, in the example below, "orange"
and "banana" both contain V2.  Note that this piece of syntax was
added in TLS 1.2 RFC5246.
Paragraph (version B):
Defined structures may have variants based on some knowledge that is
available within the environment.  The selector must be an enumerated
type that defines the possible variants the structure defines.  There
must be a case arm for every element of the enumeration declared in
the select.  Case arms have limited fall-through: if two case arms
follow in immediate succession with no fields in between, then they
both contain the same fields.  Thus, in the example below, "orange"
and "banana" both contain V2.  Note that this piece of syntax was
added in TLS 1.2 RFC5246.  Each case arm can have one or more fields.
Draft: draft-ietf-tls-tls13

Commentary: 1 ) Switches uses of ALPN label / value to " ALPN protocol " ( to clarify this is referring to a single protocol , not the entire extension ) 2 ) Remove plural from external PSK case ( if there 's not way for the client to select which protocol the 0 - RTT data uses , it does n't make sense for there to be multiple options ) 3 ) Switch reference from RFC7443 to RFC7301 ( I assume this is what was intended ) I think this makes the intended behavior of the spec a bit more clear .
Paragraph (version A):
The parameters for the 0-RTT data (symmetric cipher suite, ALPN,
etc.) are the same as those which were negotiated in the connection
which established the PSK.  The PSK used to encrypt the early data
MUST be the first PSK listed in the client's "pre_shared_key"
extension.
Paragraph (version B):
The parameters for the 0-RTT data (symmetric cipher suite, ALPN
protocol, etc.) are the same as those which were negotiated in the
connection which established the PSK.  The PSK used to encrypt the
early data MUST be the first PSK listed in the client's
"pre_shared_key" extension.
Paragraph (version A):
In order to accept early data, the server server MUST have accepted a
PSK cipher suite and selected the the first key offered in the
client's "pre_shared_key" extension.  In addition, it MUST verify
that the following values are consistent with those negotiated in the
connection during which the ticket was established.
Paragraph (version A):
The selected ALPN RFC7443 value, if any.
Paragraph (version B):
In order to accept early data, the server MUST have accepted a PSK
cipher suite and selected the first key offered in the client's
"pre_shared_key" extension.  In addition, it MUST verify that the
following values are consistent with those negotiated in the
connection during which the ticket was established.
Paragraph (version B):
The selected ALPN RFC7301 protocol, if any.
Paragraph (version A):
If the server rejects the "early_data" extension, the client
application MAY opt to retransmit the data once the handshake has
been completed.  TLS stacks SHOULD not do this automatically and
client applications MUST take care that the negotiated parameters are
consistent with those it expected.  For example, if the ALPN value
has changed, it is likely unsafe to retransmit the original
application layer data.
Paragraph (version B):
If the server rejects the "early_data" extension, the client
application MAY opt to retransmit the data once the handshake has
been completed.  TLS stacks SHOULD not do this automatically and
client applications MUST take care that the negotiated parameters are
consistent with those it expected.  For example, if the selected ALPN
protocol has changed, it is likely unsafe to retransmit the original
application layer data.
Draft: draft-ietf-tls-tls13

Commentary: All other fields deprecated by this spec use " MUST be set to ... " , such as ClientHello.legacyversion , ClientHello.legacycompressionmethods , TLSPlaintext.legacyrecordversion . Only ClientHello.legacysession_id " SHOULD be set as [ ... ] " So I suggest changing this to " MUST " as well .
Paragraph (version A):
Versions of TLS before TLS 1.3 supported a session resumption
feature which has been merged with Pre-Shared Keys in this version
(see resumption-and-psk).  This field MUST be ignored by a server
negotiating TLS 1.3 and SHOULD be set as a zero length vector
(i.e., a single zero byte length field) by clients which do not
have a cached session ID set by a pre-TLS 1.3 server.
Paragraph (version B):
Versions of TLS before TLS 1.3 supported a session resumption
feature which has been merged with Pre-Shared Keys in this version
(see resumption-and-psk).  This field MUST be ignored by a server
negotiating TLS 1.3 and MUST be set as a zero length vector (i.e.,
a single zero byte length field) by clients which do not have a
cached session ID set by a pre-TLS 1.3 server.
Draft: draft-ietf-tls-tls13

Commentary: Before record protection is established , if an endpoint receives a TLSPlaintext structure whose " length " field is too large ( 2 ^ 14 ) , should it send a " record_overflow " alert ?
Paragraph (version A):
The length (in bytes) of the following TLSPlaintext.fragment.  The
length MUST NOT exceed 2^14.
Paragraph (version B):
The length (in bytes) of the following TLSPlaintext.fragment.  The
length MUST NOT exceed 2^14.  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: with few possible exceptions , enumerateds will assume values different than the ones they were originally defined with . Backwards compatibility of   is dependent on implementations being able to ignore values they do not know about . 
 This does n't seem quite right . Some enums are complete in the sense that you should not ignore unknown ones ( HandshakeType ) and some are not complete ( ExtensionType , CipherSuite ) . 
 How about then " parse and ignore them unless the their deifnition states otherwise " . ? 
 sure that would be fine
Paragraph (version A):
An additional sparse data type is available called enum.  A field of
type enum can only assume the values declared in the definition.
Each definition is a different type.  Only enumerateds of the same
type may be assigned or compared.  Every element of an enumerated
must be assigned a value, as demonstrated in the following example.
Since the elements of the enumerated are not ordered, they can be
assigned any unique value, in any order.
Paragraph (version B):
An additional sparse data type is available called enum.  Each
definition is a different type.  Only enumerateds of the same type
may be assigned or compared.  Every element of an enumerated must be
assigned a value, as demonstrated in the following example.  Since
the elements of the enumerated are not ordered, they can be assigned
any unique value, in any order.
Paragraph (version B):
Future extension or additions to the protocol may define new values.
Implementations need to be able to parse and ignore them unless their
definition states otherwise.
Paragraph (version A):
In the following example, Taste will consume two bytes in the data
stream but can only assume the values 1, 2, or 4.
Paragraph (version B):
In the following example, Taste will consume two bytes in the data
stream but can only assume the values 1, 2, or 4 in current version
of protocol.