bip-85: add example use for age key derivation#2174
Open
dmonakhov wants to merge 1 commit into
Open
Conversation
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
|
Thanks i apologies |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
====Example use: age key derivation====subsection atthe end of the
===HEX===section inbip-0085.mediawiki.The subsection:
side-by-side from one master.
Test vectors
Derived from the master xprv already used by the HEX test vector in the same section. Reproducible end-to-end with stock tools:
The PQ recipient is a 1959-character bech32 string (it encodes
the 1216-byte X-Wing public key); only its SHA-256 is shown
inline. The full string is regenerable from the seed via
X-Wing.NewKeyFromSeed(seed).EncapsulationKey()and lives inthe reference implementation's test data.
End-to-end verification path:
bipsea derive -a hex -n 64 -i 0 -x <MASTER>reproduces theexisting HEX64 test vector (sanity check).
bipsea derive -a hex -n 32 -i 0 -x <MASTER>produces the32-byte entropy above.
identity strings.
age-keygen -y(age v1.3.0+) on each identity returnsthe matching recipient byte-for-byte (classic full string;
PQ full string hashes to the stated SHA-256).
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.
Reference implementation
age-keygen-det
— single-binary Go tool that converts a 32-byte hex seed into
an age identity file (classic or PQ). The output format mirrors
stock
age-keygenso existing age tooling (age-keygen -y,age -d,age -r) works unmodified.age-keygen -yinCI for both flavours.
CGO_ENABLED=0,-trimpath,-buildid=); same source → byte-identical binary.A worked end-to-end example using bipsea + age-keygen-det + the
spec's own master xprv is documented in the project's README
under "Worked example: BIP-85 → age".
Open question
Should the subsection also include the index-range partition guidance (
[0, 1000)for PQ identities,[1000, 2000)forclassic identities) to avoid producing the same 32 bytes under two different HRPs when both flavours are derived from one master? The reference implementation does NOT enforce this partition — it is a documentation convention, not a crypto contract. 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.