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

Commentary: cc 
 Nice ! S
Paragraph (version A):
Use of ECH does not weaken the security properties of TLS without
ECH.
Paragraph (version A):
Client-facing server configuration determines the size of the
anonymity set.  For example, if a client-facing server uses distinct
ECHConfig values for each host, then each anonymity set has size k =
maximize the size of the anonymity set where possible.  This means
client-facing servers should use the same ECHConfig for as many hosts
as possible.  An attacker can distinguish two hosts that have
different ECHConfig values based on the ECHClientHello.config_id
value.  This also means public information in a TLS handshake should
be consistent across hosts.  For example, if a client-facing server
services many backend origin hosts, only one of which supports some
cipher suite, it may be possible to identify that host based on the
contents of unencrypted handshake messages.
Paragraph (version B):
Security preservation.  Use of ECH does not weaken the security
properties of TLS without ECH.
Paragraph (version B):
Downgrade resistance.  An attacker cannot downgrade a connection
that attempts to use ECH to one that does not use ECH.
Paragraph (version B):
These properties were formally proven in ECH-Analysis.
Paragraph (version B):
With regards to handshake privacy, client-facing server configuration
determines the size of the anonymity set.  For example, if a client-
facing server uses distinct ECHConfig values for each host, then each
anonymity set has size k = 1.  Client-facing servers SHOULD deploy
ECH in such a way so as to maximize the size of the anonymity set
where possible.  This means client-facing servers should use the same
ECHConfig for as many hosts as possible.  An attacker can distinguish
two hosts that have different ECHConfig values based on the
ECHClientHello.config_id value.  This also means public information
in a TLS handshake should be consistent across hosts.  For example,
if a client-facing server services many backend origin hosts, only
one of which supports some cipher suite, it may be possible to
identify that host based on the contents of unencrypted handshake
messages.
Draft: draft-ietf-tls-esni

Commentary: I can see how that sentence is redundant , but it seems like it would be helpful to implementers .
Paragraph (version A):
The format is as defined in RFC8446, Section 4.2.  The same
interpretation rules apply: extensions MAY appear in any order, but
there MUST NOT be more than one extension of the same type in the
extensions block.  An extension can be tagged as mandatory by using
an extension type codepoint with the high order bit set to 1.  A
client that receives a mandatory extension they do not understand
MUST reject the "ECHConfig" content.
Paragraph (version B):
The format is as defined in RFC8446, Section 4.2.  The same
interpretation rules apply: extensions MAY appear in any order, but
there MUST NOT be more than one extension of the same type in the
extensions block.  An extension can be tagged as mandatory by using
an extension type codepoint with the high order bit set to 1.
Draft: draft-ietf-tls-esni

Commentary: As previously written , the wording could be understood as referring to an application using some other ( D)TLS mechanism to indicate which ECHConfig candidate value selection method to use .
Paragraph (version A):
Some uses of ECH, such as local discovery mode, may randomize the
ECHClientHello.config_id since it can be used as a tracking vector.
In such cases, the second method should be used for matching the
ECHClientHello to a known ECHConfig.  See optional-configs.  Unless
specified by the application using (D)TLS or externally configured,
implementations MUST use the first method.
Paragraph (version B):
Some uses of ECH, such as local discovery mode, may randomize the
ECHClientHello.config_id since it can be used as a tracking vector.
In such cases, the second method should be used for matching the
ECHClientHello to a known ECHConfig.  See optional-configs.  Unless
specified by the application profile or otherwise externally
configured, implementations MUST use the first method.
Draft: draft-ietf-tls-esni

Commentary: … with reference to Section 6.1.6 See also the discussion on tlswg / draft - ietf - tls - esni .
Paragraph (version A):
An ECHConfigList structure containing one or more ECHConfig
structures, in decreasing order of preference, to be used by the
client in subsequent connection attempts.  These are known as the
server's "retry configurations".
Paragraph (version B):
An ECHConfigList structure containing one or more ECHConfig
structures, in decreasing order of preference, to be used by the
client as described in rejected-ech.  These are known as the
server's "retry configurations".
Draft: draft-ietf-tls-esni

Commentary: Inspired by . We can go further and just completely define EncodedClientHelloInner first .
Paragraph (version A):
Some TLS 1.3 extensions can be quite large, thus repeating them in
the ClientHelloInner and ClientHelloOuter can lead to an excessive
overall size.  One pathological example is "key_share" with post-
quantum algorithms.  To reduce the impact of duplicated extensions,
the client may use the "ech_outer_extensions" extension.
Paragraph (version A):
OuterExtensions consists of one or more ExtensionType values, each of
which reference an extension in ClientHelloOuter.  The extensions in
OuterExtensions MUST appear in ClientHelloOuter in the same relative
order, however, there is no requirement that they be continguous.
For example, OuterExtensions may contain extensions A, B, C, while
ClientHelloOuter contains extensions A, D, B, C, E, F.
Paragraph (version A):
The "ech_outer_extensions" extension is only used for compressing the
ClientHelloInner.  It can only be included in
EncodedClientHelloInner, and MUST NOT be sent in either
ClientHelloOuter or ClientHelloInner.
Paragraph (version A):
The client then MAY substitute extensions which it knows will be
duplicated in ClientHelloOuter.  To do so, the client removes and
replaces extensions from EncodedClientHelloInner with a single
"ech_outer_extensions" extension.  Removed extensions MUST be ordered
consecutively in ClientHelloInner.  The list of outer extensions,
OuterExtensions, includes those which were removed from
EncodedClientHelloInner, in the order in which they were removed.
Paragraph (version B):
OuterExtensions contains the removed ExtensionType values.  Each
value references the matching extension in ClientHelloOuter.  The
values MUST be ordered contiguously in ClientHelloInner, and the
"ech_outer_extensions" extension MUST be inserted in the
corresponding position in EncodedClientHelloInner.  Additionally, the
extensions MUST appear in ClientHelloOuter in the same relative
order.  However, there is no requirement that they be contiguous.
For example, OuterExtensions may contain extensions A, B, C, while
ClientHelloOuter contains extensions A, D, B, C, E, F.
Paragraph (version B):
The "ech_outer_extensions" extension can only be included in
EncodedClientHelloInner, and MUST NOT appear in either
ClientHelloOuter or ClientHelloInner.
Draft: draft-ietf-tls-esni

Commentary: I 'm guessing this is almost a typo .
Paragraph (version A):
The retry mechanism repairs inconsistencies, provided the server is
authoritative for the public name.  If server and advertised keys
mismatch, the server will respond with ech_retry_requested.  If the
server does not understand the "encrypted_client_hello" extension at
all, it will ignore it as required by Section 4.1.2 of RFC8446.
Provided the server can present a certificate valid for the public
name, the client can safely retry with updated settings, as described
in rejected-ech.
Paragraph (version B):
The retry mechanism repairs inconsistencies, provided the server is
authoritative for the public name.  If server and advertised keys
mismatch, the server will reject ECH and respond with
"retry_configs".  If the server does not understand the
"encrypted_client_hello" extension at all, it will ignore it as
required by Section 4.1.2 of RFC8446.  Provided the server can
present a certificate valid for the public name, the client can
safely retry with updated settings, as described in rejected-ech.
Draft: draft-ietf-tls-esni

Commentary: 1 said to not use trial decryption unless " externally configured on both sides " but there 's no way to know that , so I think the " on both sides " ought be deleted unless something else was intended .
Paragraph (version A):
Some uses of ECH, such as local discovery mode, may randomize the
ECHClientHello.config_id since it can be used as a tracking vector.
In such cases, the second method should be used for matching the
ECHClientHello to a known ECHConfig.  See optional-configs.  Unless
specified by the application using (D)TLS or externally configured on
both sides, implementations MUST use the first method.
Paragraph (version B):
Some uses of ECH, such as local discovery mode, may randomize the
ECHClientHello.config_id since it can be used as a tracking vector.
In such cases, the second method should be used for matching the
ECHClientHello to a known ECHConfig.  See optional-configs.  Unless
specified by the application using (D)TLS or externally configured,
implementations MUST use the first method.
Draft: draft-ietf-tls-esni

Commentary: When retry - configs are defined in section 5 we say they are for " subsequent connection attempts " but in 6.1.6 we have a MUST NOT for using those for " subsequent connections . " That seems inconsistent and maybe even wrong if one thinks about how e.g. wget can crawl web pages , or how applications might use libcurl , so this change tries to fix that . Not sure if short duration is the right way to phrase it though .
Paragraph (version A):
If at least one of the values contains a version supported by the
client, it can regard the ECH keys as securely replaced by the
server.  It SHOULD retry the handshake with a new transport
connection, using the retry configurations supplied by the server.
The retry configurations may only be applied to the retry connection.
The client MUST continue to use the previously-advertised
configurations for subsequent connections.  This avoids introducing
pinning concerns or a tracking vector, should a malicious server
present client-specific retry configurations in order to identify the
client in a subsequent ECH handshake.
Paragraph (version B):
If at least one of the values contains a version supported by the
client, it can regard the ECH keys as securely replaced by the
server.  It SHOULD retry the handshake with a new transport
connection, using the retry configurations supplied by the server.
The retry configurations may only be applied to the retry connection.
The client MUST NOT use retry configurations for connections beyond
the retry.  This avoids introducing pinning concerns or a tracking
vector, should a malicious server present client-specific retry
configurations in order to identify the client in a subsequent ECH
handshake.
Draft: draft-ietf-tls-esni

Commentary: The goal here is really to provide more clarify about cardinality , if there 's a better way or place to do that , that 'd be fine . 
 I do n't believe this is necessary . This idiom is well understood in TLS and this just appears to be excess verbiage . 
 Hiya , ( As with all these PRs , I 'm ok if they 're not accepted ... ) For me , that is better than the original , but I do think we ought state the expected cardinality that implementers need to handle somewhere . I reckon it 's better to not assume implementers are very familiar with SVCB as for libraries at least , the DNS stuff happens elsewhere . They will have to figure that out eventually , but better to say it somewhere explicitly I think , or we may face some important code base that does n't handle 1 public key when it ought . Cheers , S.
Paragraph (version A):
The length, in bytes, of the next field.
Paragraph (version B):
The length, in bytes, of the next field.  This length field allows
implementations to skip over the elements in such a list where
they cannot parse the specific version of ECHConfig.
Draft: draft-ietf-tls-esni

Commentary: Not sure if this is needed , but I guess it would be another way to generate failures;- ) 
 Good clarification ! This was already somewhat in the real - ech section , so I just replaced this with a forward pointer there .
Paragraph (version A):
The list of HPKE KDF and AEAD identifier pairs clients can use for
encrypting ClientHelloInner.
Paragraph (version B):
The list of HPKE KDF and AEAD identifier pairs clients can use for
encrypting ClientHelloInner.  See real-ech for how clients choose
from this list.
Draft: draft-ietf-tls-esni

Commentary: Seems useful to note that -13 should be around for a while but still might change later 
 Yeah that 's fine . Ta , S. 
 How about this simplification based on the outcome from 111 ? I think it 's clear that future changes may occur , so I just dropped that .
Paragraph (version A):
DISCLAIMER: This draft is work-in-progress and has not yet seen
significant (or really any) security analysis.  It should not be used
as a basis for building production systems.
Paragraph (version B):
DISCLAIMER: This draft is work-in-progress and has not yet seen
significant (or really any) security analysis.  It should not be used
as a basis for building production systems.  This published version
of the draft has been designated an "implementation draft" for
testing and interop purposes.
Draft: draft-ietf-tls-esni

Commentary: Hopefully HPKE is done enough that we no longer need to pin a draft version .
Paragraph (version A):
ECH uses draft-08 of HPKE for public key encryption I-D.irtf-cfrg-
hpke.  The ECH configuration is defined by the following "ECHConfig"
structure.
Paragraph (version B):
ECH uses HPKE for public key encryption I-D.irtf-cfrg-hpke.  The ECH
configuration is defined by the following "ECHConfig" structure.
Draft: draft-ietf-tls-esni

Commentary: This assumes the formulation where , on ECH reject , the server is the client - facing server . In other words , backend servers will never get a CH without ECH having been accepted , so GREASE does n't apply there . cc 
 cc too , since he had thoughts on this
Paragraph (version A):
Otherwise, if all candidate ECHConfig values fail to decrypt the
extension, the client-facing server MUST ignore the extension and
proceed with the connection using ClientHelloOuter.  This connection
proceeds as usual, except the server MUST include the
"encrypted_client_hello" extension in its EncryptedExtensions with
the "retry_configs" field set to one or more ECHConfig structures
with up-to-date keys.  Servers MAY supply multiple ECHConfig values
of different versions.  This allows a server to support multiple
versions at once.
Paragraph (version B):
If sending a HelloRetryRequest, the server MAY include an
"encrypted_client_hello" extension with a payload of 8 random
bytes; see dont-stick-out for details.
Paragraph (version B):
If the server is configured with any ECHConfigs, it MUST include
the "encrypted_client_hello" extension in its EncryptedExtensions
with the "retry_configs" field set to one or more ECHConfig
structures with up-to-date keys.  Servers MAY supply multiple
ECHConfig values of different versions.  This allows a server to
support multiple versions at once.
Paragraph (version A):
If the client-facing server rejected ECH, or if the first ClientHello
did not include an "encrypted_client_hello" extension, the client-
facing server proceeds with the connection as usual.  The server does
not decrypt the second ClientHello's ECHClientHello.payload value, if
there is one.
Paragraph (version B):
If the client-facing server rejected ECH, or if the first ClientHello
did not include an "encrypted_client_hello" extension, the client-
facing server proceeds with the connection as usual.  The server does
not decrypt the second ClientHello's ECHClientHello.payload value, if
there is one.  Moreover, if the server is configured with any
ECHConfigs, it MUST include the "encrypted_client_hello" extension in
its EncryptedExtensions with the "retry_configs" field set to one or
more ECHConfig structures with up-to-date keys, as described in
client-facing-server.
Draft: draft-ietf-tls-esni

Commentary: Based on ( merge that first ) .
Paragraph (version A):
When the server sends a HelloRetryRequest, the client checks for the
presence of an "encrypted_client_hello" extension.  If none is found,
then the client presumes rejection and handles the HelloRetryRequest
using ClientHelloOuter.  (Note that the client-facing server does not
send this extension in its HelloRetryRequest.)  Otherwise it proceeds
as follows.
Paragraph (version B):
When the server sends a HelloRetryRequest, the client checks for the
presence of an "encrypted_client_hello" extension.  If none is found,
then the client presumes rejection and handles the HelloRetryRequest
using ClientHelloOuter.  (Note that the client-facing server does not
send this extension in its HelloRetryRequest.  [[NOTE: This may
change, depending on the outcome of issue#450.]]) Otherwise it
proceeds as follows.
Paragraph (version A):
Some uses of ECH, such as local discovery mode, may randomize the
ECHClientHello.config_id since it can be used as a tracking vector.
In such cases, the second method should be used for matching
ECHClientHello to known ECHConfig.  See optional-configs.  Unless
specified by the application using (D)TLS or externally configured on
both sides, implementations MUST use the first method.
Paragraph (version B):
Some uses of ECH, such as local discovery mode, may randomize the
ECHClientHello.config_id since it can be used as a tracking vector.
In such cases, the second method should be used for matching the
ECHClientHello to a known ECHConfig.  See optional-configs.  Unless
specified by the application using (D)TLS or externally configured on
both sides, implementations MUST use the first method.
Draft: draft-ietf-tls-esni

Commentary: Missing Punctuation At section 8 . Compatibility Issues 
 Thanks !
Paragraph (version B):
Unlike most TLS extensions, placing the SNI value in an ECH extension
is not interoperable with existing servers, which expect the value in
the existing plaintext extension.  Thus server operators SHOULD
ensure servers understand a given set of ECH keys before advertising
them.  Additionally, servers SHOULD retain support for any
previously-advertised keys for the duration of their validity.
Draft: draft-ietf-tls-esni

Commentary: Just some minor nits I picked up during a slow pass of the spec . 
 LGTM pending one nit .
Paragraph (version A):
The HPKE encapsulated key, used by servers to decrypt the
corresponding "payload" field.  This field is empty in
ClientHelloOuters sent in response to HelloRetryRequest.
Paragraph (version B):
The HPKE encapsulated key, used by servers to decrypt the
corresponding "payload" field.  This field is empty in a
ClientHelloOuter sent in response to HelloRetryRequest.
Paragraph (version A):
The client generates the extension payload by constructing an
"OfferedPsks" structure (see RFC8446, Section 4.2.11) as follows.
For each PSK identity advertised in the ClientHelloInner, the client
generates a random PSK identity with the same length.  It also
generates a random, 32-bit, unsigned integer to use as the
"obfuscated_ticket_age".  Likewise, for each inner PSK binder, the
client generates random string of the same length.
Paragraph (version A):
If the server replies with a "pre_shared_key" extension in its
ServerHello, then the client MUST abort the handshake with an
"illegal_parameter" alert.
Paragraph (version B):
The client generates the extension payload by constructing an
"OfferedPsks" structure (see RFC8446, Section 4.2.11) as follows.
For each PSK identity advertised in the ClientHelloInner, the client
generates a random PSK identity with the same length.  It also
generates a random, 32-bit, unsigned integer to use as the
"obfuscated_ticket_age".  Likewise, for each inner PSK binder, the
client generates a random string of the same length.
Paragraph (version B):
Per the rules of real-ech, the server is not permitted to resume a
connection in the outer handshake.  If ECH is rejected and the
client-facing server replies with a "pre_shared_key" extension in its
ServerHello, then the client MUST abort the handshake with an
"illegal_parameter" alert.
Draft: draft-ietf-tls-esni

Commentary: There are two reasons for this . First , the algorithm in Appendix B for decoding the EncodedClientHelloInner does n't actually enforce this . Second , aborting on duplicated extensions is slightly stricter than RFC 8446 requires . It states that " [ t]here MUST NOT be more than one extension of the same type in a given extension block " , but does n't specify what the receiver does in this case .
Paragraph (version A):
OuterExtensions contains duplicate values.
Draft: draft-ietf-tls-esni

Commentary: The requirement to check the ClientHello for an inner ClientECH does n't make sense because the entire section is already conditioned by observing an inner ClientECH . Also clarify that the client - facing vs. backend server dispatch happens at the initial ClientHello . Switching roles mid - connection will not work very well .
Paragraph (version A):
As above, the payload of "encrypted_client_hello" is expected to be a
"ClientECH" with "ClientECH.type" is "inner".  If this is not the
case, the backend server MUST abort the handshake with an
"illegal_parameter" alert.
Paragraph (version A):
Note that, in case of HelloRetryRequest, the backend server confirms
ECH acceptance twice: first In HelloRetryRequest, as described here;
and then in the subsequent ServerHello, as described above.
Paragraph (version B):
In the subsequent ServerHello message, the backend server sends the
accept_confirmation value as described in backend-server.
Draft: draft-ietf-tls-esni

Commentary: To be included with . Note that this is a wire - breaking change that should have landed in draft-11 , but did n't . 
 since this will go into the next version of the draft , can we bump everything to the next version here ? 
 Done . 
 Thanks ! 
 ECHConfig is defined as The intention was to bump ECHConfig.version from 0xfe0a to 0xfe0b for draft-11 , but this got missed by ( I wrote the PR , so I apologize for my part in missing this . ) How do folks think we should resolve this ? Do we need to cut a new draft with the ambiguity fixed ? 
 Oh whoops , nice catch ! Using definitely wo n't work since the format and corresponding ClientECH extension has changed . I suppose all the implementors could just agree to mentally fix this typo when reading the draft , but may as well cut draft-12 . Draft numbers are cheap . 
 We could try to pick up some editorial changes , too , like those suggested in . 
 I 'd also personally be pretty happy to have in there , but also fine to skip it for what 's supposed to be a small bugfix draft snapshot . 
 +1 I 've not checked recent editorial changes but they 're probably fine too . S 
 I 'd be happy to take in draft-12 as well , though I 'm inclined to think this should strictly be a bugfix / editorial draft . I 'd say let 's wait until   gets off back from PTO and let him make the call . Unless we 're in a hurry , in which case we could ping one of the other authors to merge our changes and cut a draft . 
 Closing as resolved .
Paragraph (version A):
encrypted_client_hello(0xfe0b), with "TLS 1.3" column values set
to "CH, HRR, EE", and "Recommended" column set to "Yes".
Paragraph (version B):
encrypted_client_hello(0xfe0c), with "TLS 1.3" column values set
to "CH, HRR, EE", and "Recommended" column set to "Yes".