Subject: [COSE] AD review of draft-ietf-cose-rfc8152bis-algs-07

From: Barry Leiba <[email-masked]>
Date: Tue, 12 May 2020 13:06:49 -0400

Here’s my AD review of the 8152bis algorithms document.

— Section 8 —

   There is a presumption in the way that this is laid out is that the
   algorithm identifier itself is not needed to be a part of this as it
   is specified in a different location.

I find that very hard to read.  The passive “there is a presumption”,
the third “is” (I think “is that” is meant to be “in that”), and the
unclear antecedents to “this” and “it” make it unclear.  I would
suggest a rephrasing, but I can’t follow it well enough to do that.
Will you please rephrase it, perhaps starting with “The way
<something> is laid out presumes that the algorithm identifier does
not need to be part of <whatever> because <something clearer than
what’s there>.” ?  Thanks.

   Two different types of capabilities are defined: Capabilities for
   algorithms and capabilities for key structures.

Nit: One capitalizes something after colon only if it’s a complete
sentence, and this isn’t.  So make it a lower-case “c”.

   Once defined by
   registration with IANA, the list capabilities is immutable.

Nit: “list of capabilities”, yes?

   algorithm specific header parameters or key parameters, but they do

Nit: hyphenate “algorithm-specific”.

   For a key, the
   first element should also be a key type value, while this means that
   this value will be duplicated if both an algorithm and key capability
   are used, the key type is needed in order to understand the rest of
   the values.

I think this is two spliced sentences, and that it needs to be split
after “key type value”.

— Section 8.2 —

   the capabilities is set to the single entry of the key type

“capabilities is”?  What’s the correct fix for this?  And what does
“items” refer to in the next sentence?

— Section 8.3 —

   In this section a trio of examples are provided.

He-he… “three examples” is plural, so “are” is correct.  But “a trio
of examples” is singular, so it needs “is”.  Please pick one.

   In all three cases
   the pair of capabilities is always provided as the algorithm and then
   the key capabilities.

That feels awkward and a little confusing.  Maybe this?:

NEW
In each case, the pair of capabilities designates first the algorithm
and then the key capabilities.
END

— Section 9 —

   There has been an attempt to limit the number of places where the
   document needs to impose restrictions on how the CBOR Encoder needs
   to work.

Both instances of “needs to” seem odd.  For that matter, so does
“there has been an attempt”.  Maybe this, or something like it?:

NEW
This document limits the restrictions it imposes on how the CBOR
Encoder can work.
END

— Section 10.2 —

   not done then the DE should be consulted final registration for this
   document is done.

Is this missing the word “before”?  Or “when”?

— Section 10.3 —

   IANA is required to modify the description to "Public Key"

Change “required” to “requested”.

-- 
Barry