Spec nitpicking

[neinseg]

Hey there,

writing a compatible, embedded (µC) decryption-only POC implementation of age, I noticed that in a few places, the spec is not explicit in what it expects, and I had to look at age's code to figure out details. I know the spec currently is not a formal spec, but I thought listing the underspecified details will be useful if at some point someone wants to create a (more) formal spec from it.

• The spec does not state which kind of newlines it expects: LF or CRLF. Is a compliant implementation expected to support both? I think explicitly spec'ing unix newlines here would be best for implementation simplicity.
• The spec isn't clear on spaces after stanza arrows: From the examples I gather that the -> is always followed by a space, but would a file without that space still be valid? I think it would be best to require exactly one space there.
• The spec doesn't say how runs of consecutive spaces are handled in stanza argument parsing. Is "foo[sp][sp]bar" equivalent to the arguments ["foo", "", "bar"] or ["foo", "bar"]? I think spec'ing the former would be best, explicitly stating that arguments are separated by exactly one space. In the same way, spec'ing what happens when the arg line ends on spaces would be useful.
• The spec isn't explicit on the space between the end-of-header marker "---" and the header HMAC.
• The spec says that the HMAC covers the entire header up to the "---" end of header marker. From the code I gather that the HMAC ends including the third dash, and excludes the following space. That would be useful information to have in the spec.
• In the description of scrypt stanzas, the spec doesn't state how log2(N) is encoded. I assume decimal, no leading zeros, without sign?
• Where labels are specified for the HKDF, it is unclear whether the trailing null byte is considered part of the label (it is not). Also, while the document refers to RFC5869, terminology is inconsistent: What age calls "label", the RFC calls "info".
• In the spec of the "---" line it remains unspecified how many bytes of HKDF are used in HMAC
• edit: I just noticed that for encrypt() the spec points to RFC 7539. However, AFAICT the RFC encrypt function outputs tag and ciphertext as two separate outputs, and AFAICT the RFC does not specify which one goes first in a binary stream. Of course, the natural thing to do is to append the tag to the ciphertext, and that's what both age and some libraries do (e.g. the python cryptography package). If I'm correct in that the RFC doesn't specify this it would be useful information to have in the age spec. I'm using mbedtls, which expects both as separate inputs/outputs and leaves it up to the user how to format these.

Thank you for the great work,
Jan

[neinseg]

One more thing that I just noticed: The spec does not place an upper bound on the number of stanzas that may be contained in a header. While this keeps age as flexible as possible, it does open the possibility for DOS since a recipient has to verify all stanzas in turn as for every stanza the recipient has to potentially calculate a computationally fairly expensive X25519 point multiplication. On my laptop using a recent AMD Ryzen CPU, I get about 1 MB/s of unwrapping pure X25519 age stanzas (about 10 kStanza/s). I think on more resource-constrained systems, this could become an issue.

I think a possible fix could be to have something in the spec like "a compliant implementation MUST support at least [insert large but not astronomical number here, e.g. 256] stanzas of the same type" This would give application developers an useful value to refer to. age -e could then simply warn the user after recipient 256 that the other end might not support that many recipients, and age -d could come with a default that errors out after stanza # 256 like, "hey, this file contains unusually many stanzas. To parse them all, pass --please-take-your-time" or something.

Similarly, maximums on the length of a header and of a single stanza would be useful for an implementation to error out quicker than after parsing the entire file. An age payload may legitimately be several gigabytes in size. While it's hard to agree on a single maximum header size that will fit all possible use cases and all future developments, I think it should be possible to set an order of magnitude limit. Even if age goes post-quantum at some point and stanza sizes massively increase, I think something like 10 MB per stanza and say, 512MB for the whole header should be a sane limit.

[neinseg]

Another minor observation from #284 on ephemeral secrets: The go implementation will generate a new ephemeral secret for every stanza, so this recipient will obviously be able to decrypt all of their stanzas but nothing unexpected will happen. However, the spec only requires a new ephemeral secret per file key. This leads to the interesting case where if an implementation actually did that and shared the same ephemeral secret e.g. for all X25519 stanzas, any recipient can check for a public key they know if it matches any other stanza. While this probably isn't a problem, the property if recipients are secret or not towards other recipients should not depend on an implementation detail like this.

[The-King-of-Toasters]

I made similar comments in another discussion myself, as I'm writing my own implementation as well. We should swap notes.