feat: add self-describing key container codecs (pkix,pkcs8,cose-key)#400
Open
feat: add self-describing key container codecs (pkix,pkcs8,cose-key)#400
Conversation
Introduce container codecs for IETF-standard asymmetric key formats that carry the algorithm identifier alongside the key material, so implementers can reuse existing crypto libraries and specs rather than mint a per-algorithm codec for every new scheme. - pkix-pub (0x40): SubjectPublicKeyInfo (SPKI) per IETF RFC 5280 section 4.1.2.7 - pkcs8-priv (0x41): OneAsymmetricKey (PKCS #8) per IETF RFC 5958 section 2 - both formats self-identify the key algorithm via the embedded AlgorithmIdentifier OID - codes placed in the single-byte varint range (< 0x80) so existing users of libp2p-key (0x72) in peer IDs and IPNS names can migrate without paying an extra prefix byte per identifier - 0x40 and 0x41 sit in the unclustered 0x39-0x4f free block, avoiding the ipld/CID-codec neighborhood at 0x70-0x7f Refs: - https://www.rfc-editor.org/rfc/rfc5280 - https://www.rfc-editor.org/rfc/rfc5958 - libp2p/specs#711
Register the CBOR-native counterparts to pkix-pub/pkcs8-priv so the table has one-codec-per-role containers for both the DER (ASN.1) and CBOR (COSE) ecosystems, covering the same "algorithm identifier travels in the payload" model on both sides. - cose-key (0x42): COSE_Key map per IETF RFC 9052 section 7; media type application/cose-key - cose-key-set (0x43): COSE_KeySet array per IETF RFC 9052 section 7; media type application/cose-key-set - split mirrors IETF's own registration of two media types and two CoAP Content-Format IDs (101 and 102), and keeps the "prefix tells you the shape" invariant - both remain in the single-byte varint range (0x42 and 0x43 in the unclustered 0x39-0x4f block) for identifier cost parity with libp2p-key Refs: - https://www.rfc-editor.org/rfc/rfc9052 - https://www.iana.org/assignments/media-types/application/cose-key - https://www.iana.org/assignments/media-types/application/cose-key-set
This was referenced Apr 14, 2026
MarcoPolo
approved these changes
Apr 14, 2026
Member
|
Before having a closer look: do they need to be in the 1 byte range, or can then be > 0x80? Getting them into the 2 bytes range is much easier as it needs a less thorough review. |
Contributor
|
1 byte range would be ideal, as that lowers the overhead to bridging to other standards. 2 bytes wouldn't be a blocker of course, but if this isn't worth a 1 byte codepoint, I'm not sure what would is. |
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.
Summary
Adds a family of self-describing key container codecs in one motion. Each wraps an IETF-standard container whose payload carries its own algorithm identifier, so one codec covers every algorithm the container
can carry.
pkix-pub0x40SubjectPublicKeyInfo(SPKI)pkcs8-priv0x41OneAsymmetricKey(PKCS#8)cose-key0x42COSE_Keymap (application/cose-key)cose-key-set0x43COSE_KeySetarray (application/cose-key-set)The algorithm is self-identified by the payload:
AlgorithmIdentifierOID for the DER containers,kty/alg/crvfor COSE.Motivation
The main goal is to make these codecs usable for libp2p peer IDs and IPNS records, so the set of supported key types in those systems stops being gated by multicodec assignments.
Today, adopting a new key type in libp2p or IPNS requires minting a per-algorithm multicodec entry first. That turns the multicodec table into a bottleneck: every new algorithm (ML-DSA, SLH-DSA, any future PQ
scheme, niche curves) has to land a bespoke entry before applications can use it, and everyone has to agree on that entry before implementations can ship.
These four containers break that coupling. Because the algorithm identifier lives inside the payload, a single codec covers every algorithm the container can carry. The moment an IETF/RFC encoding exists for a
new key type (for example RFC 9881 for ML-DSA in SPKI/PKCS#8, or a
COSE_Keykty/algregistration), it is immediately usable as a libp2p or IPNS key withoutwaiting on a multicodec update.
Concretely:
pkix-pub; any PKCS#8-encodable private key may be supported throughpkcs8-priv; CBOR-native stacks get the same path viacose-key/cose-key-set.crypto/x509, rustls, Java JCE, WebCrypto, and every other mainstream crypto stack.COSE_Keyis already the key formatused by WebAuthn/passkeys, CWT, EAT, and constrained-device stacks.
Related:
Code placement
All four codes are single-byte varints (
< 0x80). Existing users oflibp2p-key(at0x72, one byte on the wire) encode the codec prefix into every peer ID and IPNS name. Placing the replacements at two-byte codes would mean every migrated identifier pays an extra byte forever.Specifically,
0x40-0x43sit in the unclustered0x39-0x4ffree block, avoiding theipld/CID-codec neighborhood at0x70-0x7fwhere akey-tagged entry would not fit the surrounding tags.Why
cose-keyandcose-key-setare separate codecsCOSE_Keyis a CBOR map;COSE_KeySetis a CBOR array. IETF registers them as separate IANA media types (application/cose-keyvsapplication/cose-key-set) and separate CoAP Content-Format IDs (101 vs 102) in RFC 9052 §11.3.