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

Commentary: The sentinel value was chosen to avoid conflicting with any valid TLS 1.2 value , but this is not actually desirable . We need to avoid conflicting with any non - TLS-1.3 server but still be a valid TLS 1.2 value . A TLS 1.3 server must still correctly implement TLS 1.2 to interoperate with existing TLS 1.2 clients . In particular , placing it at the front clobbers TLS 1.2 's server timestamp . Putting this in the random was silly and 1.3 rightfully removes it , but some software depends on servers sending a timestamp . The tlsdate program uses this as a secure - ish time synchronization protocol . Silly as it is , it exists and it arguably was following the letter of the TLS 1.2 spec , even if we do n't like that timestamp very much ... Move the sentinel to the end so servers may implement this downgrade protection ( which will be needed in the short term given the current version negotiation as it forces browsers to implement the version fallback again ) without breaking any tlsdate instances which may still exist .
Paragraph (version A):
TLS 1.3 clients receiving a TLS 1.2 or below ServerHello MUST check
that the top eight octets are not equal to either of these values.
TLS 1.2 clients SHOULD also perform this check if the ServerHello
indicates TLS 1.1 or below.  If a match is found, the client MUST
abort the handshake with a fatal "illegal_parameter" alert.  This
mechanism provides limited protection against downgrade attacks over
and above that provided by the Finished exchange: because the
ServerKeyExchange includes a signature over both random values, it is
not possible for an active attacker to modify the randoms without
detection as long as ephemeral ciphers are used.  It does not provide
downgrade protection when static RSA is used.
Paragraph (version B):
TLS 1.3 clients receiving a TLS 1.2 or below ServerHello MUST check
that the last eight octets are not equal to either of these values.
TLS 1.2 clients SHOULD also perform this check if the ServerHello
indicates TLS 1.1 or below.  If a match is found, the client MUST
abort the handshake with a fatal "illegal_parameter" alert.  This
mechanism provides limited protection against downgrade attacks over
and above that provided by the Finished exchange: because the
ServerKeyExchange includes a signature over both random values, it is
not possible for an active attacker to modify the randoms without
detection as long as ephemeral ciphers are used.  It does not provide
downgrade protection when static RSA is used.
Paragraph (version A):
Note: Versions of TLS prior to TLS 1.3 used the top 32 bits of the
Random value to encode the time since the UNIX epoch.  The sentinel
value above was selected to avoid conflicting with any valid TLS 1.2
Random value and to have a low (2^{-64}) probability of colliding
with randomly selected Random values.
Draft: draft-ietf-tls-tls13

Commentary: I would actually much rather we only offer one PSK identity since TLS 1.2 was perfectly fine offering just one and resumption has no use for offering multiple , but I suspect I will lose that fight . Absent that , at least make the protocol well - defined . Unlike both TLS 1.2 resumption and TLS 1.2 PSK , TLS 1.3 increases the state space and allows clients to offer multiple PSK identities . This mostly works , but 0 - RTT presumes that only one is offered . Define 0 - RTT to presume the first identity is selected and clarify that other shapes are possible due to the increased state space .
Paragraph (version A):
When resuming via a PSK with an appropriate ticket (i.e., one with
the "allow_early_data" flag), clients can also send data on their
first flight ("early data").  This data is encrypted solely under
keys derived using the PSK as the static secret.  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.
Paragraph (version B):
When resuming via a PSK with an appropriate ticket (i.e., one with
the "allow_early_data" flag), clients can also send data on their
first flight ("early data").  This data is encrypted solely under
keys derived using the first offered PSK as the static secret.  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.
Paragraph (version A):
A list of the identities (labels for keys) that the client is
willing to negotiate with the server.
Paragraph (version B):
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 A):
If the server selects a PSK cipher suite, it MUST send a
"pre_shared_key" extension with the identity that it selected.  The
client MUST verify that the server's selected_identity is within the
range supplied by the client.  If any other value is returned, the
client MUST generate a fatal "unknown_psk_identity" alert and close
the connection.
Paragraph (version B):
If the server selects a PSK cipher suite, it MUST send a
"pre_shared_key" extension with the identity that it selected.  The
client MUST verify that the server's selected_identity is within the
range supplied by the client.  If the server supplies an "early_data"
extension, the client MUST verify that the server selected the first
offered identity.  If any other value is returned, the client MUST
generate a fatal "unknown_psk_identity" alert and close the
connection.
Paragraph (version B):
Note that, although 0-RTT data is encrypted with the first PSK
identity, the server may fall back to 1-RTT and select a different
PSK identity if multiple are offered.
Draft: draft-ietf-tls-tls13

Commentary: The section on connection states was almost all cruft . I made a new section for nonce construction and moved the piece on sequence numbers there . The only text I modified was the first three paragraphs of the nonce section , which needed to be scrubbed for references to " connection state " , and the lead - in section on the AEAD , which I moved to where the other AEAD stuff was and expanded a little to include some forward references . 
 LGTM Did you still want to replace any of this ? The stuff being cut here is very obsolete and must confuse anyone who attempts to read through the whole spec . 
 Yes , I 'm working on it this week . ,   wrote :
Paragraph (version A):
The two cryptographic operations -- digital signing, and
authenticated encryption with additional data (AEAD) -- are
designated digitally-signed, and aead-ciphered, respectively.  A
field's cryptographic processing is specified by prepending an
appropriate key word designation before the field's type
specification.  Cryptographic keys are implied by the current session
state (see connection-states).
Paragraph (version B):
The two cryptographic operations -- digital signing, and
authenticated encryption with additional data (AEAD) -- are
designated digitally-signed, and aead-ciphered, respectively.  A
field's cryptographic processing is specified by prepending an
appropriate key word designation before the field's type
specification.
Draft: draft-ietf-tls-tls13

Commentary: and arguably should never be used in that fashion . I know that this stuff badly needs a rewrite , but this is just egregious .
Paragraph (version A):
Note: The TLS Record Protocol can operate in an insecure mode but is
generally only used in this mode while another protocol is using the
TLS Record Protocol as a transport for negotiating security
parameters.
Draft: draft-ietf-tls-tls13

Commentary: This is purely aesthetic , but apparently no one realizes the name is different , not even IANA , so we may as well go fix it . ( I do n't know how to write IANA considerations , so I 've left it a TODO . But if you give me text , I 'll update this PR to include it . ) For consistency . At a glance , it seems most TLS implementations did not realize the HandshakeType value was actually named sessionticket and assumed it was named newsession_ticket anyway . Moreover , the IANA entry was named neither and actually named NewSessionTicket since RFC 4507 's IANA considerations used the wrong name .
Paragraph (version A):
TLS HandshakeType Registry: Future values are allocated via
Standards Action RFC2434.
Paragraph (version B):
TLS HandshakeType Registry: Future values are allocated via
Standards Action RFC2434.  IANA [SHALL update/has updated] this
registry to rename item 4 from "NewSessionTicket" to
"new_session_ticket".
Draft: draft-ietf-tls-tls13

Commentary: I 'm going to see about getting rid of it anyway , but I think , for the spec , this is probably the better text , as sad as it makes me . The revised signature algorithm mechanism left the {  , ecdsa } SignatureAndHashAlgorithm without a corresponding SignatureScheme defined at all .  does not have a corresponding curve , so defining it alongside ecdsap256sha256 and friends was a nuisance . But omitting it , combined with other text , implicitly means it " MUST NOT be offered or negotiated by any implementation " . Clients ( ideally ) send only one ClientHello , so this implies a constraint on TLS 1.2 as well .  needs to go , but I think I was a tad overzealous here . I would n't be surprised {  , ecdsa } can be removed from TLS 1.2 right now . Certainly it will be much much easier to remove than { sha1 , rsa } . But this is probably better a SHOULD NOT rather than a MUST NOT . We would n't like to discover after the fact that a MUST NOT in TLS 1.3 is untenable due to some ecosystem problem . Notably , old versions of some popular server software ignore signature algorithms and only sign SHA-1 . This mostly affects RSA since ECDSA is n't that common , but any such ECDSA deployments would be affected . This is also a little odd for servers as TLS 1.2 says missing sigalgs means the client is assumed to support { sha1 , X } . ( Although , strictly speaking , the spec does not say the server must do anything useful with that advertisement . ) In contrast , dsasha1 is already not offered by many major browsers but is merely a SHOULD NOT . Define ecdsasha1RESERVED as a companion to dsa*RESERVED to bring it out of the implicit MUST NOT . Then include it in the SHOULD NOT lists alongside rsapkcs1sha1 and dsasha1 .
Paragraph (version A):
rsa_pkcs1_sha1 and dsa_sha1 SHOULD NOT be offered.  Clients offering
these values for backwards compatibility MUST list them as the lowest
priority (listed after all other algorithms in the
supported_signature_algorithms vector).  TLS 1.3 servers MUST NOT
offer a SHA-1 signed certificate unless no valid certificate chain
can be produced without it (see server-certificate-selection).
Paragraph (version B):
rsa_pkcs1_sha1, dsa_sha1, and ecdsa_sha1 SHOULD NOT be offered.
Clients offering these values for backwards compatibility MUST list
them as the lowest priority (listed after all other algorithms in the
supported_signature_algorithms vector).  TLS 1.3 servers MUST NOT
offer a SHA-1 signed certificate unless no valid certificate chain
can be produced without it (see server-certificate-selection).
Paragraph (version B):
In addition, the signature algorithm MUST be compatible with the
key in the sender's end-entity certificate.  RSA signatures MUST
use an RSASSA-PSS algorithm, regardless of whether RSASSA-
PKCS1-v1_5 algorithms appear in "signature_algorithms".  SHA-1
MUST NOT be used in any signatures in CertificateVerify.  All
SHA-1 signature algorithms in this specification are defined
solely for use in legacy certificates, and are not valid for
CertificateVerify signatures.
Draft: draft-ietf-tls-tls13

Commentary: The definition is all " etcetera " currently . We should not assume that readers can parse out the hash algorithm from the enum label .
Paragraph (version A):
Each SignatureScheme value lists a single signature algorithm that
the client is willing to verify.  The values are indicated in
descending order of preference.  Note that a signature algorithm
takes as input an arbitrary-length message, rather than a digest.
Algorithms which traditionally act on a digest should be defined in
TLS to first hash the input with a specified hash function and then
proceed as usual.
Draft: draft-ietf-tls-tls13

Commentary: PTAL 
 I was thinking if you wanted to have a cookie but not PSK for some reason . I could go either way on this . Not allowing it would have the advantage that it would always be strictly for a given connection and if QUIC wanted to have some sort of source address token it could put it elsewhere ( like in EE )
Paragraph (version B):
Allowing the server to force the client to demonstrate
reachability at their apparent network address (thus providing a
measure of DoS protection).  This is primarily useful for non-
connection-oriented transports (see RFC6347 for an example of
this).
Paragraph (version B):
Allowing the server to offload state to the client, thus allowing
it to send a HelloRetryRequest without storing any state.  The
server does this by pickling that post-ClientHello hash state into
the cookie (protected with some suitable integrity algorithm).
Paragraph (version B):
When sending a HelloRetryRequest, the server MAY provide a "cookie"
extension to the client (this is an exception to the usual rule that
the only extensions that may be sent are those that appear in the
ClientHello).  When sending the new ClientHello, the client MUST echo
the value of the extension.  Clients MUST NOT use cookies in
subsequent connections.
Paragraph (version B):
"cookie" is REQUIRED for all cipher suites.
Draft: draft-ietf-tls-tls13

Commentary: TLS 1.2 did not specify this and some implementations have sporadic interoperability issues as a result . Specify that , in TLS 1.3 , public keys should be zero - padded . This is believed to be the more compatible TLS 1.2 variant , and having cryptographic messages be fixed - width fields where possible ( not that it matters for public keys ) seems preferable to saving one byte 1/256 of the time . 
 ( Er , that should say " DHE public keys " . I 'll go do a force - push to fix the commit description . ) 
 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):
Diffie-Hellman DH parameters for both clients and servers are encoded
in the opaque key_exchange field of a KeyShareEntry in a KeyShare
structure.  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 a KeyShareEntry in a KeyShare
structure.  The opaque value contains the Diffie-Hellman public value
(dh_Y = g^X mod p), encoded as a big-endian integer, padded with
zeros to the size of p.
Paragraph (version B):
Note: For a given Diffie-Hellman group, the padding results in all
public keys having the same length.
Draft: draft-ietf-tls-tls13

Commentary: I think that you should mark this document as updating 6066 and 6961 .
Paragraph (version B):
Move CertificateStatus to an extension.
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 EncryptedExtensions.  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):
Note: this means that the certificate status appears prior to the
certificates it applies to.  This is slightly anomalous but matches
the existing behavior for SignedCertificateTimestamps RFC6962, and is
more easily extensible in the handshake state machine.
Draft: draft-ietf-tls-tls13

Commentary: You 'll also need to update the last paragraph of the MTI Extensions section ( currently section 8.2 ) . Now that we 're going to be down to only one client - only extension defined in this document , that whole paragraph can probably be cut in favor of a one - off note in the remaining extension 's section ( signature_algorithms will be the last ) . 
 So that the clients can learn about what groups a server supports . The idea here is to allow a client to offer P256 but then learn that a server supports for next time without the server having to reject .
Paragraph (version B):
As of TLS 1.3, servers are permitted to send the "supported_groups"
extension to the client.  If the server has a group it prefers to the
ones in the "key_share" extension but is still willing to accept the
ClientHello, it SHOULD send "supported_groups" to update the client's
view of its preferences.  Clients MUST NOT act upon any information
found in "supported_groups" prior to successful completion of the
handshake, but MAY use the information learned from a successfully
completed handshake to change what groups they offer to a server in
subsequent connections.
Paragraph (version A):
Some of these extensions exist only for the client to provide
additional data to the server in a backwards-compatible way and thus
have no meaning when sent from a server.  The client-only extensions
defined in this document are: "signature_algorithms" &
"supported_groups".  Servers MUST NOT send these extensions.  Clients
receiving any of these extensions MUST respond with a fatal
"unsupported_extension" alert and close the connection.
Paragraph (version B):
Servers MUST NOT send the "signature_algorithms" extension; if a
client receives this extension it MUST respond with a fatal
"unsupported_extension" alert and close the connection.
Draft: draft-ietf-tls-tls13

Commentary: The current wording of KeyUpdate a bit ambiguous , and leaves out certain areas needed for enforcement and might result in a security issue if not implemented correctly A sender of the keyupdate has no choice of which key to encrypt the keyupdate with , however the recipient does . It has 2 choices :    key and reset the sequence number after acking the keyupdate   the new key for the key update and reset the sequence number before acking the keyupdate . This distinction is very important for security . If a client uses option b ) , this causes a security vuln . Because the sequence numbers are reset after a key update , an attacker could truncate ( application data ) records from the old stream , wait for the key update from the client , and then let new packets through . The client or server has no way of figuring out this has happened . If a receiver verifies that the KeyUpdate is received with the old key before accepting messages encrypted with the new key , then this attack is prevented . 
 Excellent point . I will merge this . Please also file a PR adding yourself to acknowledgements .
Paragraph (version B):
Both sender and receiver must encrypt their KeyUpdate messages with
the old keys.  Additionally, both sides MUST enforce that a KeyUpdate
with the old key is received before accepting any messages encrypted
with the new key.  Failure to do so may allow message truncation
attacks.
Draft: draft-ietf-tls-tls13

Commentary: sanity check ? 
 This is n't going to change a great deal , but we need to identify how exporters are constructed with the change to a HKDF - based PRF and the new key schedule .
Paragraph (version B):
Note: the inner HKDF-Extract is strictly unnecessary, but it
maintains the invariant that HKDF Extract and Expand calls are
paired.
Draft: draft-ietf-tls-tls13

Commentary: Change ticketlifetimehint to ticket_lifetime and add stricter requirements . 
 lgtm Please send an email to pointing to the change and making a case for it . 
 Sent , thanks . ,   wrote : 
 Mailing list discussion here : 
 +1 
 Merging per WG discussion . please send me a PR adding yourself to acknowledgements :)
Paragraph (version A):
Indicates the lifetime in seconds as a 32-bit unsigned integer in
network byte order from the time of ticket issuance.  A value of
zero is reserved to indicate that the lifetime of the ticket is
unspecified.
Paragraph (version A):
The ticket lifetime hint is informative only.  A client SHOULD delete
the ticket and associated state when the time expires.  It MAY delete
the ticket earlier based on local policy.  A server MAY treat a
ticket as valid for a shorter or longer period of time than what is
stated in the ticket_lifetime_hint.
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.  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.
Draft: draft-ietf-tls-tls13

Commentary: the PSK acronym occurs first in the TOC , and later in S 6 without being spelled - out -- these modest changes fix that . [ this is also a small test to see if I have the tlswg+github process figured out ] 
 ok , I see the problem ( see below ) -- tho i ought to install travis , kramdown , et al hereabouts to be able to try a build locally before pushing again to here . 
 You do n't need to install everything unless you 're testing the build yourself , which usually is n't needed . 
 Oh , sorry i did n't see your suggestion above until after I 'd figured out how to fix the one xref the section title had broken -- but the fix can be easily changed to how you suggest if you all wish . also thx for the hint wrt toolchain . 
 I 'd prefer just renaming the ref , as parens do n't end up in the autogenerated one , so it looks a little odd . ( " { { resumption - and - pre - shared - key - psk } } " ) If it works , though , I do n't have a strong objection , as it does n't really matter . 
 Server Name Indication could be encrypted to protect it from being inspected by passive attackers . There are some virtual - hosting type situations where hiding this information is considered desirable . If we can encrypt SNI , then it is probably trivial to encrypt other extensions . However , this complicates the handshake . A lot . It also complicates virtual - hosting scenarios . Rich summarizes the issues pretty well here : 
 Is this already ruled - out ? How could the SNI be encrypted without an addition RTT ? One could hash the SNI in the Client Hello which would at least help if the served host name is not publicly known ( e.g. using a self - signed certificate ) . 
 It seems likely that there will eventually be an ( optional ? ) extension that permits an encrypted " real " SNI , with some fake public SNI . But maybe that is not what you are asking . 
 why was this closed ? 
 Because we are not going to do anything about it in the base specification .
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-pre-shared-key-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.