Comments about the age format document

[The-King-of-Toasters]

I'm currently writing an age implementation in Zig, and have encountered a couple issues with the format document at https://age-encryption.org/v1. Keep in mind I'm not a cryptographer, and I'm only doing this because I have a burning hatred for gpg.

• It is not obvious on first sight that the encrypt operation acts as an AEAD, and thus the result is cyphertext || tag. I'm not sure of any other implementation that doesn't append the tag, other than Zig). I had to go look at the Go implementation to check this myself. I think it would be better to explicitly note this with wording like chachaSeal[key, nonce](plaintext).
• The ssh-ed25519 documentation is confusing and incorrect. Reading it as is, the steps for wrapping a file key are:

  their key: [32]u8
  SSH key: u32be(11) || "ssh-ed25519" || u32be(32) || their key
  ephemeral secret: random(32)
  
  tweak: HKDF[SSH key, "age-encryption.org/v1/ssh-ed25519"]("")
  
  our public key: X25519(ephemeral secret, basepoint)
  converted key: edwardsToMontgomery(their key)
  tweaked key: X25519(tweak, converted key)
  shared secret: X25519(ephemeral secret, tweaked key)
  

  However, the reference implementation does it very differently:

  our public key: X25519(ephemeral secret, basepoint)
  converted key: edwardsToMongomery(their key)
  shared secret: X25519(tweak, X25519(ephemeral secret, converted key))
  

  Key information about the ed25519 process is split into another page, and the order of terms made it very hard for me to grok the steps in a procedural manner. Also, in the time since the document was written, draft-ietf-curdle-ssh-ed25519-ed448-08 became a proper rfc: RFC 8709.

Overall I have some ideas for improvements:

• Split the tool spec and format spec into two distinct documents. I would put it under age-encryption.org/version/cmd or something.
• Remove all outdated/unsupported things from the beta (e.g. support for github: and alias: on the command line). Since the reference implementation explicitly errors out when you do this, I think it's safe to remove. Better to add that information to the manpage IMO.
• All functions, variables and other key definitions should be under a single subheading, and note the exact types/construction that they return.
• List the file key wrapping/unwrapping in a procedural manner, so variables first, then functions.
• Describe the STREAM scheme in more detail (i.e., how the nonce is incremented, when chunks are flushed).
• Describe the PEM encoding scheme in more detail (i.e., define what is considered malleability, the number of characters per line).
• Convert the document to static HTML or plaintext. This is more of a nice-to-have, but having it on Docs means that it'll always suck up a considerable amount of CPU cycles on my thinkpad, which I avoid currently by exporting it as a pdf. I could help in this area.

[str4d]

Following up on this, the age specification has now been written (the document this discussion refers to was really a design document, not a specification). The previous URL now points to the specification, which can also be reached at https://c2sp.org/age.

[FiloSottile]

Hi! Happy to see implementations of age in other languages, and thank you for the spec feedback.

As @str4d mentioned, most of the issues are addressed by the new spec at https://c2sp.org/age. It covers only the format, while the CLI documentation lives in the man page now. Have a look and let us know what you think.

The SSH methods are not specified in that document, I'll put together a separate document for them. Generally, I don't want Note that X25519(ephemeral secret, X25519(tweak, converted key)) and X25519(tweak, X25519(ephemeral secret, converted key)) are equivalent, so the design document is not wrong.