Draft structure/Editorial Changes

[franziskuskiefer]

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] https://mailarchive.ietf.org/arch/msg/mls/ZOy80Yp5bRhoM8fsQMGVwmFFEzY/

[beurdouche]

If we want an implementation document, which is a legitimate ask, we should write an implementation document.

[franziskuskiefer]

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.

[beurdouche]

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 node_encap/node_decap functions which are required to generate a correct payload and a standard way to serialize abstract structures... etc.

[franziskuskiefer]

Specifying a functional behavior and providing a guide for implementation are two very different things.

Right, the document is doing neither right now.

[bifurcation]

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 #520. 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 # Ratchet Trees to after # Cryptographic Objects and # Key Packages
• For subsections:
  • Move the tree-relevant subsections of # Key Packages into # Ratchet Trees — including ## Parent Hash, ## Tree Hashes, and ## Update Paths
  • Split ## Group State into two:
    • Put the GroupContext definition part in a new subsection ## Group Context under # Cryptographic Objects
    • Put the transcript updating part in a new subsection ## Updating the Transcript under # Key Schedule

[rohan-wire]

I have an alternative organization of the first sections:

• Add the one sentence definition of node before the last paragraph of ##Tree Computation Terminology
• Swap ##Ratchet Tree Nodes and ##Views of a Ratchet Tree

This seems to all flow nicely with very few forward references.

A more radical rewrite might

• Move #Group Evolution forward before #Cryptographic Objects but I don't think that is necessary.

I do like Richard's proposal to split ## Group State

[bifurcation]

I'm considering this fixed after the series of reorg PRs that @rohan-wire @Bren2010 and I just finished.

565 #566 #567 #568 #569 #570 #571