diff --git a/.migration/learn-hub/how-does-icp-work/chain-key-cryptography/certified-communication.md b/.migration/learn-hub/how-does-icp-work/chain-key-cryptography/certified-communication.md deleted file mode 100644 index 0d1a681..0000000 --- a/.migration/learn-hub/how-does-icp-work/chain-key-cryptography/certified-communication.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -learn_hub_id: 34214090576404 -learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34214090576404-Certified-Communication" -learn_hub_title: "Certified Communication" -learn_hub_section: "Chain-Key Cryptography" -learn_hub_category: "How does ICP work?" -migrated: false ---- - -# Certified Communication - -Why do you trust data obtained from a blockchain? Well, all transactions and the subsequent changes to smart contract state made their way through the blockchain consensus protocol, which guarantees correctness as long as the underlying trust assumptions hold. But verifying correctness based on the consensus protocol is tedious: A client has to download and validate the blockchain data. Even in the case of more efficient mechanisms such as [Bitcoin's SPV](https://en.bitcoinwiki.org/wiki/Simplified_Payment_Verification) or [Ethereum's light clients](https://ethereum.org/en/developers/docs/nodes-and-clients/light-clients/), clients still have to perform significant amounts of work, such as downloading and validating block headers. This makes it difficult for applications with restricted uptime and resources, such as mobile or web applications, to operate on blockchain data without defaulting to centralized intermediaries. - -The Internet Computer is different: Using [chain-key cryptography](https://learn.internetcomputer.org/hc/en-us/articles/34209486239252), the Internet Computer can generate [digital signatures](https://en.wikipedia.org/wiki/Digital_signature) that can be validated with a single, permanent public key belonging to the Internet Computer. Unlike with traditional digital signatures, however, the private key material _never_ exists in a single place. It is always securely distributed between many different nodes, and valid signatures can only be generated when the majority of these nodes cooperates in a cryptographic protocol. A client application only has to embed the Internet Computer's public key, and can immediately validate all certified responses it receives from the Internet Computer, without putting any trust into the particular node it received the response from. - -The Internet Computer's certification feature is exposed to canisters through _certified variables_. From an application perspective, certified variables can be set during an update call to a canister, when the canister changes its state during a transaction that went through consensus. The certificate can then be read in a subsequent query call, so the canister can respond to a client's request in a trustworthy way but without incurring the additional delay of consensus. Certified variables also underlie many of the Internet Computer's advanced features such as [certified assets](https://learn.internetcomputer.org/hc/en-us/articles/34276431179412) and [Internet Identity](https://identity.ic0.app/). - -More technically, each canister can specify a single 32-byte value that will be certified by the subnet. Well-known concepts such as [Merkle trees](https://en.wikipedia.org/wiki/Merkle_tree) or, more generally, [authenticated data structures](https://cs.brown.edu/research/pubs/pdfs/2003/Tamassia-2003-ADS.pdf) can be used to extend the certification from this single 32-byte value to arbitrary amounts of data. Libraries such as [certified-map](https://github.com/dfinity/cdk-rs/tree/main/library/ic-certified-map) make the feature easily accessible for developers. - diff --git a/.migration/learn-hub/how-does-icp-work/chain-key-cryptography/chain-key-cryptography.md b/.migration/learn-hub/how-does-icp-work/chain-key-cryptography/chain-key-cryptography.md deleted file mode 100644 index 1c37470..0000000 --- a/.migration/learn-hub/how-does-icp-work/chain-key-cryptography/chain-key-cryptography.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -learn_hub_id: 34209486239252 -learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34209486239252-Chain-Key-Cryptography" -learn_hub_title: "Chain-Key Cryptography" -learn_hub_section: "Chain-Key Cryptography" -learn_hub_category: "How does ICP work?" -migrated: false ---- - -# Chain-Key Cryptography - -_Chain-key cryptography_ enables subnets of the Internet Computer to jointly hold cryptographic keys, in a way that no small subset of potentially misbehaving nodes on the subnet can perform useful operations with the key, but the majority of honest nodes together can. Chain-key cryptography provides several major benefits to ICP: - - 1. Secure and efficient subnet-to-subnet communication enables ICP to scale horizontally, increasing the compute and memory capacity as more nodes are joining the Internet Computer. - 2. [Certified responses](https://learn.internetcomputer.org/hc/en-us/articles/34214090576404) enable clients to validate the information they receive from ICP nodes efficiently and without the need of keeping any blockchain state. - 3. Smart contracts have access to a source of unpredictable and unbiased randomness. - 4. [Chain-key signatures](https://learn.internetcomputer.org/hc/en-us/articles/34209497587732) enable canister smart contracts on ICP to hold assets and invoke smart contracts on other blockchain networks. - 5. [vetKeys](https://internetcomputer.org/docs/current/references/vetkeys-overview) enable dapps to encrypt data based on encryption keys controlled by canister smart contracts. - - - -## Digital Signatures - -A _digital signature scheme_ is a very traditional type of public-key cryptosystem, in which a secret key (held only by the signer) is used to generate a digital signature on a message, and a public key (available to everyone) may be used to efficiently verify a digital signature on a message. The basic security property achieved by such a scheme is that a valid signature on a message cannot be created without explicitly invoking the signing algorithm with the corresponding secret key. - -A _threshold signature scheme_ is a digital signature scheme where the secret signing key is never stored in one location (which would become a single point of failure). Rather, the secret key is effectively split up into _secret shares_ , and each secret share is stored on a different machine. To sign a message, these machines must agree to sign the message and coordinate with one another to generate a digital signature in a distributed fashion (importantly, without ever reconstructing the secret signing key in one location). - -## Sharing Cryptographic Keys among the Nodes of a Subnet - -While threshold signature schemes have been around for a long time, the Internet Computer is the first blockchain-based system to fully integrate this technology in the core of its design. Each subnet is associated with the public key of such a threshold signature scheme. - -More technically, Chain-Key Cryptography is the combination of two cryptographic protocols: The first is a _distributed key generation_ protocol in which nodes of a subnet can together generate shares of a cryptographic key. The protocol ensures that the actual cryptographic key never actually exists at any one place, it exists only _virtually_ , determined by the shares held by all nodes together. A variation of the same protocol is used to re-share the cryptographic key when, e.g. the membership of a subnet changes and new nodes participate in the protocol. The second protocol is the _threshold signature_ protocol, which the nodes evaluate together when a message has to be signed. - diff --git a/.migration/learn-hub/how-does-icp-work/chain-key-cryptography/chain-key-signatures.md b/.migration/learn-hub/how-does-icp-work/chain-key-cryptography/chain-key-signatures.md deleted file mode 100644 index 76b00be..0000000 --- a/.migration/learn-hub/how-does-icp-work/chain-key-cryptography/chain-key-signatures.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -learn_hub_id: 34209497587732 -learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34209497587732-Chain-Key-Signatures" -learn_hub_title: "Chain-Key Signatures" -learn_hub_section: "Chain-Key Cryptography" -learn_hub_category: "How does ICP work?" -migrated: false ---- - -# Chain-Key Signatures - -The main application of _chain-key signatures_ is to enable direct interoperability with other blockchains as part of [Chain Fusion](https://learn.internetcomputer.org/hc/en-us/articles/34329023770260). Using chain-key signatures, canister smart contracts obtain control over cryptographic keys: They have a public key, from which a blockchain address on another blockchain like Bitcoin or Ethereum can be derived, and they can sign transactions relative to that address. One major application of chain-key signatures is creating [chain-key tokens](https://learn.internetcomputer.org/hc/en-us/articles/34211397080980), which are twins of tokens from other blockchains that exist on ICP. Two major examples of these are ckBTC and ckETH, representations of BTC and ETH on the Internet Computer, in which a canister smart contract cryptographically controls the bitcoin and ether that backs the ckBTC and ckETH tokens 1:1. Indeed, using chain-key signatures is the strongest, most decentralized way of integrating blockchains as no additional trust assumptions besides that of the two blockchains are required. In particular, there are no additional parties that manage signature keys or their shares. - -A key component of chain-key signatures is threshold cryptography. The threshold signature scheme used to implement [certified communication](https://learn.internetcomputer.org/hc/en-us/articles/34214090576404) for ICP is based on BLS signatures. While BLS signatures have distinct advantages, they are not used on many other blockchains. In order to work with other blockchains, the Internet Computer must use threshold signatures that are compatible with the digital signature schemes of those other blockchains. By far the most commonly used signature scheme (including Bitcoin and Ethereum) is the [ECDSA signature scheme](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm). Because of this, _threshold ECDSA_ signatures have been the first ones to be supported on the IC. Subsequently, support for [Schnorr signatures](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki) as used by Bitcoin has been added, enabling full use of Bitcoin features that depend on Taproot, such as [Ordinals](https://www.bitcoin.com/get-started/what-are-bitcoin-ordinals/). The recently added support for [EdDSA signatures](https://en.wikipedia.org/wiki/EdDSA) unlocks integration with blockchains like Solana, TON, or Cardano. - -## Threshold ECDSA - -Implementing a secure and efficient threshold signing protocol for ECDSA is much more challenging than for BLS signatures. While there has been a flurry of [research on threshold ECDSA in recent years](https://eprint.iacr.org/2020/1390), none of these protocols meet the demanding requirements of the Internet Computer: they all either assume a _synchronous network_ (meaning that the protocols will fail or become insecure if messages are unexpectedly delayed) or provide _no robustness_(meaning that the ability to produce signatures is completely lost if a _single_ node should crash) or _both_. Neither of these assumptions are acceptable on the IC: security and liveness must hold even in an _asynchronous network_ with many faulty nodes. - -The DFINITY R&D team has designed, analyzed, and implemented a new threshold ECDSA signing protocol that works over an _asynchronous network_ and is quite _robust_ (it will still produce signatures if up to a third of the nodes in a subnet are crashed or corrupt) while still delivering acceptable performance. This signing protocol has been published in two research papers that [describe the protocol in detail](https://eprint.iacr.org/2022/506) and [prove the key elements of its security](https://eprint.iacr.org/2021/1330). The NNS DAO decided to adopt threshold ECDSA on the Internet Computer and to roll it out, such that canister smart contracts are able to have an ECDSA public key. - -## Threshold Schnorr and EdDSA - -The Schnorr signature scheme, of which EdDSA is a variant, is more amenable to being adapted to a threshold protocol than the ECDSA signature scheme. Consequently, the threshold signing protocols for Schnorr and EdDSA implemented in ICP are simplified variants of the ECDSA signing protocol, and inherit the property of robustness in an asynchronous network. - diff --git a/.migration/learn-hub/how-does-icp-work/chain-key-cryptography/subnet-keys-and-subnet-signatures.md b/.migration/learn-hub/how-does-icp-work/chain-key-cryptography/subnet-keys-and-subnet-signatures.md deleted file mode 100644 index 4dbb9e8..0000000 --- a/.migration/learn-hub/how-does-icp-work/chain-key-cryptography/subnet-keys-and-subnet-signatures.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -learn_hub_id: 34209540682644 -learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34209540682644-Subnet-Keys-and-Subnet-Signatures" -learn_hub_title: "Subnet Keys and Subnet Signatures" -learn_hub_section: "Chain-Key Cryptography" -learn_hub_category: "How does ICP work?" -migrated: false ---- - -# Subnet Keys and Subnet Signatures - -Each subnet on ICP manages cryptographic keys that are used in several parts of the protocol: - - * An unbiased random beacon determines the block maker in each consensus round. - * Messages to other subnets are signed and can be validated by the receiving subnet based on knowledge of only the public key of the sending subnet, which enables horizontal scalability of ICP. - * Client applications can validate information retrieved from the subnet using only the public key of the subnet, enabling these applications to be resource-efficient (even run as part of a standard website) and fully trustworthy. - * Each canister has access to an unbiased and unpredictable source of randomness. - - - -## Threshold BLS Signatures - -The threshold signature scheme implemented by the IC for the above-mentioned tasks is a threshold version of the well-known [BLS signature scheme](https://en.wikipedia.org/wiki/BLS_digital_signature). One reason for using the BLS signature scheme is that it is the only one that yields a threshold signing protocol that is very simple and efficient. Indeed, a machine holding a share of the secret signing key can very easily generate a share of a signature on a message, and these signature shares can be combined to form a BLS signature on a message – no further interaction between these machines is required. - -Another reason for using the BLS signature scheme is that signatures are _unique_ , meaning that for a given public key and message, there is only one valid signature on that message. This unique-signature property is essential for the application to generating unpredictable and unbiased pseudo-random numbers for smart contracts: after a smart contract requests a pseudo-random number (and not before!), a signature on a special message is generated, and this signature is passed through a hash function to derive a seed from which the required pseudo-random numbers are generated. By the security property of the signature scheme, neither this seed nor the derived pseudo-random numbers can be predicted or biased. - -## Distributed Key Generation - -While signing with threshold BLS is quite straightforward, designing a secure, decentralized protocol for generating and distribution the shares of the secret signing key – that is, a DKG, or Distributed Key Generation protocol – remains a challenge. While there has been quite a bit of research on DKG design, the vast majority of DKG protocols in the literature do not meet the demanding requirements of the Internet Computer, in that they either assume a _synchronous network_ (meaning that the protocols will fail or become insecure if messages are unexpectedly delayed) or provide _no robustness_ (meaning that the ability to produce signatures is completely lost if a _single_ node should crash) or _both_. Neither of these assumptions are acceptable on the IC: security and liveness must hold even an _asynchronous network_ with many faulty nodes. - -DFINITY has designed, analyzed, and implemented [a new DKG protocol](https://eprint.iacr.org/2021/339) that works over an _asynchronous network_ and is quite _robust_ (it will still succeed if up to a third of the nodes in a subnet are crashed or corrupt) while still delivering acceptable performance. In addition to generating a new key, this protocol can also be used to reshare an existing key. This functionality is essential to enable autonomous evolution of the IC topology as subnet membership changes over time. - diff --git a/docs/concepts/certified-data.md b/docs/concepts/certified-data.md new file mode 100644 index 0000000..eba99a4 --- /dev/null +++ b/docs/concepts/certified-data.md @@ -0,0 +1,60 @@ +--- +title: "Certified Data" +description: "How ICP enables clients to verify query responses with a single public key check" +sidebar: + order: 11 +--- + +Query calls on ICP return results immediately without going through consensus. This means the response comes from a single replica, and a client cannot inherently distinguish a legitimate response from a fabricated one. Certified data solves this: by embedding cryptographic certificates in query responses, canisters can prove that their response reflects state that was committed through consensus, without the client needing to replay any historical state. + +## The verification problem + +Traditional verification approaches require significant client-side work. Bitcoin's Simplified Payment Verification downloads and validates block headers. Ethereum's light clients maintain a chain of committee hashes and verify Merkle proofs against the state root. Both approaches require ongoing synchronization and are impractical for mobile or web applications that need fast, lightweight verification. + +ICP takes a different approach: instead of requiring clients to track any chain state, the protocol produces a certificate that can be verified with a single signature check against a **single, stable public key** (the Internet Computer's root public key). This key never changes (it was fixed at genesis and is published in the NNS governance system), so any client can embed it and immediately verify any certificate it receives. + +## How certificates are produced + +Each subnet holds a threshold BLS signing key. The corresponding subnet public key is registered on the NNS and derivable from the IC root public key. At each consensus round, the subnet computes a **certified state tree**: a hash tree representing the replicated state of all canisters on that subnet, then signs the root hash of this tree with its threshold BLS key. + +The signed root is included in the subnet's **certified state**, which is available to every replica. When a canister wants to certify a response, it embeds a piece of certified state in the response, along with a Merkle path (witness) proving that the certified piece is included under the signed root. + +The result is a certificate that carries: +- the subnet's threshold BLS signature over the state tree root +- a chain of NNS signatures linking the subnet public key back to the IC root key +- a witness (Merkle path) from the signed root to the specific canister value + +Verifying this chain of signatures requires only the IC root public key. No block header downloads, no committee tracking, no ongoing synchronization. + +## Certified variables + +The interface through which canisters participate in this mechanism is **certified variables**: + +- During an **update call** (which goes through consensus), the canister calls `certified_data_set` with a 32-byte value. The subnet includes this value in its certified state at the end of the consensus round. +- During a **query call**, the canister reads back the certificate (the subnet's signature over the certified state tree) and returns it to the caller along with the canister's response. + +The 32-byte limitation is not a problem in practice. Applications use standard data structures like [Merkle trees](https://en.wikipedia.org/wiki/Merkle_tree) to commit to arbitrarily large amounts of data in a single 32-byte root hash. The canister stores the full data structure locally and returns a Merkle witness (a path from the root to the requested value) alongside the certificate in each query response. The client verifies both the certificate signature and the witness together. + +This pattern allows canisters to provide both fast responses (query, no consensus delay) and cryptographic authentication, a combination that most distributed systems cannot offer without full state replay. + +## Applications + +Certified data is used throughout ICP for exactly this reason: + +- **Certified variables in canisters.** Any canister can certify its state for client verification. See the [Certified variables guide](../guides/backends/certified-variables.md) for how to implement this. +- **Certified assets.** The asset canister uses certified variables to produce certified HTTP responses. When a browser fetches a page served by an ICP canister, the HTTP gateway verifies the certificate before serving the response, so the browser sees only content that was committed through consensus. +- **Internet Identity.** The Internet Identity service certifies its delegations, so clients can verify that an authentication delegation is authentic without trusting the individual replica that served the query. + +## Relationship to chain-key cryptography + +Certified data is one of the core applications of [chain-key cryptography](chain-key-cryptography.md). The threshold BLS signature property that makes certified data possible is the same one that enables fast response verification at the top level: a single subnet public key is enough to verify any response from that subnet, because the private key is never held by any single node and the signature is produced collectively by the subnet's nodes through threshold BLS. + +The unique-signature property of BLS is also essential here: for a given message and key, exactly one valid BLS signature exists. This means no subset of nodes can produce a different certificate for the same state, even if they collude. + +## Next steps + +- [Certified variables guide](../guides/backends/certified-variables.md): implement certified responses in a canister +- [Chain-key cryptography](chain-key-cryptography.md): the threshold BLS signatures that power this system +- [Network overview](network-overview.md): how subnet nodes produce the certified state tree + + diff --git a/docs/concepts/chain-key-cryptography.md b/docs/concepts/chain-key-cryptography.md index bcc916d..883dc87 100644 --- a/docs/concepts/chain-key-cryptography.md +++ b/docs/concepts/chain-key-cryptography.md @@ -1,22 +1,22 @@ --- title: "Chain-Key Cryptography" -description: "Threshold signatures that enable cross-chain integration, fast verification, and chain evolution" +description: "Threshold signatures that enable crosschain integration, fast verification, and chain evolution" sidebar: order: 9 --- -Chain-key cryptography is a set of threshold cryptographic protocols that underpin the Internet Computer. Instead of any single node holding a private key, keys are split into shares distributed across the nodes of a [subnet](network-overview.md). Nodes collaboratively sign messages without ever reconstructing the full key: and this single capability enables everything from fast response verification to canisters signing transactions on Bitcoin, Ethereum, and dozens of other blockchains. +Chain-key cryptography is a set of threshold cryptographic protocols that underpin the Internet Computer. Instead of any single node holding a private key, keys are split into shares distributed across the nodes of a [subnet](network-overview.md). Nodes collaboratively sign messages without ever reconstructing the full key: and this single capability enables everything from fast response verification to canisters signing transactions on Bitcoin, Ethereum, and dozens of other chains. ## Why threshold cryptography matters -On most blockchains, verifying state requires replaying transactions or trusting a full node. On ICP, verifying a response means checking **one signature against one public key**: regardless of how many nodes produced it. This is possible because each subnet holds a threshold BLS key: any sufficiently large subset of nodes can produce a valid signature, but no smaller group can forge one. +On traditional distributed networks, verifying state requires replaying transactions or trusting a full node. On ICP, verifying a response means checking **one signature against one public key**: regardless of how many nodes produced it. This is possible because each subnet holds a threshold BLS key: any sufficiently large subset of nodes can produce a valid signature, but no smaller group can forge one. This design has several consequences for developers: - **Fast verification.** Clients verify subnet responses with a single public key check. There is no need to download block headers or maintain a light client. -- **Certified data.** Canisters can set certified variables that the subnet signs at each block. Query responses that include these certificates are cryptographically authenticated, bridging the gap between fast queries and trusted updates. See [Certified variables](../guides/backends/certified-variables.md). +- **Certified data.** Canisters can set certified variables that the subnet signs at each block. Query responses that include these certificates are cryptographically authenticated, bridging the gap between fast queries and trusted updates. See [Certified data](certified-data.md) for the conceptual explanation and [Certified variables](../guides/backends/certified-variables.md) for the implementation guide. - **Verifiable randomness.** The threshold BLS scheme produces unique signatures: for a given message and key, only one valid signature exists. ICP exploits this property to generate unpredictable, unbiased random numbers that canisters can consume. See [Verifiable randomness](verifiable-randomness.md). -- **Cross-chain signing.** Canisters can request threshold ECDSA and Schnorr signatures, giving them the ability to control addresses and sign transactions on external blockchains. This is the foundation of [Chain Fusion](chain-fusion.md). +- **Crosschain signing.** Canisters can request threshold ECDSA and Schnorr signatures, giving them the ability to control addresses and sign transactions on external chains. This is the foundation of [Chain Fusion](chain-fusion.md). ## Core protocols @@ -24,7 +24,7 @@ Chain-key cryptography is not a single algorithm but a protocol suite. The main ### Distributed key generation (DKG) -Before a subnet can sign anything, its nodes must collectively generate a key whose shares are distributed among them. ICP uses a novel DKG protocol that works over an **asynchronous network** and tolerates up to one-third of nodes being faulty. The same protocol handles **key resharing**: transferring key material to a new set of nodes when subnet membership changes: without ever reconstructing the private key. Resharing also runs periodically within a subnet to defend against adaptive attackers: each resharing invalidates all previously obtained shares, so compromising nodes over time does not help an adversary accumulate enough shares to forge signatures. +Before a subnet can sign anything, its nodes must collectively generate a key whose shares are distributed among them. ICP uses a novel DKG protocol that works over an **asynchronous network** and tolerates up to one-third of nodes being faulty. The same protocol handles **key resharing**: transferring key material to a new set of nodes when subnet membership changes (for example, during node rotation), without ever reconstructing the private key. Resharing ensures that shares held by removed nodes become useless, so the subnet's signing ability is preserved across membership changes while old shares cannot be exploited. ### Threshold BLS signatures @@ -37,7 +37,7 @@ BLS was chosen for two properties: ### Chain-key signatures (threshold ECDSA and Schnorr) -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 blockchains. +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: @@ -54,6 +54,14 @@ Each scheme is backed by a pair of management canister methods: See the [Management canister reference](../references/management-canister.md#chain-key-signing) for the full API, and the [IC interface specification](../references/ic-interface-spec/index.md) for the authoritative protocol-level details. +#### Why threshold ECDSA is harder than threshold BLS + +Threshold signing for BLS is straightforward because BLS signature shares can be combined non-interactively: each node signs independently and the shares are aggregated with no further communication. ECDSA has no such property; producing a threshold ECDSA signature requires a multi-round interactive protocol among the signing nodes. + +Existing threshold ECDSA protocols in academic literature all assume either a synchronous network (messages must arrive within a bounded time) or offer no robustness against node crashes. Neither assumption is acceptable for ICP: security and liveness must hold over an asynchronous network with up to one-third of nodes faulty. ICP implements a novel threshold ECDSA protocol that is both asynchronous and robust, with formal security proofs published in [protocol design](https://eprint.iacr.org/2022/506) and [security analysis](https://eprint.iacr.org/2021/1330) papers. + +Threshold Schnorr (including Ed25519) protocols are simplified variants of the ECDSA signing protocol. They inherit the same asynchronous-network and robustness properties. + ### Key derivation 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. @@ -62,9 +70,9 @@ For ECDSA and BIP340, key derivation uses a generalized form of [BIP-32](https:/ 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. -Because the derivation algorithm is deterministic and uses only public parameters (the master public key, the canister principal, and the derivation path), public key derivation can also be performed **offline**: no management canister call or network connection required. This is useful for building explorers, dashboards, or address-derivation tools that need a canister's public key or blockchain address without a live ICP connection. See the [offline key derivation guide](../guides/chain-fusion/offline-key-derivation.md) for TypeScript and Rust libraries. +Because the derivation algorithm is deterministic and uses only public parameters (the master public key, the canister principal, and the derivation path), public key derivation can also be performed **offline**: no management canister call or network connection required. This is useful for building explorers, dashboards, or address-derivation tools that need a canister's public key or network address without a live ICP connection. See the [offline key derivation guide](../guides/chain-fusion/offline-key-derivation.md) for TypeScript and Rust libraries. - + ### Pre-signatures @@ -91,7 +99,7 @@ For signing costs, see [Cycles costs](../references/cycles-costs.md). ## Supported chains -Any blockchain whose transaction authentication uses ECDSA (secp256k1) or Schnorr signatures (BIP340 over secp256k1, or Ed25519) can be integrated with ICP through chain-key signatures. For the full list of supported chains with integration methods and chain-key tokens, see [Chain Fusion: Supported chains](chain-fusion.md#supported-chains). +Any chain whose transaction authentication uses ECDSA (secp256k1) or Schnorr signatures (BIP340 over secp256k1, or Ed25519) can be integrated with ICP through chain-key signatures. For the full list of supported chains with integration methods and chain-key digital assets, see [Chain Fusion: Supported chains](chain-fusion.md#supported-chains). ## Chain evolution @@ -104,8 +112,9 @@ For more on how upgrades work at the protocol level, see the [Chain Evolution](h ## Next steps - [Chain Fusion](chain-fusion.md): how canisters use chain-key signatures to interact with other blockchains +- [Certified data](certified-data.md): how the subnet's threshold BLS key enables certified query responses - [Ethereum integration](../guides/chain-fusion/ethereum.md): using threshold ECDSA with Ethereum and EVM chains - [VetKeys](vetkeys.md): a related cryptographic primitive for onchain encryption - [Management canister reference](../references/management-canister.md): the threshold signing API - + diff --git a/docs/concepts/index.md b/docs/concepts/index.md index 8944cc1..f3e8005 100644 --- a/docs/concepts/index.md +++ b/docs/concepts/index.md @@ -24,6 +24,7 @@ Understand the ideas behind the Internet Computer before you build on it. These ## Cryptography and cross-chain - **[Chain-Key Cryptography](chain-key-cryptography.md)**: Threshold signatures that enable cross-chain integration, fast finality, and chain evolution. +- **[Certified Data](certified-data.md)**: How canisters certify query responses using the subnet's threshold BLS key. - **[Chain Fusion](chain-fusion.md)**: How ICP connects to Bitcoin, Ethereum, Solana, and other blockchains natively. - **[VetKeys](vetkeys.md)**: Verifiable encrypted threshold key derivation for onchain encryption and secret management. diff --git a/docs/concepts/security.md b/docs/concepts/security.md index ef23dff..22be00f 100644 --- a/docs/concepts/security.md +++ b/docs/concepts/security.md @@ -2,7 +2,7 @@ title: "Security Model" description: "The IC security model: canister isolation, trust boundaries, and the threat model for app developers" sidebar: - order: 12 + order: 13 --- The Internet Computer provides strong security guarantees at the protocol level: replicated execution, threshold cryptography, and deterministic state machines. But the protocol cannot prevent bugs in your code. Understanding where the platform's guarantees end and your responsibilities begin is essential for building secure apps. @@ -87,7 +87,7 @@ See [Upgrade safety](../guides/security/canister-upgrades.md) for patterns that ### Controller risk -Canister controllers can change the code, extract funds, or delete the canister at any time. If a single person or team controls a canister that holds user assets, users must trust that entity completely. For applications where this trust is unacceptable, control can be transferred to a DAO (such as an [SNS](../guides/governance/launching.md)) or the canister can be made immutable by removing all controllers. +Canister controllers can change the code, extract funds, or delete the canister at any time. If a single person or team controls a canister that holds user assets, users must trust that entity completely. For applications where this trust is unacceptable, control can be transferred to an [SNS](../guides/governance/launching.md) or the canister can be made immutable by removing all controllers. Users can verify a canister's controllers through the IC dashboard or by querying the canister's information via a `read_state` request. diff --git a/docs/concepts/vetkeys.md b/docs/concepts/vetkeys.md index e27d660..9a96171 100644 --- a/docs/concepts/vetkeys.md +++ b/docs/concepts/vetkeys.md @@ -2,7 +2,7 @@ title: "VetKeys" description: "Verifiable encrypted threshold key derivation for encryption and secret management on ICP" sidebar: - order: 11 + order: 12 --- VetKeys (verifiably encrypted threshold keys) give canisters the ability to derive secret key material on demand, without any node or canister ever seeing the raw key. The protocol that underpins this capability is called vetKD: verifiable encrypted threshold key derivation. diff --git a/docs/guides/backends/certified-variables.md b/docs/guides/backends/certified-variables.md index 2fafb61..1f08272 100644 --- a/docs/guides/backends/certified-variables.md +++ b/docs/guides/backends/certified-variables.md @@ -7,7 +7,7 @@ sidebar: Query calls on ICP are answered by a single replica without going through consensus. This means a malicious or faulty replica could return fabricated data. **Certified variables** solve this: the [canister](../../concepts/canisters.md) stores a hash in the [subnet's](../../concepts/network-overview.md#subnets) certified state during an update call, and query responses include a certificate signed by the subnet's threshold BLS key, proving the data is authentic. The result is responses that are both fast (no consensus delay) and cryptographically verified. -For a conceptual overview of why query integrity matters, see [Security concepts](../../concepts/security.md). +For a conceptual explanation of how certified data works and why it matters, see [Certified data](../../concepts/certified-data.md). For the security implications, see [Security concepts](../../concepts/security.md). ## How certification works @@ -364,4 +364,4 @@ See [Frontend certification](../../guides/frontends/certification.md) for the as - [IC Interface Specification: Certified Data](../../references/ic-interface-spec/canister-interface.md#system-api-certified-data): the certified data system API - [IC Interface Specification: Certification](../../references/ic-interface-spec/certification.md): certificate format and delegation - +