Loading...
Loading...
Build vetKeys cryptography on the Internet Computer via the vetKD system API and the ic-vetkeys (Rust, Motoko) and @icp-sdk/vetkeys (frontend) libraries: identity-based encryption (IBE), threshold BLS signatures, timelock encryption, symmetric key derivation, and offline public-key derivation. Use when implementing IBE, encrypting to a principal, BLS signing, sealed-bid or timelock schemes, deriving encryption keys on-chain, transport keys, or calling vetkd_public_key / vetkd_derive_key. For access-controlled encrypted key-value storage (password managers, encrypted notes), use the encrypted-maps skill instead. Not for authentication — use user-sign-in.
npx skill4agent add dfinity/icskills vetkeys(canister, context, input)| Layer | Rust | Motoko | Frontend |
|---|---|---|---|
| Package | | | |
| Management API | | | — |
| Low-level primitives | crate root ( | — (not available, see below) | package root ( |
is legacy (frozen at 0.4.0). The package was renamed to@dfinity/vetkeysat 0.5.0. Frontend agent/identity types come from@icp-sdk/vetkeys(@icp-sdk/core,@icp-sdk/core/agent), not@icp-sdk/core/principal/@dfinity/agent.@dfinity/principalUse 0.7 or later. 0.5 and 0.6 declaredas a plain dependency, so they could nest a second copy of core beside the one the app installs instead of failing; 0.7 peers it as@icp-sdk/core. The API is identical across all three.^5 || ^6
ic-cdk = "0.20"ic-cdk-management-canister = "0.1"ic-dummy-getrandom-for-wasmic-vetkeysmoc ≥ 1.13.0core ≥ 2.6.1@icp-sdk/core@^6^5 || ^6^6| You want to… | Use |
|---|---|
| Store & share encrypted key-value data (password manager, notes, vault) | |
| Encrypt to a principal so only they can decrypt (messaging) | IBE → |
| Reveal data only after a deadline (sealed-bid auction, timelock) | Timelock IBE → |
| Have the canister produce a signature verifiable by anyone | Threshold BLS → |
| Derive a per-user/per-resource symmetric (AES) key | Symmetric derivation → this file |
| Encrypt to a principal without any canister call | Offline public-key derivation → this file |
| Produce on-chain verifiable randomness | Verifiable randomness (VRF) → this file |
| Authenticate users / logins | not vetKeys — use the |
"my_app""symmetric_key"decryptAndVerifyTransportSecretKey.random()decryptAndVerifyVetKeysign_with_blssignWithBlsic-vetkeysKeyManagerEncryptedMapsMasterPublicKeyDerivedPublicKey@icp-sdk/vetkeysdecryptAndVerify| Key name | Where | |
|---|---|---|
| local + mainnet (testing) | 10_000_000_000 |
| local + mainnet (production) | 26_153_846_153 |
vetkd_public_keyvetkd_derive_keytest_key_1key_1ManagementCanister26_153_846_153aaaaa-aa#[init]init_argsicp.yamlVETKD_KEY_NAMEtest_key_1reinstalltest_key_1VETKD_KEY_NAMEvetkd_public_keyvetkd_derive_keyuse ic_cdk::update;
use ic_cdk_management_canister::{VetKDCurve, VetKDDeriveKeyArgs, VetKDKeyId, VetKDPublicKeyArgs};
const CONTEXT: &[u8] = b"symmetric_key"; // domain separator; must match on the client
fn key_id() -> VetKDKeyId {
// name comes from an #[init] arg in real code; "test_key_1" for local + mainnet testing
VetKDKeyId { curve: VetKDCurve::Bls12_381_G2, name: "test_key_1".to_string() }
}
#[update]
async fn symmetric_verification_key() -> Vec<u8> {
let res = ic_cdk_management_canister::vetkd_public_key(&VetKDPublicKeyArgs {
canister_id: None, // defaults to this canister
context: CONTEXT.to_vec(),
key_id: key_id(),
})
.await
.expect("vetkd_public_key failed");
res.public_key // no cycles required
}
#[update]
async fn encrypted_symmetric_key_for_caller(transport_public_key: Vec<u8>) -> Vec<u8> {
let caller = ic_cdk::api::msg_caller(); // capture BEFORE the await
let res = ic_cdk_management_canister::vetkd_derive_key(&VetKDDeriveKeyArgs {
input: caller.as_slice().to_vec(), // key identifier (plaintext) — never secret data
context: CONTEXT.to_vec(),
transport_public_key,
key_id: key_id(),
})
.await // the binding attaches the required cycles automatically
.expect("vetkd_derive_key failed");
res.encrypted_key
}import ManagementCanister "mo:ic-vetkeys/ManagementCanister";
import Principal "mo:core/Principal";
import Text "mo:core/Text";
import Runtime "mo:core/Runtime";
persistent actor {
// Captured into keyId at first install and fixed for the life of the canister's derived keys;
// changing VETKD_KEY_NAME on a later upgrade has no effect (see the key-name warning above).
let keyName = Runtime.envVar<system>("VETKD_KEY_NAME") ?? "test_key_1";
let keyId : ManagementCanister.VetKdKeyid = { curve = #bls12_381_g2; name = keyName };
public shared func symmetricVerificationKey() : async Blob {
// context / domain separator; no cycles required
await ManagementCanister.vetKdPublicKey(null, Text.encodeUtf8("symmetric_key"), keyId);
};
public shared ({ caller }) func encryptedSymmetricKeyForCaller(transportPublicKey : Blob) : async Blob {
// signature is (input, context, keyId, transportPublicKey); helper attaches cycles automatically
await ManagementCanister.vetKdDeriveKey(
Principal.toBlob(caller), Text.encodeUtf8("symmetric_key"), keyId, transportPublicKey);
};
};VetKeyimport { TransportSecretKey, DerivedPublicKey, EncryptedVetKey } from "@icp-sdk/vetkeys";
// `backend` is your actor; `myPrincipal` is the authenticated caller's Principal (@icp-sdk/core/principal)
// 1. Fresh transport key per request
const tsk = TransportSecretKey.random();
// 2. Fetch the encrypted derived key + the public verification key
const [encryptedKeyBytes, publicKeyBytes] = await Promise.all([
backend.encrypted_symmetric_key_for_caller(tsk.publicKeyBytes()),
backend.symmetric_verification_key(),
]);
// 3. Decrypt & verify -> VetKey. The identity bytes MUST equal the backend `input`
// (here the caller principal), or verification throws.
const vetKey = EncryptedVetKey.deserialize(new Uint8Array(encryptedKeyBytes)).decryptAndVerify(
tsk,
DerivedPublicKey.deserialize(new Uint8Array(publicKeyBytes)),
myPrincipal.toUint8Array(),
);
// 4. Derive AES-GCM key material and encrypt/decrypt. There is NO `toDerivedKeyMaterial()`.
const keyMaterial = await vetKey.asDerivedKeyMaterial();
const domainSep = "my_app:notes"; // unique per app + usage
const ciphertext = await keyMaterial.encryptMessage("secret message", domainSep, ""); // (msg, domainSep, associatedData)
const plaintext = await keyMaterial.decryptMessage(ciphertext, domainSep, "");
// new TextDecoder().decode(plaintext) === "secret message"import { MasterPublicKey } from "@icp-sdk/vetkeys";
import { Principal } from "@icp-sdk/core/principal";
const derivedPublicKey = MasterPublicKey.productionKey() // key_1 (default); MasterPublicKey.pocketicKey() for local
.deriveCanisterKey(Principal.fromText(canisterId).toUint8Array())
.deriveSubKey(new TextEncoder().encode("my_app")); // the context / domain separator
// derivedPublicKey (a DerivedPublicKey) can now be used for IBE encryption offlineuse ic_vetkeys::{MasterPublicKey, DerivedPublicKey};
use ic_cdk_management_canister::{VetKDCurve, VetKDKeyId};
let master = MasterPublicKey::for_mainnet_key(&VetKDKeyId {
curve: VetKDCurve::Bls12_381_G2,
name: "key_1".to_string(),
}).expect("unknown key name"); // for_pocketic_key(..) for local
let derived: DerivedPublicKey = master
.derive_canister_key(canister_id.as_slice())
.derive_sub_key(b"my_app");ic_vetkeys::management_canister::compute_vrf(input, context, key_id) -> VrfOutputinputcontextVrfOutput.deserialize(...)@icp-sdk/vetkeys@icp-sdk/vetkeys@dfinity/vetkeys@icp-sdk/core@icp-sdk/core/agent@icp-sdk/core/principalawait HttpAgent.create({ identity, host, rootKey })HttpAgentrootKeysafeGetCanisterEnv()@icp-sdk/core/agent/canister-envfetchRootKey()icp-clitoDerivedKeyMaterial()const dkm = await vetKey.asDerivedKeyMaterial()await dkm.encryptMessage(msg, domainSep, associatedData)await dkm.decryptMessage(ct, domainSep, associatedData)ic-cdk-management-canistervetkd_public_keyvetkd_derive_keyic_vetkeys::management_canistersign_with_blsmo:ic-vetkeys/ManagementCanistervetKdPublicKeyvetKdDeriveKeysignWithBlsblsPublicKeyactor "aaaaa-aa"vetkd_*MasterPublicKeyDerivedPublicKey@icp-sdk/vetkeysvetkd_derive_keykey_1test_key_1vetkd_public_keycontextinputcontextinputdecryptAndVerifycontextinputinputawaitic_cdk::api::msg_caller()({ caller })vetkd_derive_keyKeyManagerEncryptedMapsinputsign_with_blssignWithBlscontextinputic-dummy-getrandom-for-wasmgetrandomic_cdk::api::msg_caller()ic_cdk::caller()ic_cdk::call::Call::unbounded_wait(..).with_cycles(..)ic_cdk::api::call::call*IbeCiphertext.encrypt(publicKey, IbeIdentity.fromPrincipal(recipient), plaintext, IbeSeed.random())IbeCiphertext.deserialize(ct).decrypt(vetKey)references/ibe.mdic_vetkeys::management_canister::sign_with_blsManagementCanister.signWithBlsverifyBlsSignature(derivedPublicKey, message, signature)references/bls-signing.mdencrypted-mapsicp.yamlicp-cliicp deploy backend # local replica provisions test_key_1
icp canister call backend symmetric_verification_key '()' # non-empty BLS public-key blob
# derive needs a 48-byte transport public key from the frontend; different callers get different keys