On Stable Storage for Items in Concise Binary Object Representation (CBOR)
draft-ietf-cbor-file-magic-12

Thanks for this document. It seems useful, and the core specification
part in Section 2 is clear and understandable.

That said, it could be even friendlier to someone approaching it as a
CBOR n00b. I don't think that's a major concern, because I can’t
imagine why someone other than a hapless IESG member would approach this
document cold, without some reasonable background in CBOR. Still, if you
want an example of what I'm talking about, the casual "so that there are
no leading zeroes" in Section 2.1, with no whys or wherefores, felt a
bit like a scavenger hunt.

I also agree with a number of Lars's comments (in particular, what's a... 
disk? Some technology from the 1900s?). Also Zahed's suggestion to move
Section 3 to an appendix.

Finally, while I am quibbling about style, I thought the trips down 
memory lane and visits to sites of software grievances of Christmas 
Past in Sections 1 and 3 slowed down the read without adding insight.

Finally, I do have one specific comment on where the text is unclear in
Section 2.2:

   A CBOR Protocol specification may specify the use of two tags only
   for specific cases.  For instance, it might use them when storing the
   representation in a local file or for Web access, but not when using
   them in protocol messages that already provide the necessary context.

The first sentence reads like a prohibition on specification of two tags
for general cases. (I don't know what that would mean, it's just a
straightforward way to parse it. "May" combined with "only" is
the difficult bit I think.) If your meaning is what I think it is,
substituting "might" for "may" would fix it.

But in the final analysis, the fact that all I've got is quibbles is
evidence of a job well done, thank you. :-)

Thank to Chris Wood for the SECDIR review.  

Thank you for addressing my DISCUSS and COMMENT points.

¯\_(ツ)_/¯

Thanks for working on this document. I kind of like the question/answer style of writing the document.

Some comments/questions below, and I think addressing them would help improving the document.

- Section 2.1: it say's

      This tag needs to be allocated by the author of the CBOR Protocol
   
   it was not clear to me if "this tag" is the same tag that needs IANA registration or not. It needs some clarification text on that.

- file(1) is both referred as command and program, I always thought it is a command.

- Section 3.2: I didn't get the proper motivation for this section in this document. There were no mention of other CBOR data items and certainly they become the center piece in this section. I think it would be great to add some text about the motivation. 

- Speaking very frankly I feel like section 3.1 and section 3.2 are not the center part of this specification and should be moved to appendix section.

Thank you for the work put into this document. This document describes a nice addition to CBOR.

Please find below some non-blocking COMMENT points (but replies would be appreciated even if only for my own education), and some nits.

Special thanks to Christian Amsüss for the shepherd's write-up even if the justification for the intended status is somehow weak (but at least present). 

I hope that this helps to improve the document,

Regards,

-éric

## General comment

I was about to ballot a DISCUSS due to the absence of BCP14 and any normative language in a standard track document. Explanations from the authors/WG/AD will be more than welcome as I am not convinced by the shepherd's explanation ("let's avoid down ref in the future").

## Abstract

Just wondering whether the "on-disk" actually reflects the use of the Unix `file` command as this command also works on many other file systems / storage.

The abstract seems to indicate that there is ONE format while the rest of the document is about THREE formats. Suggest to update the abstract to reflect the choice among 3 formats.

## Section 1

Unsure whether the comparison of Unix file with TCP/IP stream brings any value.

Should there be a reference for "MIME type" ?

Should there be a reference for "media type registration template" ?

BTW, this section reads like a nice set of anecdotes, which is easy to read, but a more logical flow would be a plus for the reader.

A reference to CBOR RFC 8742 is probably required.

"magic number" should perhaps be introduced before citing it ?

Unsure whether the paragraph "A major inspiration ..." brings any value to the text.

## Section 1.2

Is the 'magic number' unique per CBOR protocol or just for any CBOR protocol? (i.e., this definition seems really restricted to CBOR and not to `file`) Should it also be distinct from other 'magic numbers' in /etc/magic ?

## Section 2

I am confused, and probably misread the document, but earlier I had the impression that THREE methods will be specified in this document and this section defines only TWO.

## Section 2.1

Should the 4-byte magic number be different than the existing 'magic numbers' supported by `file` ?

## Section 2.2.1

I must be really confused (and sorry about that) but the example contains a 0x00 which contradicts the above "avoid values that have an embedded zero byte" (from section 2.1).

## Section 3

I really love the "COVID vaccination certificate that needs to be displayed in QR code form" example (just use "COVID-19" perhaps) but should a reference be added ?

The considerations for the protocol designers do not really fit my ideas about a standard track document but rather of a BCP.

# NITS  

## Section 1

In "two possible methods of enveloping data are presented: a CBOR Protocol designer will specify one", should the ":" rather be a ";" ? Anyway, the RFC editor will review it ;-)

## Section 2.3

Please be consistent with the use of lower case or upper case for hexadecimal numbers, e.g., 0x42_4f_52

"Abstract", paragraph 1, comment:
>    This document defines an on-disk format for CBOR data items that is
>    friendly to common on-disk recognition systems such as the Unix
>    file(1) command.

I suggest to not talk about disks or stable storage in this abstract or the
document body. What's actually being defined here is a file layout, and files
can be stored on a variety of media. (And "file" isn't an "on-disk recognition
system" either, it's a heuristic file type classifier.)

Section 2.1, paragraph 1, comment:
>    The IANA policy for 4-byte CBOR Tags is First Come First Served, so
>    all that is required is an email to IANA, having filled in the small
>    template provided in Section 9.2 of [STD94].

FCFS codepoints may be requested in different ways in the future (e.g., web
forms) in addition to email. The document need not go into details on how FCFS
requests are made.

Section 2.1, paragraph 0, comment:
>    In order to be in the four-byte range, and so that there are no
>    leading zeros, the value needs to be in the range 0x01000000 (decimal
>    16777216) to 0xFFFFFFFF (decimal 4294967295).

Including or excluding those two boundary values?

Section 2.1, paragraph -1, comment:
>    The use of a sequence of four US-ASCII codes which are mnemonic to
>    the protocol is encouraged, but not required.

If it's encouraged, why not require it, so that software can actually depend on
it rather than needing to test for it? (Ditto for the suggestion to avoid
zeroes.)

Thanks to Pete Resnick for their General Area Review Team (Gen-ART) review
(https://mailarchive.ietf.org/arch/msg/gen-art/UX8_f-rnj6FGgrSKRd-WCB8SuYg).

-------------------------------------------------------------------------------

All comments below are about very minor potential issues that you may choose to
address in some way - or ignore - as you see fit. Some were flagged by
automated tools (via https://github.com/larseggert/ietf-reviewtool), so there
will likely be some false positives. There is no need to let me know what you
did with these suggestions.

Paragraph 7768, nit:
>  shutting the daemon down. During testing it is sometimes the case that upgr
>                                   ^^^^^^^
A comma is probably missing here.

Paragraph 7824, nit:
> ot normally loaded in the daemon. Instead the IPC that is normally sent acro
>                                   ^^^^^^^
A comma may be missing after the conjunctive/linking adverb "Instead".

Hi,

Apologies for a late review, and there is just one none blocking issue that I wanted to raise:

   It is further
   suggested to avoid values that have an embedded zero byte in the four
   bytes of their binary representation (such as 0x12003456), as these
   may confuse implementations that treat the magic number as a C
   string.

I was less convinced by this statement because:
(1) It seems like C treating this as null terminated string is probably not the right thing to do, I'm not sure that we should be implicitly endorsing that.
(2) When translating values from the Content-Format registry means that this issue is presumably unavoidable.  I.e., it looks like your example in 2.2.1 violates this guidance.

Regards,
Rob