bip-85: add example use for age key derivation - #2174
Conversation
This comment was marked as off-topic.
This comment was marked as off-topic.
|
|
||
| ====Example use: age key derivation==== | ||
|
|
||
| The 32-byte output at <code>m/83696968'/128169'/32'/{index}'</code> is uniformly random and is suitable as the private-key seed for the [https://age-encryption.org/v1 age] file-encryption format. For classic age identities, bech32-encode the 32 bytes with HRP <code>AGE-SECRET-KEY-</code>; the corresponding recipient is the bech32 encoding (HRP <code>age</code>) of <code>X25519(seed, BASEPOINT)</code>. For post-quantum age identities (age v1.3.0+, Dec 2024), the same 32 bytes are a valid X-Wing seed; bech32-encode with HRP <code>AGE-SECRET-KEY-PQ-</code>. X-Wing internally SHAKE256-expands the seed into ML-KEM-768 and X25519 components, and the recipient is the bech32 encoding (HRP <code>age1pq</code>) of the X-Wing encapsulation key. A reference implementation is [https://github.com/dmonakhov/age-keygen-det age-keygen-det]. |
There was a problem hiding this comment.
A few requests for this section:
- Please insert newlines every ~80-90 chars so this file reads well in a terminal
- The Dec 2024 date is probably TMI, version makes sense but dates generally don't age well
- You say "uniformly random" but the point is "cryptographically random"
- Consider breaking most of the above into a small table for readability and using standard nomenclature like
||for concat, etc.
Example: please check the math and semantics (assume what's here is wrong), but to give you the idea:
| flavor | role | HRP | bytes encoded in data | encoded string |
|---|---|---|---|---|
| classic | identity | AGE-SECRET-KEY- |
seed (32 B) |
AGE-SECRET-KEY- || 1 || AG7WK…UKUMWQ || WNNT4U |
| classic | recipient | age |
X25519(seed, G) (32 B) |
age || 1 || m0hhzx…256wslq || mdz8e9 |
| PQ (X-Wing) | identity | AGE-SECRET-KEY-PQ- |
seed (32 B, same bytes) |
AGE-SECRET-KEY-PQ- || 1 || AG7WK…UKUMWQ || 5AN2M5 |
| PQ (X-Wing) | recipient | age1pq |
XWing.pk(seed) (≈1216 B) |
age1pq || 1 || (~1950 chars) || (6 chars) |
And then define your terms below, G, etc.
There was a problem hiding this comment.
Please insert newlines every ~80-90 chars so this file reads well in a terminal
The Dec 2024 date is probably TMI, version makes sense but dates generally don't age well
You say "uniformly random" but the point is "cryptographically random"
Ack. fixed with new version.
please check the math and semantics (assume what's here is wrong),
Oh.. thank you very much for pointing this. Indeed original test vectors was not correct, shame on me.
Please see updated version. test vectors are now correct.
| OUTPUT | ||
| * DERIVED ENTROPY=492db4698cf3b73a5a24998aa3e9d7fa96275d85724a91e71aa2d645442f878555d078fd1f1f67e368976f04137b1f7a0d19232136ca50c44614af72b5582a5c | ||
|
|
||
| ====Example use: age key derivation==== |
There was a problem hiding this comment.
| ====Example use: age key derivation==== | |
| ====<code>age</code> file encryption keys==== |
6cb352d to
943f1d9
Compare
|
Mostly looks good. Left one and line comment. For the PR description please delete the test vectors as they might have diverged and distract from the PR contents. |
Documents the connection between BIP-85's HEX application output at num_bytes=32 and the private-key seed format used by the age file-encryption format (https://age-encryption.org/v1) for both the classic X25519 identity (since age v1.0) and the post-quantum X-Wing identity (age v1.3.0+, Dec 2024). No new application number, no normative MUSTs added, no changes required in existing implementations. The amendment is purely documentational: a single subsection appended at the end of the HEX section. A test vector is added using the same master xprv as the existing HEX test vector in the same section, with both classic and post-quantum outputs. The PQ recipient (a ~1959-character bech32 string encoding the 1216-byte X-Wing public key) is included as a SHA-256 hash inline; the full string is in the reference implementation's test data. Reference implementation: https://github.com/dmonakhov/age-keygen-det - single-binary Go tool, BSD-3-Clause - cross-validates byte-for-byte against stock age-keygen -y in CI for both flavours
943f1d9 to
5055fa2
Compare
Done. please see PR updated. |
Motivation
age is a widely-deployed file-encryption format. Both its classic (X25519, since 2021)
and post-quantum (X-Wing / HPKE-MLKEM768-X25519, age v1.3.0+ Dec 2024) identity types take a 32-byte uniform seed as the secret-key material — which is precisely what BIP-85's HEX application at
num_bytes=32already returns.This PR adds a brief example-use subsection at the end of the HEX application section, documenting how to interpret the existing 32-byte HEX output as an age identity. No new application number, no normative MUSTs added, no changes required in existing implementations — the HEX application already produces exactly what age consumes; this PR just records the connection in the spec.
Documenting this gives users a single backup story: the same BIP-39 mnemonic that already secures their Bitcoin wallets can deterministically produce age identities, with no additional key-rotation infrastructure on top of what they already do.
It also unblocks downstream hardware-wallet firmware integration maintainers of firmware projects accept "implement this BIP-85 use case" much more readily than "implement a convention from a third-party repo." A spec-blessed convention turns the conversation from a bespoke contribution into a standards-conformance issue.
What changes
A new
====<code>age</code> file encryption keys====subsection atthe end of the
===HEX===section inbip-0085.mediawiki.The subsection:
Scope
This amendment is intentionally minimal:
application (128169').
about the HEX application.
(bipsea, bip85-js, ethankosakovsky/bip85).
Possible follow-ups (not in this PR):
AGEsubsection paralleling the existing RSA-GPG subsection, with full worked examples for each flavour and an optional index-partition recommendation (e.g.[0, 1000)for PQ identities,[1000, 2000)for classic identities, to avoid producing the same 32 bytes under two different HRPs when the same master is used for both flavours).0x616765'= hex-pack of ASCII "age"), with independent paths per flavour.These are noted only to clarify that this PR deliberately picks the minimal form; they can be raised separately if there is appetite.
Implementations
Per review, the spec text does not link a reference implementation.
A follow-up PR extending bipsea
with age derivation is planned.
Open question
Should the subsection also include the index-range partition guidance (
[0, 1000)for PQ identities,[1000, 2000)for classic identities) to avoid producing the same 32 bytes under two different HRPs when both flavours are derived from one master? Including it would be useful guidance; excluding it keeps the amendment maximally minimal. Open to reviewer preference.cc @ethankosakovsky @akarve — original BIP-85 authors per the
BIP header. Happy to revise based on review feedback.