Original text:
state with other clients.  A client is defined by the cryptographic keys it holds. <del> A collection of clients with shared cryptographic state. </del>  A client that is included in the shared state of a group, hence has access to the group's secrets. A signing key pair used to authenticate the sender of a message.  Terminology specific to tree computations is described in ratchet- trees. 3. <del> This protocol is designed to execute in the context of a Service Provider (SP) as described in I-D.ietf-mls-architecture.  In particular, we assume the SP provides the following services: </del>  <del> A signature key provider which allows clients to authenticate protocol messages in a group. </del>  <del> A broadcast channel, for each group, which will relay a message to all members of a group.  For the most part, we assume that this channel delivers messages in the same order to all participants. (See sequencing for further considerations.) </del>  <del> A directory to which clients can publish key packages and download key packages for other participants. </del>  4. <del> The goal of this protocol is to allow a group of clients to exchange confidential and authenticated messages.  It does so by deriving a sequence of secrets and keys known only to members.  Those should be secret against an active network adversary and should have both forward secrecy and post-compromise security with respect to compromise of any members. We describe the information stored by each client as _state_, which includes both public and private data.  An initial state is set up by a group creator, which is a group containing only itself.  The creator then sends _Add_ proposals for each client in the initial set of members, followed by a _Commit_ message which incorporates all of the _Adds_ into the group state.  Finally, the group creator generates a _Welcome_ message corresponding to the Commit and sends this directly to all the new members, who can use the information it contains to set up their own group state and derive a shared secret. Members exchange Commit messages for post-compromise security, to add new members, and to remove existing members.  These messages produce new shared secrets which are causally linked to their predecessors, forming a logical Directed Acyclic Graph (DAG) of states. The protocol algorithms we specify here follow.  Each algorithm specifies both (i) how a client performs the operation and (ii) how other clients update their state based on it. </del>  There are three major operations in the lifecycle of a group: the group with fresh entropy.  In this section, we show each proposal being committed immediately, but in more advanced deployment cases an application might gather several proposals before committing them all <del> at once. </del>  Before the initialization of a group, clients publish InitKeys (as KeyPackage objects) to a directory provided by the Service Provider. Subsequent additions of group members proceed in the same way.  Any member of the group can download a KeyPackage for a new client and <del> broadcast an Add message that the current group can use to update their state, and a Welcome message that the new client can use to initialize its state and join the group. </del>  To enforce the forward secrecy and post-compromise security of <del> messages, each member periodically updates their leaf secret.  Any member can update this information at any time by generating a fresh KeyPackage and sending an Update message followed by a Commit message.  Once all members have processed both, the group's secrets will be unknown to an attacker that had compromised the sender's prior leaf secret. </del>  Update messages should be sent at regular intervals of time as long as the group is active, and members that don't update should to determine an appropriate amount of time between Updates. Members are removed from the group in a similar way.  Any member of <del> the group can send a Remove proposal followed by a Commit message, which adds new entropy to the group state that's known to all except the removed member.  Note that this does not necessarily imply that any member is actually allowed to evict other members; groups can enforce access control policies on top of these basic mechanism. </del>  5.

Reviewer comments:
First part of fixing
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.
some comments on the overview section from a beginner's point of view. 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:
state with other clients.  A client is defined by the cryptographic keys it holds.  <ins> A linear sequence of epochs in which each epoch depends on its predecessor. A state of a group in which a specific set of authenticated clients hold shared cryptographic state. </ins> A client that is included in the shared state of a group, hence has access to the group's secrets. A signing key pair used to authenticate the sender of a message. <ins> An MLSPlaintext or MLSCiphertext message carrying an MLS Proposal or Commit object, as opposed to application data. An MLSCiphertext message carrying application data. </ins> Terminology specific to tree computations is described in ratchet- trees. 3.  <ins> MLS is designed to operate in the context described in I-D.ietf-mls- architecture.  In particular, we assume that the following services are provided: A Delivery Service that routes MLS messages among the participants in the protocol.  The following types of delivery are typically required: Pre-publication of KeyPackage objects for clients </ins>  <ins> Broadcast delivery of Proposal and Commit messages to members of a group </ins>  <ins> Unicast delivery of Welcome messages to new members of a group </ins>  <ins> An Authentication Service that enables group members to authenticate the credentials presented by other group members. </ins> 4.  <ins> The core functionality of MLS is continuous group authenticated key exchange (AKE).  As with other authenticated key exchange protocols (such as TLS), the participants in the protocol agree on a common secret value, and each participant can verify the identity of the other participants.  MLS provides group AKE in the sense that there can be more than two participants in the protocol, and continuous group AKE in the sense that the set of participants in the protocol can change over time. The core organizing principles of MLS are _groups_ and _epochs_.  A group represents a logical collection of clents that share a common secret value at any given time.  The history of a group is divided into a linear sequence of epochs.  In each epoch, a set of authenticated _members_ agree on an _epoch secret_ that is known only to the members of the group in that epoch.  The set of members involved in the group can change from one epoch to the next, and MLS assures that only the members in the current epoch have access to the epoch secret.  From the epoch secret, members derive further shared secrets for message encryption, group membership authentication, etc. The creator of an MLS group creates the group's first epoch unilaterally, with no protocol interactions.  Thereafter, the members of the group advance their shared cryptographic state from one epoch to another by exchanging MLS messages: A _KeyPackage_ object describes a client's capabilities and provides keys that can be used to add the client to a group. A _Proposal_ message proposes a change to be made in the next epoch, such as adding or removing a member A _Commit_ message initiates a new epoch by instructing members of the group to implement a collection of proposals A _Welcome_ message provides a new member to the group with the information to initialize their state for the epoch in which they were added A _PublicGroupState_ object provides potential new group members with information about the state of a group at an epoch, to allow a new member to add themselves to the group. KeyPackage, Welcome, and PublicGroupState messages are used to initiate a group or introduce new members, so they are exchanged between group members and clients not yet in the group. Proposal and Commit messages are sent from one member of a group to the others.  MLS provides a common framing layer for sending messages within a group, including Proposal and Commit as well as application data.  An _MLSPlaintext_ message provides sender authentication for unencrypted Proposal and Commit messages.  An _MLSCiphertext_ message provides encryption and authentication for both Proposal/Commit message and application data. 4.1. There are two types of cryptographic state at the core of MLS: A _key schedule_ that represents the shared secret state of the group and its evolution from one epoch to the next. A _ratchet tree_ that represents the membership of the group, providing group members a way to authenticate each other and efficiently encrypt messages to subsets of the group.  Each epoch has a distinct ratchet tree. Each member of the group maintains a view of these two facets of the group's state.  MLS messages are used to intialize these views and keep them in sync as the group transitions between epochs. Each new epoch is initiated with a Commit message.  The Commit instructs existing members of the group to update their views of ratchet tree by applying a set of Proposals, and uses the updated ratchet tree to distribute fresh entropy to the group.  This fresh entropy is provided only to members in the new epoch, not to members who have been removed, so it maintains the confidentiality of the epoch secret (in other words, it provides post-compromise security with respect to those members). For each Commit that adds member(s) to the group, there is a corresponding Welcome message.  The Welcome message provides new members with the information they need to initialize their views of the key schedule and ratchet tree, so that these views are equivalent to the views held by other members of the group in this epoch. In addition to defining how one epoch secret leads to the next, the key schedule also defines a collection of secrets that are derived from the epoch secret.  For example: An _encryption secret_ that is used to initialize a _secret tree_, which provides keys for encrypting handshake and application messages and providing forward secrecy for these messages within an epoch. A _confirmation key_ that is used to confirm that all members agree on the shared state of the group. A _resumption secret_ that members can use to prove their membership in the group, e.g., in the case of branching a subgroup. Finally, an _init secret_ is derived that is used to initialize the next epoch. 4.2. </ins> There are three major operations in the lifecycle of a group: the group with fresh entropy.  In this section, we show each proposal being committed immediately, but in more advanced deployment cases an application might gather several proposals before committing them all  <ins> at once.  In the illustrations below, we show the Proposal and Commit messages directly, while in reality they would be sent encapsulated in MLSPlaintext or MLSCiphertext objects. </ins> Before the initialization of a group, clients publish InitKeys (as KeyPackage objects) to a directory provided by the Service Provider. Subsequent additions of group members proceed in the same way.  Any member of the group can download a KeyPackage for a new client and  <ins> broadcast Add and Commit message that the current group can use to update their state, and a Welcome message that the new client can use to initialize its state and join the group. </ins> To enforce the forward secrecy and post-compromise security of  <ins> messages, each member periodically updates the keys that represent them to the group.  A member does this by sending a Commit (possibly with no proposals), or by sending an Update message that is committed by another member.  Once the other members of the group have processed these messages, the group's secrets will be unknown to an attacker that had compromised the sender's prior leaf secret. </ins> Update messages should be sent at regular intervals of time as long as the group is active, and members that don't update should to determine an appropriate amount of time between Updates. Members are removed from the group in a similar way.  Any member of  <ins> the group can send a Remove proposal followed by a Commit message. The Commit message provides new entropy to all members of the group except the removed member.  This new entropy is added to the epoch secret for the new epoch, so that it is not known to the removed member.  Note that this does not necessarily imply that any member is actually allowed to evict other members; groups can enforce access control policies on top of these basic mechanism. </ins> 5.