search

cfrg / draft-irtf-cfrg-cpace

Other
2 stars 4 forks source link

Reorder sections #7

Closed bytemare closed 1 year ago

bytemare commented 2 years ago

As discussed offline with Björn, I have some editorial suggestions which, I think, could add some clarity to the document. I'll add issues with each PR to track suggestions and discuss them.

My first suggestion is to rethink a bit the section layout. Currently, there's a mix between notation, setup, protocol execution, etc.

I suggest the following layout for the first sections

  1. Notation
  2. Cryptographic Dependencies
  3. The CPACE Protocol 3.1 Protocol flow 3.2 Setup 3.3 Inputs 3.3.1 Session identifier establishment 3.4 Online Key Exchange

N.b. that I may be biaised by the redaction of the OPAQUE spec.

juhesse commented 2 years ago

Daniel, thank you very much for reviewing the draft, and for your suggestions. We are currently waiting for additional reviews, and then we will resolve all open issues and incorporate comments with the next version of the draft. Again, thanks a lot for the very useful input. Best regards, Julia

BjoernMHaase commented 2 years ago

Daniel,

regarding possible double work. I think that it might be worth waiting for the other reviews before suggesting changes in form of a PR. Thank's for your review also from my side.

BjoernMHaase commented 2 years ago

Before starting a restructuring, we might best get a common agreement on the target-audience for the document and how to priorize the respective needs of the different "personas".

For Issue #8 I have added a suggestion on a definition of the different personas that might be relevant. https://github.com/cfrg/draft-irtf-cfrg-cpace/issues/8.

My suggestion would be to focus on the respective needs of "Archibald", "Cody" and "Veronica" and have corresponding main subsections in the I-D which should be possibly rather self-contained.? I.e. I would be willing to accept that we have some level of redundancy that avoids that "Cody" and "Veronica" will have to jump back and forth reading sections not primarily meant for them in order to find the information that is relevant for her.

BjoernMHaase commented 1 year ago

We have reworked the layout of the sections with a clear focus on implementers and testers of the protocol.

BjoernMHaase commented 1 year ago

I think that we addressed this issue in the last major rewrite.