Skip to content

Add support for COSE keys and key sets #712

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
MarcoPolo wants to merge 3 commits into
base: marco/pkix
Choose a base branch
from
+41 −1
Open

Add support for COSE keys and key sets #712

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4adf1f0
Add support for PKIX and PKCS#8 keys
MarcoPolo Apr 13, 2026
ac2b6a9
Add support for COSE keys and key sets
MarcoPolo Apr 14, 2026
0067e2d
Update peer-ids/peer-ids.md
MarcoPolo Apr 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 41 additions & 1 deletion peer-ids/peer-ids.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,11 @@ enum KeyType {
Ed25519 = 1;
Secp256k1 = 2;
ECDSA = 3;

PKIX = 0x40;
PKCS8 = 0x41;
COSE_KEY = 0x42;
COSE_KEY_SET = 0x43;
Comment on lines +69 to +70
Copy link
Copy Markdown
Member

@lidel lidel Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
COSE_KEY = 0x42;
COSE_KEY_SET = 0x43;
COSE_Key = 0x42;
COSE_KeySet = 0x43;

Other ones look like Secp256k1 and RFC 9052 uses COSE_KeySet.

Perhaps rename to match the RFC?

}

message PublicKey {
Expand Down Expand Up @@ -110,11 +115,13 @@ The second is for generating peer ids; this is discussed in the section below.

### Key Types

Four key types are supported:
The following key types are supported:
- RSA
- Ed25519
- Secp256k1
- ECDSA
- PKIX Encoded Public Keys
- PKCS#8 Encoded Private Keys

Implementations MUST support Ed25519. Implementations SHOULD support RSA if they wish to
interoperate with the mainline IPFS DHT and the default IPFS bootstrap nodes. Implementations MAY
Expand Down Expand Up @@ -185,6 +192,39 @@ To sign a message, we hash the message with SHA 256, and then sign it with the
[ECDSA standard algorithm](https://tools.ietf.org/html/rfc6979), then we encode
it using [DER-encoded ASN.1.](https://wiki.openssl.org/index.php/DER)

#### PKIX Public Keys

The PKIX key type only encodes public keys. The Data field is the [PKIX
encoding](https://www.rfc-editor.org/rfc/rfc5280) of the public key. The public
key and algorithm are identified by the [Subject Public Key
Info](https://www.rfc-editor.org/rfc/rfc5280#section-4.1.2.7) field.

Signature Verification is defined by the key algorithm used.

For backwards compatibility, if a key algorithm has a prior libp2p specific encoding, implementers SHOULD prefer that.

#### PKCS#8 Private Keys

The PKCS8 key type only encodes private keys. The Data field is the [PKCS#8 encoding](https://www.rfc-editor.org/rfc/rfc5958.html) of the private key.

Signing is defined by the key algorithm used.

For backwards compatibility, if a key algorithm has a prior libp2p specific encoding, implementers SHOULD prefer that.

#### COSE Key

The Data field is defined by [Section 7 of RFC
9052](https://www.rfc-editor.org/rfc/rfc9052#section-7).
Comment on lines +214 to +217
Copy link
Copy Markdown
Member

@lidel lidel Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Something I realized in the context of libp2p is that PeerID is a hash of this protobuf.

RFC 9052 COSE_Key is plain CBOR; no deterministic encoding is required. But this spec requires deterministic protobuf encoding so peer IDs are stable.

Problem: Two conformant COSE encoders can produce different Data bytes for the same key, yielding different peer IDs.

Fix: unsure, maybe require RFC 8949 §4.2 Core Deterministic Encoding for COSEKEY*, and reject non-deterministic encodings on decode?

Suggested change
#### COSE Key
The Data field is defined by [Section 7 of RFC
9052](https://www.rfc-editor.org/rfc/rfc9052#section-7).
#### COSE Key
The Data field is defined by [Section 7 of RFC
9052](https://www.rfc-editor.org/rfc/rfc9052#section-7).
The `COSE_Key` MUST be encoded using [CBOR Core Deterministic Encoding (RFC 8949 §4.2)](https://www.rfc-editor.org/rfc/rfc8949#section-4.2). Implementations MUST reject non-deterministic encodings.
Signing and verification for each member are defined by that member's COSE `alg` parameter.

Copy link
Copy Markdown
Contributor Author

@MarcoPolo MarcoPolo Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. 9052 has encoding restrictions, but they don't apply to the keys.

Copy link
Copy Markdown
Contributor Author

@MarcoPolo MarcoPolo Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also found this RFC: https://datatracker.ietf.org/doc/html/rfc9679 which sounds like what we should use instead of trying to define this.


The `COSE_Key` MUST be encoded using [CBOR Core Deterministic Encoding (RFC 8949 §4.2)](https://www.rfc-editor.org/rfc/rfc8949#section-4.2). Implementations MUST reject non-deterministic encodings.

Signing and verification for each member are defined by that member's COSE `alg` parameter.

#### COSE KeySet

The Data field is defined by [Section 7 of RFC
9052](https://www.rfc-editor.org/rfc/rfc9052#section-7).
Comment on lines +223 to +226
Copy link
Copy Markdown
Member

@lidel lidel Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PeerID semantics feel undefined?

Fix: spell out identity and verification rules, or drop COSE_KEY_SET from this PR until the use case is settled.

I think it may be beneficial to keep it to support hybrid keys and signatures, for example when we have both ed25519+something post-quantum secure, and requiring both sigs/handshakes etc.

so maybe:

Suggested change
#### COSE KeySet
The Data field is defined by [Section 7 of RFC
9052](https://www.rfc-editor.org/rfc/rfc9052#section-7).
#### COSE KeySet
The Data field is defined by [Section 7 of RFC
9052](https://www.rfc-editor.org/rfc/rfc9052#section-7).
`COSE_KeySet` is intended for hybrid keys and signatures, for example pairing Ed25519 with a post-quantum scheme so that handshakes and signatures combine both. The following rules apply:
- The `COSE_KeySet` MUST be encoded using [CBOR Core Deterministic Encoding (RFC 8949 §4.2)](https://www.rfc-editor.org/rfc/rfc8949#section-4.2). Implementations MUST reject non-deterministic encodings.
- Members MUST be ordered in ascending lexicographic order of their deterministic CBOR encoding. This ensures independent encoders produce identical bytes for the same set, so the resulting PeerID is stable.
- A `COSE_KeySet` MUST contain at least two members. A single-member set MUST be encoded as `COSE_Key` instead, so the same identity has exactly one on-the-wire representation.
- Each COSE `alg` (and key-type family) MUST appear at most once in the set, removing ambiguity about which member is expected to produce a given signature or handshake component.
- A signature or handshake over a `COSE_KeySet` identity is valid only if **every** member validates its corresponding component. Peers MUST NOT accept proofs that cover only a subset; doing so would defeat the purpose of the hybrid.
Signing and verification for each member are defined by that member's COSE `alg` parameter.

Copy link
Copy Markdown
Contributor Author

@MarcoPolo MarcoPolo Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it makes sense to back out the cose keyset changes. It only gives us an array of cose keys. You could imagine having a array of these protobufs instead.

Copy link
Copy Markdown
Member

@lidel lidel Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How do you mean? Current wire format for libp2p-key does not have repeatable fields, we don't have a spec for libp2p-key[], that is something you would have to invent, and add a new multicodec for it.

RFC for COSE_KeySet already exists, and could provide a backward-compatible way for hardening things with multiple keys (e.g. hybrid ed25519 + post-quantum).

Of course this is just an option, we dont have to support o require hybrid signatures this way, or at all, and can defer to future codes, but feels sensible to preregister COSE_KeySet here to allow libp2p ecosystem to experiment and evolve without gatekeepers.

Copy link
Copy Markdown
Contributor Author

@MarcoPolo MarcoPolo Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I mean using multiple protobuf messages instead of a COSE array. Maybe this doesn't work and the COSE array is better. I'm not sure. We'd also need to define how to hash the key set properly.


### Test vectors

The following test vectors are hex-encoded bytes of the above described protobuf encoding.
Expand Down