Original text:
9.1.  In addition to initializing a new epoch via KDF invocations as described above, an MLS group can also initialize a new epoch via an asymmetric interaction using the external key pair for the previous PublicGroupState for the previous epoch, encoded using the TLS serialization. <del> 9.2. </del>  Groups which already have an out-of-band mechanism to generate shared group secrets can inject those into the MLS key schedule to seed the Commit, then the resulting "psk_secret" is "psk_secret_[0]", the all- zero vector. <del> 9.3. </del>  The main MLS key schedule provides an "exporter_secret" which can be used by an application as the basis to derive new secrets called It is RECOMMENDED for the application generating exported values to refresh those values after a Commit is processed. <del> 9.4. </del>  The main MLS key schedule provides a "resumption_secret" that is used as a PSK to inject entropy from one epoch into another.  This the number of past epochs for which the "resumption_secret" may be stored. <del> 9.5. </del>  The main MLS key schedule provides a per-epoch "authentication_secret".  If one of the parties is being actively applications to add an explicit, application-defined identifier to a KeyPackage. <del> 11.5. Each member of the group maintains a GroupContext object that summarizes the state of the group: The fields in this state have the following semantics: The "group_id" field is an application-defined identifier for the group. The "epoch" field represents the current version of the group key. The "tree_hash" field contains a commitment to the contents of the group's ratchet tree and the credentials for the members of the group, as described in tree-hashes. The "confirmed_transcript_hash" field contains a running hash over the messages that led to this state. The "extensions" field contains the details of any protocol extensions that apply to the group. When a new member is added to the group, an existing member of the group provides the new member with a Welcome message.  The Welcome message provides the information the new member needs to initialize its GroupContext. Different changes to the group will have different effects on the group state.  These effects are described in their respective subsections of proposals.  The following general rules apply: The "group_id" field is constant. The "epoch" field increments by one for each Commit message that is processed. The "tree_hash" is updated to represent the current tree and credentials. The "confirmed_transcript_hash" field is updated with the data for an MLSPlaintext message encoding a Commit message as described below. The "extensions" field changes when a GroupContextExtensions proposal is committed. The "confirmed_transcript_hash" is updated with an MLSPlaintext in two steps: 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 of the most recent Commit. The confirmation tag is then included in the transcript for the next epoch.  The interim transcript hash is computed by new members using the confirmation_tag of the GroupInfo struct, while existing members can compute it directly. As shown above, when a new group is created, the "interim_transcript_hash" field is set to the zero-length octet string. </del> 12. A group is always created with a single member, the "creator".  The

Reviewer comments:
Depends on This PR moves the "Group State" subsection up into the "Key Schedule" section, where it fits more naturally.
This issue accompanies the e-mail [1] pointing out editorial issues with the draft and suggesting improvements. TL;DR: I don't think the draft currently is what is needed to implement MLS. It needs an editorial overhaul with a better structure. [1] URL
If we want an implementation document, which is a legitimate ask, we should write an implementation document.
What's the purpose of the document if not for implementation? In order for this draft to become an RFC it needs implementations. I don't see a way this will happen with the draft as is.
Specifying a functional behavior and providing a guide for implementation are two very different things. Re: what you suggested in your email: Internal representations of the tree, the way you number the indices, how you implement them or the fact that you store some hashes in the nodes are completely irrelevant to this document. Also, there is nothing formal about this appendix. On the other hand the information you need from this document is how to perform computations : things such as providing the arguments to the nodeencap/nodedecap functions which are required to generate a correct payload and a standard way to serialize abstract structures... etc.
Right, the document is doing neither right now.
We have two separable issues here: We need better explanation of the overall structure of the protocol (as in Franziskus' email), and we could rearrange the text to be clearer. For the first, I have filed . That provides a pretty complete overview of the protocol, covering all of the syntax and high-level operations. For the second, we should do a second PR after the other outstanding PRs have landed. Looking at the table of contents, I would propose we refactor in the following way: For top-level sections: Move to after and For subsections: Move the tree-relevant subsections of into — including , , and Split into two: Put the GroupContext definition part in a new subsection under Put the transcript updating part in a new subsection under
I have an alternative organization of the first sections: Add the one sentence definition of before the last paragraph of Swap and This seems to all flow nicely with very few forward references. A more radical rewrite might Move forward before but I don't think that is necessary. I do like Richard's proposal to split
I'm considering this fixed after the series of reorg PRs that NAME NAME and I just finished. Hi all, While trying to implement the MLS protocol from scratch I ran into a couple issues and I think there’s a general problem regarding the structure of the draft. Note that these are all editorial issues. Right now I see no straightforward way to implement the spec as there’s no clear structure. To implement even the basic tree structure it’s necessary to jump through the entire document. There’s also a lot of prose and examples and very little implementable parts. Let me give some examples: Section 5 (Ratchet Trees) reads like a non-normative section (or paper). The really interesting bit related to trees is in Appendix A. I suggest moving the formal description of the tree from Appendix A to this section. It’s impossible to implement this from the hand full examples here. There’s no description in here on how the tree actually works. For example, adding a node to the tree is defined in 10.1.1 (Add). The ratchet tree nodes as described in Section 5 don't hold a KeyPackage. But Section 7 says “As the KeyPackage is a structure which is stored in the Ratchet Tree and updated depending on the evolution of this tree”. The tree nodes have a parent hash field, which is of course part of the ratchet tree but shouldn’t be necessary for the description of the tree structure. Also, the description of the tree hash (Section 7.5) follows the definition of the parenthash extension in Section 7.4 such that it is not entirely clear which parenthash is used there (extension or node value). Section 5 also talks about commit messages without linking to them or introducing them. Having to talk about commit messages in this section is also a little confusing. The term “handshake message” is first used in Section 7.8 (Key Schedule) but never introduced. This should probably happen in 10 (Group Evolution), which doesn’t talk about handshake messages at all until 10.3 (Ratchet Tree Extension). There are probably plenty more issues like this. But I don’t think addressing any of these issues individually makes sense. I therefore suggest having an overhaul of the document structure. The way I see MLS there are a set of high-level structures and components that should be clearly described and built upon each other. There’s a data structure (tree) that is used to represent a group. Then there is the MLS group that implements a specific semantic on the tree. Operations to modify the group are specified in the handshake protocol. And application messages define messages encrypted with keys derived in the handshake protocol with the key schedule. The tree is a basic left-balanced binary tree and defines functions to create a tree, and add and remove nodes. A group is the main part of MLS, a tree with nodes of a certain type. So this part should describe what nodes look like and how the tree is used to compute tree invariants and keys. The handshake protocol defines all messages needed to perform operations on the MLS group. This is certainly not exhaustive and would need further refinement. But it’s the high-level structure I’d expect from the document. I’m sure other structures would work as well. But what we currently have isn’t what is needed to implement MLS imho. Cheers, Franziskus

Revised text:
9.1. <ins> Each member of the group maintains a GroupContext object that summarizes the state of the group: The fields in this state have the following semantics: The "group_id" field is an application-defined identifier for the group. The "epoch" field represents the current version of the group key. The "tree_hash" field contains a commitment to the contents of the group's ratchet tree and the credentials for the members of the group, as described in tree-hashes. The "confirmed_transcript_hash" field contains a running hash over the messages that led to this state. The "extensions" field contains the details of any protocol extensions that apply to the group. When a new member is added to the group, an existing member of the group provides the new member with a Welcome message.  The Welcome message provides the information the new member needs to initialize its GroupContext. Different changes to the group will have different effects on the group state.  These effects are described in their respective subsections of proposals.  The following general rules apply: The "group_id" field is constant. The "epoch" field increments by one for each Commit message that is processed. The "tree_hash" is updated to represent the current tree and credentials. The "confirmed_transcript_hash" field is updated with the data for an MLSPlaintext message encoding a Commit message as described below. The "extensions" field changes when a GroupContextExtensions proposal is committed. The "confirmed_transcript_hash" is updated with an MLSPlaintext in two steps: 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 of the most recent Commit. The confirmation tag is then included in the transcript for the next epoch.  The interim transcript hash is computed by new members using the confirmation_tag of the GroupInfo struct, while existing members can compute it directly. As shown above, when a new group is created, the "interim_transcript_hash" field is set to the zero-length octet string. 9.2. </ins> In addition to initializing a new epoch via KDF invocations as described above, an MLS group can also initialize a new epoch via an asymmetric interaction using the external key pair for the previous PublicGroupState for the previous epoch, encoded using the TLS serialization.  <ins> 9.3. </ins> Groups which already have an out-of-band mechanism to generate shared group secrets can inject those into the MLS key schedule to seed the Commit, then the resulting "psk_secret" is "psk_secret_[0]", the all- zero vector.  <ins> 9.4. </ins> The main MLS key schedule provides an "exporter_secret" which can be used by an application as the basis to derive new secrets called It is RECOMMENDED for the application generating exported values to refresh those values after a Commit is processed.  <ins> 9.5. </ins> The main MLS key schedule provides a "resumption_secret" that is used as a PSK to inject entropy from one epoch into another.  This the number of past epochs for which the "resumption_secret" may be stored.  <ins> 9.6. </ins> The main MLS key schedule provides a per-epoch "authentication_secret".  If one of the parties is being actively applications to add an explicit, application-defined identifier to a KeyPackage.  12. A group is always created with a single member, the "creator".  The