From 3a768c691799e377897c2879df16056b2dedf062 Mon Sep 17 00:00:00 2001 From: Leo Eichhorn Date: Thu, 8 Oct 2026 11:29:58 +0000 Subject: [PATCH 1/3] docs: add the secp256r1 ECDSA keys to the chain-key pages The interface spec and the management canister reference gained the `secp256r1` curve in #394. The concept and cycle cost pages still described threshold ECDSA as secp256k1 only. - The scheme table on the chain-key cryptography page gets a `secp256r1` (NIST P-256) row. Its use cases are web standards that require ES256: JSON Web Tokens, and VAPID web push (RFC 8292, section 2). - The key derivation paragraph names SLIP-10 for P-256, matching the `ecdsa_public_key` section of the spec. - The deployed keys table and the cycle costs table list `(secp256r1, test_key_1)` and `(secp256r1, key_1)` next to the secp256k1 keys, on the same subnets and at the same fees. `ic0.cost_sign_with_ecdsa` prices a signature by the subnet that holds the key, not by the curve. --- docs/concepts/chain-key-cryptography.md | 9 ++++++--- docs/references/cycle-costs.md | 4 ++-- 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/concepts/chain-key-cryptography.md b/docs/concepts/chain-key-cryptography.md index d4cfc37c..c9647878 100644 --- a/docs/concepts/chain-key-cryptography.md +++ b/docs/concepts/chain-key-cryptography.md @@ -40,11 +40,12 @@ BLS was chosen for two properties: Chain-key signatures extend threshold cryptography beyond ICP's internal operations. They let canisters hold keys for external signature schemes and sign arbitrary messages, which means canisters can control accounts on other chains. -Two signature schemes are supported, with the Schnorr API offering two algorithm variants: +Two signature schemes are supported. The ECDSA API offers two curves, and the Schnorr API offers two algorithms: -| Scheme | Algorithm | Key ID examples | Use cases | +| Scheme | Curve or algorithm | Key ID examples | Use cases | |--------|-----------|-----------------|-----------| | Threshold ECDSA | `secp256k1` | `key_1`, `test_key_1` | Bitcoin (legacy/SegWit), Ethereum, EVM chains, Filecoin | +| Threshold ECDSA | `secp256r1` (NIST P-256) | `key_1`, `test_key_1` | JSON Web Tokens signed with ES256, VAPID web push | | Threshold Schnorr | `bip340secp256k1` | `key_1`, `test_key_1` | Bitcoin Taproot, Ordinals | | Threshold Schnorr | `ed25519` | `key_1`, `test_key_1` | Solana, TON, Polkadot, Cardano, NEAR | @@ -67,7 +68,7 @@ Threshold Schnorr (including Ed25519) protocols are simplified variants of the E A small number of **master keys** are deployed across the network: one per signature scheme. From each master key, the protocol derives a unique **canister root key** for every canister using the canister's principal as input. From the root key, canisters can derive an unlimited number of child keys by providing a `derivation_path` in API calls. -For ECDSA and BIP340, key derivation uses a generalized form of [BIP-32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki), which means derived keys are compatible with standard Bitcoin and Ethereum HD wallet tooling. Ed25519 uses a custom hierarchical derivation mechanism designed for this use case. +For ECDSA on `secp256k1` and for BIP340, key derivation uses a generalized form of [BIP-32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki), which means derived keys are compatible with standard Bitcoin and Ethereum HD wallet tooling. ECDSA on `secp256r1` uses the same generalization over P-256, which is [SLIP-10](https://github.com/satoshilabs/slips/blob/master/slip-0010.md). Ed25519 uses a custom hierarchical derivation mechanism designed for this use case. Derivation is transparent: it happens inside the protocol as part of the signing and public-key-retrieval APIs. You provide a derivation path and the protocol handles the rest. @@ -91,6 +92,8 @@ The following master keys are deployed at the time of writing. The Network Nervo |--------|--------|---------|----------------| | `(secp256k1, test_key_1)` | ECDSA | Development and testing | 13-node subnet | | `(secp256k1, key_1)` | ECDSA | Production | High-replication subnet | +| `(secp256r1, test_key_1)` | ECDSA | Development and testing | 13-node subnet | +| `(secp256r1, key_1)` | ECDSA | Production | High-replication subnet | | `(bip340secp256k1, test_key_1)` | Schnorr | Development and testing | 13-node subnet | | `(bip340secp256k1, key_1)` | Schnorr | Production | High-replication subnet | | `(ed25519, test_key_1)` | Schnorr (Ed25519) | Development and testing | 13-node subnet | diff --git a/docs/references/cycle-costs.md b/docs/references/cycle-costs.md index 2c5b2e10..4d2aa17e 100644 --- a/docs/references/cycle-costs.md +++ b/docs/references/cycle-costs.md @@ -94,8 +94,8 @@ Threshold signing and key derivation are core ICP protocol capabilities: the cry | Key name | Algorithm(s) | Environment | Signing subnet | Cycles | ~USD | |----------|-------------|------------|----------------|--------|------| -| `test_key_1` | ECDSA (`secp256k1`), Schnorr (`bip340secp256k1`, `ed25519`) | Testing | 13-node (`fuqsr`) | 10_000_000_000 | ~$0.0137 | -| `key_1` | ECDSA (`secp256k1`), Schnorr (`bip340secp256k1`, `ed25519`) | Production | 34-node fiduciary (`pzp6e`) | 26_153_846_153 | ~$0.0357 | +| `test_key_1` | ECDSA (`secp256k1`, `secp256r1`), Schnorr (`bip340secp256k1`, `ed25519`) | Testing | 13-node (`fuqsr`) | 10_000_000_000 | ~$0.0137 | +| `key_1` | ECDSA (`secp256k1`, `secp256r1`), Schnorr (`bip340secp256k1`, `ed25519`) | Production | 34-node fiduciary (`pzp6e`) | 26_153_846_153 | ~$0.0357 | If the canister may be blackholed or called by other canisters, send more cycles than the listed cost: unused cycles are refunded, and this ensures calls succeed if the signing subnet grows in node count. From 4d4b7e94dd69d1e2b5229a084353ddacac0221cb Mon Sep 17 00:00:00 2001 From: Leo Eichhorn Date: Thu, 22 Oct 2026 13:32:28 +0000 Subject: [PATCH 2/3] docs: add X.509 certificates to the secp256r1 use cases WebPKI accepts ECDSA only on the NIST curves: the CA/Browser Forum Baseline Requirements permit P-256, P-384 and P-521. With a P-256 key, a canister can sign X.509 certificates, for example as a private certificate authority. --- docs/concepts/chain-key-cryptography.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/chain-key-cryptography.md b/docs/concepts/chain-key-cryptography.md index c9647878..30567c01 100644 --- a/docs/concepts/chain-key-cryptography.md +++ b/docs/concepts/chain-key-cryptography.md @@ -45,7 +45,7 @@ Two signature schemes are supported. The ECDSA API offers two curves, and the Sc | Scheme | Curve or algorithm | Key ID examples | Use cases | |--------|-----------|-----------------|-----------| | Threshold ECDSA | `secp256k1` | `key_1`, `test_key_1` | Bitcoin (legacy/SegWit), Ethereum, EVM chains, Filecoin | -| Threshold ECDSA | `secp256r1` (NIST P-256) | `key_1`, `test_key_1` | JSON Web Tokens signed with ES256, VAPID web push | +| Threshold ECDSA | `secp256r1` (NIST P-256) | `key_1`, `test_key_1` | X.509 certificates, JSON Web Tokens signed with ES256, VAPID web push | | Threshold Schnorr | `bip340secp256k1` | `key_1`, `test_key_1` | Bitcoin Taproot, Ordinals | | Threshold Schnorr | `ed25519` | `key_1`, `test_key_1` | Solana, TON, Polkadot, Cardano, NEAR | From b4a6ebdcf428b823096c9784a519004d0e6a1225 Mon Sep 17 00:00:00 2001 From: Leo Eichhorn Date: Thu, 22 Oct 2026 13:32:28 +0000 Subject: [PATCH 3/3] chore: bump the ic-cdk-management-canister pin to 0.3.0 0.3.0 moves to ic-management-canister-types 0.11, which adds EcdsaCurve::Secp256r1 and the million_round_instructions_total field of SubnetMetricsResult. None of the HTTPS outcall pages or examples that this pin covers use either, so no page changes. --- .sources/upstream.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.sources/upstream.json b/.sources/upstream.json index 8a333c04..253fd53f 100644 --- a/.sources/upstream.json +++ b/.sources/upstream.json @@ -116,7 +116,7 @@ { "repo": "dfinity/cdk-rs", "name": "ic-cdk-management-canister", - "pinned": "0.2.0", + "pinned": "0.3.0", "track": "crate", "crate": "ic-cdk-management-canister", "affects": "The HTTPS outcall APIs in guides/backends/https-outcalls.mdx, concepts/https-outcalls.md and references/cycle-costs.md, and the Rust snippets in the send_http_get, send_http_post and daily_planner examples. This crate versions independently of `ic-cdk` in the same repo, so it gets its own entry: 0.2.0 replaced the free `http_request` with the `HttpRequest` and `FlexibleHttpRequest` builders and moved pricing to version 2. Read the sections newer than the pin in https://github.com/dfinity/cdk-rs/blob/master/ic-cdk-management-canister/CHANGELOG.md.",