Hi
Your file format document is a great document:
https://git.glasklar.is/sigsum/core/sigsum-go/-/blob/main/doc/sigsum-proof.m...
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/2...
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