Subject: [Cbor] Secdir last call review of draft-ietf-cbor-file-magic-11

From: Christopher Wood via Datatracker <[email-masked]>
Date: Fri, 15 Apr 2022 10:36:52 -0700

Reviewer: Christopher Wood
Review result: Has Nits

Section 2.1:

   The use of a sequence of four US-ASCII codes which are mnemonic to
   the protocol is encouraged, but not required.

This seems like good advice. Including an example for one of the CBOR Protocols
under development might be helpful.

Section 2.2:

   The tag content of that tag is a second CBOR Tag that has been
   allocated to describe the specific Protocol involved, as described
   above.

I'd replace "as described above" with an explicit reference to Section 2.1.
Moreover, I might rephrase this to something like the following:

   The tag content of the outer tag is a second CBOR Tag whose number has
   been allocated to describe the specific Protocol involved, as described
   above. The tag content of this inner tag is the single CBOR data item.

Section 2.3:

Unlike 2.2, there's no accompanying example. I think it would improve
readability if one were included, even though conceptually the wrapping
mechanism is simple.

Section 3.2:

   If only one item is ever expected in the file, the use of Labeled
   CBOR Sequence may present an implementation hurdle to programs that
   previously just read a single data item and used it.

What stood out to me when reading this document is that the CBOR Sequence
wrapper could (seemingly) be used for all use cases -- it just happens to be a
little more complicated to implement when all one requires is a single data
item and doesn't expected to be concatenating files (wrappers) together.
However, the additional complexity seems pretty minimal. Would it be worth just
dropping the Tag Wrapped variant entirely? At the very least, that would seem
to not fracture parsing support, where some parsing programs expect a single
wrapped Protocol data item in a file, whereas others might expect multiple.
Encouraging the latter seems more generally useful, especially give the PEM
certificate format example in Section 3.

Section 3.3:

   If the Protocol expects to use other tags values at the top-level,
   then the use of the tag wrapped format may be easier to explain in
   the protocol description.

I didn't quite follow this. In particular, the "top-level" for the Protocol is
is the wrapped CBOR data item, right? That is, using the example from Section
2.2.1, the top-level is here:

   d9 d9f7                       # tag(55799)
      da 63740070                # tag(1668546672)
         81                      # array(1)   <----- top-level?

But this text in Section 3.3 seems to suggest that the top-level is:

   d9 d9f7                       # tag(55799) <----- suggested top-level
      da 63740070                # tag(1668546672)
         81                      # array(1)

My understanding is that the Protocol's use of CBOR is entirely encapsulated by
the wrappers, so I'm not sure I understand the guidance in this section.
Clarification might be helpful, if only for me. =)