[noise] Document structure (was: Mechanical definition of "fallback" modifier)

[Trevor Perrin]

Reviving this thread:

The need to rethink our document structure is becoming pressing,
particularly because David, Rhys, Alexey are writing extensions and we
don't have good processes for that.

Jake, Rhys, and Alexey have spoken in favor of refactoring the current
Noise spec into a minimalist "core" with PSK, resumption, and crypto
algorithms moved into separate "extensions".  Jake explains this well:


On Mon, Jun 12, 2017 at 8:15 AM, Jake McGinty <me at jake.su> wrote:
> A specification structure proposal I’ve had floating around in my head for a bit:
>
> 1) Core
>
> Definitions of the handshake and transport state machines (sections 1-8 in the current rev32 spec).
>
> 2) Appendices
>
> Overview of security properties of the various handshake options (sections 7.4 and 7.5), as they’re convenient information but not a necessary part of a specification since it can be generated from the core spec.
>
> 3) Extensions
>
> Currently this would be one document for each of {pskN, fallback, HFS, NewHope}, and perhaps we could have a standardized set of sections for extension papers so the documents don’t look totally different from each other.
>
> -----
>
> To address Alex’s concern (which I share) about well-defined compliance, Noise implementations should consider the core spec to be the minimum requirement, and would simply include a list of which extensions are also supported.


An alternative to the "minimalist core" would be a "tied-off core"
where we finalize the Noise spec with its current feature set, and add
new features via new extensions documents.

A third alternative is an "expanding core" where we keep adding things
into the main spec.

There's a lot to consider:

MINIMALIST CORE: Conceptually the cleanest, but it means more
different documents, and we're no longer using the core spec to
indicate the recommended feature set and crypto functions for
libraries.  I think Jake, Rhys, and Alexey like this, and Jason
doesn't.

TIED-OFF CORE: This is probably the road we are starting down by
default, since people are writing extensions and I'd like to stop
adding onto the core.  This leaves open the question of what the
extension documents add up to, e.g. do we eventually do a revised or
new core document to include important extensions?

EXPANDING CORE: This is the simplest in a sense, since Noise would
always be defined by a single doc.  However this makes it hard to
indicate that features are at different maturity levels, and hard for
others to contribute since my editing of the spec is a bottleneck.


I might be leaning towards a "tied-off core".  It's messier than the
"minimalist" approach, but I worry that a major document refactoring
could be confusing and disruptive (e.g. for downstream implementers
who might be uncertain about how to refer to the parts of Noise they
use).

But I'm really not sure, and would like to hear more thoughts!


Trevor