Cryptography - Internet Computer

The Internet Computer’s cryptography component provides the security foundations for the entire protocol. This includes chain-key cryptography, threshold signatures, key management, and various cryptographic primitives used throughout the system.

Overview

The crypto component is organized into several layers:

Crypto Component

Main interface used by replicas for all cryptographic operations

Threshold Signatures

BLS12-381 based threshold signatures for consensus and certification

Chain-Key Crypto

Threshold ECDSA/Schnorr for signing transactions on other chains

TLS & Node Keys

Transport security and node identity management

The cryptography implementation is located in rs/crypto/ with the main component in src/ and supporting libraries in subdirectories.

Architecture

The crypto component is structured as follows:

Crypto Component (rs/crypto/src/)
├── SecretKeyStore: Manages and protects secret keys
├── Public Interfaces: TLS, signing, verification
└── Internal Implementation (rs/crypto/internal/)
    ├── Crypto Service Provider (CSP)
    ├── Threshold Signature Schemes
    └── Basic Signature Schemes

Key Components

Crypto Component
Internal Libraries
Public Crates

Location: rs/crypto/src/The main interface used by replica components:

Manages secret keys through SecretKeyStore
Provides signing and verification operations
Handles TLS connections
Interfaces with consensus and other components

// From rs/crypto/README.adoc:
// "Crypto Component used by a replica. It contains
// SecretKeyStore, which manages and protects the
// secret keys owned by a node."

Location: rs/crypto/internal/Implementation of cryptographic primitives:

Should not be used directly outside /crypto/
Contains actual cryptographic algorithms
Provides low-level crypto operations
Optimized for security and performance

WebAssembly-compatible utilities:

ic-crypto-sha: SHA256, SHA224 hashing
ic-crypto-tree-hash: Hash trees and witnesses
ic-crypto-node-key-validation: Node key validation
ic-crypto-utils-*: Signature utilities

Chain-Key Cryptography

Chain-key cryptography is a cornerstone innovation of the Internet Computer, enabling:

Single public key for the entire IC
Fast finality and certified queries
Threshold signatures without key reconstruction
Integration with other blockchains (Bitcoin, Ethereum)

Threshold Signatures (BLS12-381)

The IC uses BLS signatures on the BLS12-381 curve for:

Consensus

Random beacon and block finalization:

// Nodes collectively sign blocks
// Threshold of signatures creates valid block signature
// Single signature verifiable against subnet public key

Certification

State certification and query responses:

// Subnet signs state root hash
// Queries return certified responses
// Clients verify against subnet public key

DKG (Distributed Key Generation)

Non-interactive DKG for key generation:

// Nodes generate key shares without interaction
// Threshold of shares can produce signatures
// Public key computed from commitments

From rs/crypto/internal/crypto_lib/threshold_sig/bls12_381/:

Forward-secure encryption for dealing
NIZK proofs for correctness
Complaint mechanism for cheating dealers

Properties

Non-Interactive

Key generation doesn’t require synchronous communication rounds

Threshold Security

Requires t+1 of n shares to produce signatures

Unique Signatures

Each message has exactly one valid signature

Efficient Verification

Single signature verification regardless of signers

Chain-Key Signatures

The IC can sign transactions for other blockchains using threshold cryptography:

Threshold ECDSA

Overview
Key Derivation
Signing Process

Enables canisters to have ECDSA keys and sign transactions:Supported Curves:

secp256k1 (Bitcoin, Ethereum)
secp256r1 (Enterprise applications)

Use Cases:

Bitcoin integration
Ethereum interoperability
Cross-chain DeFi
Multi-chain wallets

Hierarchical key derivation for canisters:

// Each canister can derive multiple keys
// Derivation path includes:
// - Master key ID
// - Canister ID
// - Derivation path (BIP32-like)

// From rs/crypto/internal/crypto_lib/threshold_sig/
//      canister_threshold_sig/src/signing/key_derivation.rs

Threshold signing workflow:

Canister requests signature via System API
Request goes to subnet with threshold key
Nodes perform multi-party computation
Signature shares are combined
Final signature returned to canister

Signing operations have higher latency (several seconds) due to threshold protocol execution.

Threshold Schnorr

Support for Schnorr signatures:

BIP-340 for Bitcoin Taproot
Ed25519 for other applications
Similar threshold protocol to ECDSA
Optimized for specific use cases

// From rs/crypto/internal/crypto_lib/threshold_sig/
//      canister_threshold_sig/src/signing/
// - ecdsa.rs: ECDSA signing
// - bip340.rs: Schnorr BIP-340
// - eddsa.rs: Ed25519 signing

Internet Computer Distributed Key Generation (IDKG)

IDKG is the protocol for generating and managing threshold keys:

Dealing Phase

Dealers create and distribute encrypted key shares:

// Each dealer creates polynomial commitments
// Encrypts shares for each receiver
// Includes zero-knowledge proofs

Verification Phase

Receivers verify dealings:

// Check NIZK proofs
// Verify encryption correctness
// Submit complaints if invalid

Transcript Creation

Consensus on valid dealings:

// Aggregate dealings from threshold of dealers
// Create transcript with public verification data
// Receivers can now reconstruct key shares

Key Derivation

Generate signing keys from transcript:

// Each node derives its key share
// Public key computed from transcript
// Ready for threshold signing

Protocol Features:

Resharing

Transfer key shares to new node set without revealing the key

Multiple Keys

Support multiple threshold keys on same subnet

Forward Security

Old key shares cannot recover future keys

Verifiable

All operations include cryptographic proofs

Key Management

SecretKeyStore

The crypto component manages node secret keys:

// From rs/crypto/src/
// SecretKeyStore provides:
// - Secure storage of secret keys
// - Key generation
// - Access control
// - Key rotation support

Stored Keys:

Node signing keys (Ed25519)
Committee signing keys (multi-signature)
DKG encryption keys (forward-secure)
TLS certificate keys
Threshold key shares

Node Key Validation

Validation of node public keys:

// rs/crypto/node_key_validation/
// - Verify key format and validity
// - Check key uniqueness
// - Validate cryptographic properties
// - Used during node registration

The ic-crypto-node-key-validation crate is WebAssembly-compatible and can be used in canisters.

Cryptographic Primitives

Hashing

SHA-2 Family
Hash Trees
Hash-to-Curve

Location: rs/crypto/sha/Standard hash functions:

// SHA-256: 256-bit output
// SHA-224: Truncated SHA-256
// Used for: General hashing, IDs, commitments

Location: rs/crypto/tree_hash/Merkle tree construction:

// Labeled hash trees for state
// Witnesses for certified queries
// Partial tree reconstruction

// From rs/crypto/README.adoc:
// ic-crypto-tree-hash: "computation of hash
// trees and witnesses"

Location: rs/crypto/internal/crypto_lib/threshold_sig/canister_threshold_sig/Hashing to elliptic curve points:

// Used in threshold ECDSA
// Deterministic point generation
// Domain separation

Signature Schemes

Scheme	Use Case	Location
BLS12-381	Threshold signatures, consensus, certification	`rs/crypto/internal/crypto_lib/threshold_sig/bls12_381/`
Ed25519	Node signatures, basic authentication	`rs/crypto/internal/crypto_lib/basic_sig/ed25519/`
ECDSA	Threshold signing for Bitcoin, Ethereum	`rs/crypto/internal/crypto_lib/threshold_sig/canister_threshold_sig/`
Schnorr	Bitcoin Taproot, alternative signatures	`rs/crypto/internal/crypto_lib/threshold_sig/canister_threshold_sig/`

TLS and Transport Security

Node-to-Node Communication

All replica communication is secured with TLS:

// rs/crypto/tls_interfaces/
// - TLS handshake interfaces
// - Certificate validation
// - Secure channel establishment

// Features:
// - Mutual authentication
// - Forward secrecy
// - Certificate-based node identity

Registry Integration

Crypto keys are stored in the Registry:

Node public keys
Subnet threshold keys
DKG transcripts
Certificate chains

// Registry provides:
// - Key distribution
// - Version history
// - Access to all nodes

Cryptographic Tests

The crypto component includes extensive testing:

Unit Tests

Located throughout rs/crypto/ for individual components:

// Tests/: Various protocol tests
// - Integration tests
// - Protocol correctness
// - Error handling

Benchmarks

Performance testing in benches/:

// rs/crypto/benches/
// - Signing performance
// - Verification speed
// - Key generation time

Stability Tests

Ensure consistent behavior:

// rs/crypto/internal/crypto_lib/threshold_sig/
//     bls12_381/tests/stability.rs
// - Serialization stability
// - Cross-version compatibility

Usage Examples

Threshold Signing (Canister)

// Canister requests ECDSA signature
let args = SignWithECDSAArgs {
    message_hash: hash,
    derivation_path: vec![canister_id.as_bytes()],
    key_id: EcdsaKeyId {
        curve: EcdsaCurve::Secp256k1,
        name: "key_1".to_string(),
    },
};

// Call management canister
let (signature,): (ECDSAPublicKeyResponse,) = 
    call(Principal::management_canister(), "sign_with_ecdsa", (args,))
    .await?;

Verification (Client)

use ic_crypto_tree_hash::*;

// Verify certified query response
let certificate = Certificate::from_cbor(cert_bytes)?;
let witness = Witness::from_cbor(witness_bytes)?;

// Verify against subnet public key
verifier.verify_certified_data(
    &subnet_id,
    &certificate,
    &witness,
    &data_hash,
)?;

Security Considerations

Key Protection

Secret keys stored in encrypted format
Access controlled by crypto component
Never exported from SecretKeyStore
Rotation procedures for compromised keys

Threshold Security

Requires threshold of nodes to sign
Individual node compromise doesn’t leak key
Byzantine fault tolerance (n ≥ 3f+1)
Proactive resharing for forward security

Side-Channel Resistance

Constant-time implementations
Memory protection mechanisms
Sandboxed execution
Regular security audits

Protocol Security

Formal security proofs
Zero-knowledge proofs for correctness
Complaint mechanisms
Verifiable randomness

Never use crypto internal libraries directly. Always go through the public crypto component interface.

Source Code Reference

// rs/crypto/src/
// Main crypto component used by replicas

From rs/crypto/README.adoc:

rs/crypto/
├── src/           - Main Crypto Component with SecretKeyStore
├── internal/      - Implementation (not for direct external use)
├── sha/           - ic-crypto-sha (Wasm-compatible)
├── tree_hash/     - ic-crypto-tree-hash (Wasm-compatible)  
├── node_key_validation/ - ic-crypto-node-key-validation (Wasm)
└── utils/         - Signature utilities (Wasm-compatible)

Consensus

How cryptography enables IC consensus

State Management

State certification using threshold signatures

Canisters

Using chain-key signatures in canisters

Network Nervous System

Governance and the Registry’s key management

Overview

Getting Started

Architecture

Core Components

IC-OS

Chain Integration

Development

​Overview

Crypto Component

Threshold Signatures

Chain-Key Crypto

TLS & Node Keys

​Architecture

​Key Components

​Chain-Key Cryptography

​Threshold Signatures (BLS12-381)

​Properties

Non-Interactive

Threshold Security

Unique Signatures

Efficient Verification

​Chain-Key Signatures

​Threshold ECDSA

​Threshold Schnorr

​Internet Computer Distributed Key Generation (IDKG)

Resharing

Multiple Keys

Forward Security

Verifiable

​Key Management

​SecretKeyStore

​Node Key Validation

​Cryptographic Primitives

​Hashing

​Signature Schemes

​TLS and Transport Security

​Node-to-Node Communication

​Registry Integration

​Cryptographic Tests

​Usage Examples

​Threshold Signing (Canister)

​Verification (Client)

​Security Considerations

Key Protection

Threshold Security

Side-Channel Resistance

Protocol Security

​Source Code Reference

​Related Topics

Consensus

State Management

Canisters

Network Nervous System

Build docs developers (and LLMs) love

Overview

Architecture

Key Components

Chain-Key Cryptography

Threshold Signatures (BLS12-381)

Properties

Chain-Key Signatures

Threshold ECDSA

Threshold Schnorr

Internet Computer Distributed Key Generation (IDKG)

Key Management

SecretKeyStore

Node Key Validation

Cryptographic Primitives

Hashing

Signature Schemes

TLS and Transport Security

Node-to-Node Communication

Registry Integration

Cryptographic Tests

Usage Examples

Threshold Signing (Canister)

Verification (Client)

Security Considerations

Source Code Reference

Related Topics