Improve DX with custom Stanzas

[AnomalRoil]

I'm talking here as a developer using the age library, I guess it falls under UX reports?

While it is possible to implement our own Wrap and Unwrap types, it is difficult currently to advertise we've done so when using age as a library.

For instance a custom Wrap implementation with our own recipient type will error as follow when decrypted with age:

age: error: no identity matched any of the recipients
age: report unexpected or unhelpful errors at https://filippo.io/age/report

which is expected, but not very informative for the user.

Furthermore, it's not possible to set custom Header and Footer in armor to differentiate our armored ciphertext from a common age ciphertext:

age/armor/armor.go

Lines 23 to 26 in 084c974

	const (
	Header = "-----BEGIN AGE ENCRYPTED FILE-----"
	Footer = "-----END AGE ENCRYPTED FILE-----"
	)

And it's also not possible to tweak the intro to advertise a custom type of age Stanza:

age/internal/format/format.go

Line 108 in 084c974

const intro = "age-encryption.org/v1\n"

While the latter is fine since it's quickly apparent that a custom recipient type was used by looking at the -> headers' lines, it's not the case at all with the armored ciphertexts.

My suggested improvements would be to:

• add a way to customize the Header and Footer in armor, since this package could very well be of use to other developers on its own.
• in the case where only unknown recipients are parsed by the cmd line tool age, error out like now, but display at least one of them to help the user understand they need a custom plugin / other tool to decrypt the ciphertext.

What do you think?

[AnomalRoil]

For context this is related to how we're using custom stanzas in https://github.com/drand/tlock and as you can see the ciphertext that are generated here: https://timevault.drand.love/

For example this one:

-----BEGIN AGE ENCRYPTED FILE-----
YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IHRsb2NrIDMwNTA0ODAgNzY3Mjc5N2Y1
NDhmM2Y0NzQ4YWM0YmYzMzUyZmM2YzZiNjQ2OGM5YWQ0MGFkNDU2YTM5NzU0NWM2
ZTJkZjViZgpoVll1dXliT3g3S2QyZm9WM1hibUJxWndJeERCUC9rUHgrbFlvVlZK
NkFyV0V0MVM0Qi9KTERoUi9TRmovei9ICkZ2OURRRXVmUWpEMEpLV3FWNFZNb3BQ
Y0p5YzlOWDhLSzViejRTMDhmRm8KLS0tIGhjazRzeXA3Znd6amhqTHVKM1Nmc1V3
b0o1OW1zcjVMNWk1T0J1NzVjdjQKdhVW/YkoBuU+cOe8XVHftFZxjKhjBrwY5g1v
9jJXoPsDB8nC9SkbuQ1fzMshKKe1Ah5wKjtM8g==
-----END AGE ENCRYPTED FILE-----

PS: Yes, I plan to look into implementing a plugin mode for age in tle once the plugin feature is merged into the Go codebase. I'm afraid I'm not planning a Rust plugin @str4d, but @CluEleSsUK might be.

[FiloSottile]

I opened #486 to improve the error message, but I am going back and forth about custom armor headers. They would be reasonably easy to do for library use of age, but generally we want to encourage not reinventing cmd/age and writing plugins instead, now that those are an option. Should a plugin be allowed to set the armor header? What if two plugins try to do that? How would that work on the decryption side? Maybe we could contact the plugins before reading the file, to get supported armor headers, but that feels like a lot of complexity.

What do you think?

[AnomalRoil]

I think a plugin should be allowed to specify a custom armor header, yeah since it is a human readable indicator that you need plugin XYZ to decrypt it.

I feel like the armor headers and footers should be discarded by the library anyway since the only interesting thing for age itself is whether or not there is a stanza it can process or not in the armored data.

I agree with you that an interaction with the plugins when decoding armor is superfluous. Maybe only support changing the AGE part? And match on "BEGIN" and "ENCRYPTED FILE". Or maybe only allow adding data to it suffixed to AGE ?
As in:

-----BEGIN AGE-TLOCK ENCRYPTED FILE-----