jiebi/ids-paragraph-commentary-corpus huggingface dataset:
Draft: draft-ietf-mls-protocol

Commentary: This PR adds clarification around X509 cert structure , the chain and its encoding X509 . 
 thanks for the suggestions . updated PR to reflect the changes . pls let me know .. 
 i have pushed another commit .. can you please check . thanks
Paragraph (version B):
For X509Credential, each entry in the chain represents a single DER-
encoded X509 certificate.  The chain is ordered such that the first
entry (chain[0]) is the end-entity certificate and each subsequent
certificate in the chain MUST be the issuer of the previous
certificate.  The algorithm for the "public_key" in the end-entity
certificate MUST match the relevant ciphersuite.
Draft: draft-ietf-mls-protocol

Commentary: Rotating keys is important and in some cases , Signature Keys are not going to be very " long - term " . Instead they 're going to be rotated periodically . I thus propose we simply remove the assumption that Signature Keys are of a " long - term " nature ( or otherwise " long - lived " ) . The second change in this PR is that I a few words indicating explicitly that the identity must not change when updating a KeyPackage .
Paragraph (version A):
A long-lived signing key pair used to authenticate the sender of a
message.
Paragraph (version B):
A signing key pair used to authenticate the sender of a message.
Paragraph (version A):
A long-term signature key provider which allows clients to
authenticate protocol messages in a group.
Paragraph (version B):
A signature key provider which allows clients to authenticate
protocol messages in a group.
Paragraph (version A):
A KeyPackage object specifies a ciphersuite that the client supports,
as well as providing a public key that others can use for key
agreement.  The client's signature key can be updated throughout the
lifetime of the group by sending a new KeyPackage with a new
signature key; the new signature key MUST be validated by the
authentication service.
Paragraph (version B):
A KeyPackage object specifies a ciphersuite that the client supports,
as well as providing a public key that others can use for key
agreement.  The client's signature key can be updated throughout the
lifetime of the group by sending a new KeyPackage with a new
Credential.  However, the identity MUST be the same in both
Credentials and the new Credential MUST be validated by the
authentication service.
Paragraph (version A):
Note that the long-term signature keys used by the protocol MUST be
distributed by an "honest" authentication service for clients to
authenticate their legitimate peers.
Paragraph (version B):
Note that the signature keys used by the protocol MUST be distributed
by an "honest" authentication service for clients to authenticate
their legitimate peers.
Draft: draft-ietf-mls-protocol

Commentary: that MLSPlaintext does not currently authenticate the sender 's membership on the group , and as a result , some important attacks arise . Discussion on the list indicated that adding a MAC with a key derived from the key schedule would provide this authentication . This PR implements that suggestion . 
 Lgtm . Rebase and I 'll properly approve . 
 Generally not a fan of rebasing , but here you go . 
 From ... This would be a useful terminology to describe a client which shares its cryptographic material across multiple device . To be discussed ? 
 Done in draft-06
Paragraph (version A):
The "signature" field in an MLSPlaintext object is computed using the
signing private key corresponding to the credential at the leaf in
the tree indicated by the sender field.  The signature covers the
plaintext metadata and message content, which is all of MLSPlaintext
except for the "signature" field.  The signature also covers the
GroupContext for the current epoch, so that signatures are specific
to a given group and epoch.
Paragraph (version B):
The "signature" field in an MLSPlaintext object authenticates the
sender of the MLSPlaintext message.  The input to the signature is an
MLSPlaintextTBS structure, which encodes the content and metadata of
the message as well a context for the signature that associates to
the group messages sent within the group.
Paragraph (version B):
In cases where the sender is a member of the group, the context
contains the GroupContext for the current epoch and a "membership
tag" that authenticates that the sender is a member of the group.  As
a result, for messages sent within a group, the signature
authenticates the member's individual identity, and the membersip tag
authenticates their membership in the group.
Paragraph (version B):
When the sender type is "member", the "membership_tag" field MUST
contain a full-size MAC output, and MUST be verified before verifying
the signature or processing the message content.  For other sender
types, the "membership_tag" field MUST be set to the zero-length
octet string.
Paragraph (version B):
Note that the "membership_tag" is not carried forward from
MLSPlaintext to MLSCiphertext.  In the context of an MLSCiphertext,
the AEAD authentication provides the function that the
"membership_tag" provides for MLSPlaintext.
Draft: draft-ietf-mls-protocol

Commentary: As discussed on this removes the paragraph in the Group Creation section specifying that joiners SHOULD verify group creation if it is detected . A recent change to group creation - namely a random initial - makes it impossible to verify group creation .
Paragraph (version A):
A new member receiving a Welcome message can recognize group creation
if the number of entries in the "members" array is equal to the
number of leaves in the tree minus one.  A client receiving a Welcome
message SHOULD verify whether it is a newly created group, and if so,
SHOULD verify that the above process was followed by reconstructing
the Add and Commit messages and verifying that the resulting
transcript hashes and epoch secret match those found in the Welcome
message.
Draft: draft-ietf-mls-protocol

Commentary: This PR gets rid of the explicit HMAC reference and uses KDF.Extract instead ( which internally uses HMAC ) . Also is renamed to . 
 I do n't love the extra , but I can live with it .
Paragraph (version A):
Thus the "confirmed_transcript_hash" field in a GroupContext object
represents a transcript over the whole history of MLSPlaintext Commit
messages, up to the confirmation field in the current MLSPlaintext
message.  The confirmation and signature fields are then included in
the transcript for the next epoch.  The interim transcript hash is
passed to new members in the GroupInfo struct, and enables existing
members to incorporate a Commit message into the transcript without
having to store the whole MLSPlaintextCommitAuthData structure.
Paragraph (version B):
Thus the "confirmed_transcript_hash" field in a GroupContext object
represents a transcript over the whole history of MLSPlaintext Commit
messages, up to the confirmation tag field in the current
MLSPlaintext message.  The confirmation tag and signature fields are
then included in the transcript for the next epoch.  The interim
transcript hash is passed to new members in the GroupInfo struct, and
enables existing members to incorporate a Commit message into the
transcript without having to store the whole
MLSPlaintextCommitAuthData structure.
Paragraph (version A):
Construct an MLSPlaintext object containing the Commit object.
Use the "commit_secret" to advance the key schedule and compute
the "confirmation" value in the MLSPlaintext.  Sign the
MLSPlaintext using the current epoch's GroupContext as context.
Paragraph (version B):
Construct an MLSPlaintext object containing the Commit object.
Use the "commit_secret" to advance the key schedule and compute
the "confirmation_tag" value in the MLSPlaintext.  Sign the
MLSPlaintext using the current epoch's GroupContext as context.
Paragraph (version A):
Use the "confirmation_key" for the new epoch to compute the
confirmation MAC for this message, as described below, and verify
that it is the same as the "confirmation" field in the
MLSPlaintext object.
Paragraph (version A):
HMAC RFC2104 uses the Hash algorithm for the ciphersuite in use.
Paragraph (version B):
Use the "confirmation_key" for the new epoch to compute the
confirmation tag for this message, as described below, and verify
that it is the same as the "confirmation_tag" field in the
MLSPlaintext object.
Paragraph (version A):
Verify the confirmation MAC in the GroupInfo using the derived
confirmation key and the "confirmed_transcript_hash" from the
GroupInfo.
Paragraph (version B):
Verify the confirmation tag in the GroupInfo using the derived
confirmation key and the "confirmed_transcript_hash" from the
GroupInfo.
Draft: draft-ietf-mls-protocol

Commentary: This is a simple rename of to to be more descriptive of the action being performed by the message . I 'll open a separate PR after this PIR is merged with updates to the spec where it uses when instead it should say ( since not every actually ratchets forward key material , as I understand ) . Some examples of where these clarifications should happen are : Line 1203 should instead say " each MLS UpdatePath message " The sections " Ratchet Tree Evolution " and " Sychronizing Views of the Tree " should describe the process of generating the key material for an message cc 
 DirectPath corresponds to the graph theory term " direct path " of a leaf with the root 
 " Direct path " is still a thing , and the object in question here operates along a direct path , but I think " UpdatePath " indicates more clearly what it 's doing .
Paragraph (version A):
If populating the "path" field: Create a DirectPath using the new
tree (which includes any new members).  The GroupContext for this
operation uses the "group_id", "epoch", "tree_hash", and
"confirmed_transcript_hash" values in the initial GroupContext
object.
Paragraph (version A):
Assign this DirectPath to the "path" field in the Commit.
Paragraph (version A):
Apply the DirectPath to the tree, as described in
synchronizing-views-of-the-tree.  Define "commit_secret" as the
value "path_secret[n+1]" derived from the "path_secret[n]"
value assigned to the root node.
Paragraph (version B):
If populating the "path" field: Create a UpdatePath using the new
tree (which includes any new members).  The GroupContext for this
operation uses the "group_id", "epoch", "tree_hash", and
"confirmed_transcript_hash" values in the initial GroupContext
object.
Paragraph (version B):
Assign this UpdatePath to the "path" field in the Commit.
Paragraph (version B):
Apply the UpdatePath to the tree, as described in
synchronizing-views-of-the-tree.  Define "commit_secret" as the
value "path_secret[n+1]" derived from the "path_secret[n]"
value assigned to the root node.
Paragraph (version A):
Apply the DirectPath to the tree, as described in
synchronizing-views-of-the-tree, and store "key_package" at the
Committer's leaf.
Paragraph (version B):
Apply the UpdatePath to the tree, as described in
synchronizing-views-of-the-tree, and store "key_package" at the
Committer's leaf.
Draft: draft-ietf-mls-protocol

Commentary: Addresses ambiguity pointed out on the mailing list by 
 In , we changed from using HKDF to using the KDF from HPKE , which I thought removed the need for the ciphersuite to specify a hash function . As a result , ciphersuites no longer needed to specify a hash . However , the transcript computations still have a raw invocation , not a KDF invocation . So we need to either : the transcript hash computations to use the KDF , or that ciphersuites still specify a hash function ( as before ) 
 What about the call in the and the " hashes " for ?
Paragraph (version A):
When a new group is created, the "interim_transcript_hash" field is
set to the zero-length octet string.
Paragraph (version B):
As shown above, when a new group is created, the
"interim_transcript_hash" field is set to the zero-length octet
string.
Paragraph (version B):
The hash used for the MLS transcript hash is the one referenced in
the ciphersuite name.  In the ciphersuites defined above, "SHA256"
and "SHA512" refer to the SHA-256 and SHA-512 functions defined in
SHS.
Draft: draft-ietf-mls-protocol

Commentary: A couple of minor editorial changes to the current draft , namely : < details < summaryThere was a missing grave accent in one of the paragraphs of < a href=""the Commit section</acausing some formatting issues</summaryBefore : ! After : ! < /details < details < summaryFix typo Pre - Shared Keys section</summary [ ... ] , it does not necessarily provide the same [ ... ] guarantees ~than~ as a Commit message . < /details < details < summaryResolve remaining reference to < codepriorepoch</code</summaryIn the Sequencing section there was a reference to a field that was introduced in . However , in , it was removed from the struct where it was . That entire struct was then removed in , after which the trail runs cold . So I was n't able to figure out exactly what it must be based on what on what it originally was . Hence , I replaced it with something that makes sense in context . I based the new text on the following line found in the < a href=""(current ) Commit section</a : < /details < details < summaryRewrite paragraph on the < codenew_member</codeSenderType</summaryI found the phrase " In such cases " after the sentence " Proposals with types other than Add MUST NOT be sent with this sender type " slightly confusing and awkward . To improve this I rewrote the paragraph . < /details 
 Couple of nits on your nits
Paragraph (version A):
Note that, as a PSK may have a different lifetime than an update, it
does not necessarily provide the same Forward Secrecy (FS) or Post-
Compromise Security (PCS) guarantees than a Commit message.
Paragraph (version B):
Note that, as a PSK may have a different lifetime than an update, it
does not necessarily provide the same Forward Secrecy (FS) or Post-
Compromise Security (PCS) guarantees as a Commit message.
Paragraph (version A):
The "new_member" SenderType is used for clients proposing that they
themselves be added.  For this ID type the sender value MUST be zero.
Proposals with types other than Add MUST NOT be sent with this sender
type.  In such cases, the MLSPlaintext MUST be signed with the
private key corresponding to the KeyPackage in the Add message.
Recipients MUST verify that the MLSPlaintext carrying the Proposal
message is validly signed with this key.
Paragraph (version B):
The "new_member" SenderType is used for clients proposing that they
themselves be added.  For this ID type the sender value MUST be zero
and the Proposal type MUST be Add. The MLSPlaintext MUST be signed
with the private key corresponding to the KeyPackage in the Add
message.  Recipients MUST verify that the MLSPlaintext carrying the
Proposal message is validly signed with this key.
Paragraph (version A):
Each Commit message is premised on a given starting state, indicated
in its "prior_epoch" field.  If the changes implied by a Commit
messages are made starting from a different state, the results will
be incorrect.
Paragraph (version B):
Each Commit message is premised on a given starting state, indicated
by the "epoch" field of the enclosing MLSPlaintext message.  If the
changes implied by a Commit messages are made starting from a
different state, the results will be incorrect.
Draft: draft-ietf-mls-protocol

Commentary: This PR adds a fix mentioned in but was not included in the PR that was eventually merged . Specifically , both public and encrypted private values are sent in a message containing key material to ratchet the tree forward .
Paragraph (version A):
After generating a Commit as described in the prior section, the
generator of the Commit must broadcast this update to other members
of the group, who apply it to keep their local views of the tree in
sync with the sender's.  When a client commits a change to the tree
(e.g., to add or remove a member), it transmits a handshake message
containing a set of public values for intermediate nodes in the
direct path of a leaf.  The other members of the group can use these
public values to update their view of the tree, aligning their copy
of the tree to the sender's.
Paragraph (version B):
After generating a Commit as described in the prior section, the
generator of the Commit must broadcast this update to other members
of the group, who apply it to keep their local views of the tree in
sync with the sender's.  When a client commits a change to the tree
(e.g., to add or remove a member), it transmits a handshake message
containing a set of public and encrypted private values for
intermediate nodes in the direct path of a leaf.  The other members
of the group can use these values to update their view of the tree,
aligning their copy of the tree to the sender's.
Draft: draft-ietf-mls-protocol

Commentary: cc./ it should be better now . 
 Thanks both ! :)
Paragraph (version A):
Fetch KeyPackages for the members to be added, and selects a
version and ciphersuite according to the capabilities of the
members.  To protect against downgrade attacks, the creator MUST
use the "capabilities" extensions in these KeyPackages to verify
that the chosen version and ciphersuite is the best option
supported by all members.
Paragraph (version B):
Fetch KeyPackages for the members to be added, and select a
version and ciphersuite according to the capabilities of the
members.  To protect against downgrade attacks, the creator MUST
use the "capabilities" extensions in these KeyPackages to verify
that the chosen version and ciphersuite is the best option
supported by all members.
Paragraph (version A):
In the case where the client could have been compromised (device
loss...), the client SHOULD signal the delivery service to expire all
the previous KeyPackages and publish fresh ones for PCS.
Paragraph (version B):
In the case where the client could have been compromised (device
loss, for example), the client SHOULD signal the delivery service to
expire all the previous KeyPackages and publish fresh ones for PCS.
Draft: draft-ietf-mls-protocol

Commentary: This PR tries to clarify these paragraphs by the following : Differentiating between HPKE public / private keys when describing how these keys are rotated for a commit Clarifying who does the actions associated with a commit Adding consistency fixes between the two paragraphs Let me know if these fixes are not quite right , as this PR tries to clarify where I had questions when reading .
Paragraph (version A):
When performing a Commit, the leaf KeyPackage of the committer and
its direct path to the root are updated with new secret values.  The
HPKE leaf public key within the KeyPackage MUST be a freshly
generated value to provide post-compromise security.
Paragraph (version A):
The generator of the Commit starts by using the HPKE secret key
"leaf_hpke_secret" associated with the new leaf KeyPackage (see key-
packages) to compute "path_secret[0]" and generate a sequence of
"path secrets", one for each ancestor of its leaf.  That is,
path_secret[0] is used for the node directly above the leaf,
path_secret[1] for its parent, and so on.  At each step, the path
secret is used to derive a new secret value for the corresponding
node, from which the node's key pair is derived.
Paragraph (version B):
When performing a Commit, the generator of the Commit updates its
leaf KeyPackage and its direct path to the root with new secret
values.  The HPKE leaf public key within the KeyPackage MUST be
derived from a freshly generated HPKE secret key to provide post-
compromise security.
Paragraph (version B):
The generator of the Commit starts by sampling a fresh random value
called "leaf_secret", and uses the leaf_secret to generate their leaf
HPKE key pair (see key-packages) and to seed a sequence of "path
secrets", one for each ancestor of its leaf.  In this setting,
path_secret[0] refers to the node directly above the leaf,
path_secret[1] for its parent, and so on.  At each step, the path
secret is used to derive a new secret value for the corresponding
node, from which the node's key pair is derived.
Paragraph (version B):
After performing these operations, the generator of the Commit MUST
delete the leaf_secret.
Draft: draft-ietf-mls-protocol

Commentary: This PR defines and links to the HPKE draft when first introducing this term in the draft .
Paragraph (version A):
A signed object describing a client's identity and capabilities,
and including an HPKE public key that can be used to encrypt to
that client.
Paragraph (version B):
A signed object describing a client's identity and capabilities,
and including a hybrid public-key encryption (HPKE I-D.irtf-cfrg-
hpke ) public key that can be used to encrypt to that client.
Draft: draft-ietf-mls-protocol

Commentary: This PR makes a few minor fixes to extensions : Coalesces and into a single extension Adds a list of supported extensions in parallel with the versions and ciphersuites Adds a missing value to the IANA table for the extension
Paragraph (version A):
KeyPackage objects MUST contain at least three extensions, one of
type "supported_versions", one of type "supported_ciphersuites", and
one of type "lifetime".  The "supported_versions" and
"supported_ciphersuites" extensions allow MLS session establishment
to be safe from downgrade attacks on these two parameters (as
discussed in group-creation), while still only advertising one
version / ciphersuite per KeyPackage.
Paragraph (version B):
KeyPackage objects MUST contain at least two extensions, one of type
"capabilities", and one of type "lifetime".  The "capabilities"
extension allow MLS session establishment to be safe from downgrade
attacks on the parameters described (as discussed in group-creation),
while still only advertising one version / ciphersuite per
KeyPackage.
Paragraph (version A):
The "supported_versions" extension contains a list of MLS versions
that are supported by the client.  The "supported_ciphersuites"
extension contains a list of MLS ciphersuites that are supported by
the client.
Paragraph (version A):
These extensions MUST be always present in a KeyPackage.
Paragraph (version B):
The "capabilities" extension indicates what protocol versions,
ciphersuites, and protocol extensions are supported by a client.
Paragraph (version B):
This extension MUST be always present in a KeyPackage.  Extensions
that appear in the "extensions" field of a KeyPackage MUST be
included in the "extensions" field of the "capabilities" extension.
Paragraph (version A):
Fetch KeyPackages for the members to be added, and selects a
version and ciphersuite according to the capabilities of the
members.  To protect against downgrade attacks, the creator MUST
use the "supported_versions" and "supported_ciphersuites" fields
in these KeyPackages to verify that the chosen version and
ciphersuite is the best option supported by all members.
Paragraph (version B):
Fetch KeyPackages for the members to be added, and selects a
version and ciphersuite according to the capabilities of the
members.  To protect against downgrade attacks, the creator MUST
use the "capabilities" extensions in these KeyPackages to verify
that the chosen version and ciphersuite is the best option
supported by all members.