Hi
Your file format document is a great document:
https://git.glasklar.is/sigsum/core/sigsum-go/-/blob/main/doc/sigsum-proof.…
I have some ideas for how to improve it; I may have mentioned these
before but would like to summarize the ideas and ask for your feedback:
1) Suggest a filename extension
It seems some people use *.proof although *.sigsum-proof may be more
advertizy. Or just *.sigsum?
2) Suggest a filename naming convention
It should also suggest that the common way to name a Sigsum proof file
is to name it after the file it contains a proof for, and include an
example like:
hello-2.1.3.tar.gz
hello-2.1.3.tar.gz.proof
3) Specify a MIME media subtype. I suggest "text/sigsum-proof".
4) To be a clear MIME media subtype specification it should discuss
character set encoding concerns. The document already refer to ASCII
and I suggest making this even more explicit: Sigsum proof files MUST be
7-bit clear ASCII files and MUST NOT contain any byte with the high bit
set.
5) Add a ABNF grammar describing the format.
6) Discuss how to handle non-compliant data. For example is a "#"
comment line allowed? Is adding/removing whitespace allowed? CRLF vs
CR vs LF vs NUL etc delimiters? Behaviour if the format doesn't comply
with the grammar? "Applications MUST generate compliant data and MUST
be able to parse compliant data, and SHOULD NOT use non-compliant data.
A valid reasing for accepting non-compliant data is if the applications
for some reason is unable to implement a strict parser."
7) Putting the text into an IETF draft would be useful, as a reference
for the MIME media subtype registration and a file format reference.
I'm sure you know the process, but I'm happy to put this together and
submit it if you want.
8) Versioning... the following document makes me a little nervous that
the file format is still in flux which is detrimental for deployment:
https://git.glasklar.is/sigsum/project/documentation/-/blob/main/proposals/…
It may be useful to discuss if all file format versions are using the
same filename extension, convention, MIME media sub-type, and if so any
discussion how entities should behave when parsing and generating files.
I think there are two options: 1) Pretend version 1 never existed and
just remove all support for it. 2) Document that applications MUST
generate version 2 format, and applications MUST handle both formats and
MUST discard the short 'leaf' checksum.
/Simon
