dfinity/icskills

encrypted-maps

Add access-controlled, end-to-end encrypted key-value storage to a canister with the vetKeys EncryptedMaps library (ic-vetkeys for Rust and Motoko backends, @icp-sdk/vetkeys for the frontend).

查看源码

使用方法

  1. 复制安装命令,在自己的智能体环境安装前先检查源码包。
  2. 从原始文档核对所需工具、凭据和支持的宿主。
  3. 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/dfinity/icskills --skill encrypted-maps

开始前需了解

  • 安装不包含模型订阅、API 额度或访问文件的权限。
  • 仓库星数和安装量反映活跃情况,不等于独立质量或安全测试。
仓库原始内容

按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。

Encrypted Maps (vetKeys)

EncryptedMaps is a ready-made vetKeys library for access-controlled, end-to-end encrypted key-value storage. Each map is owned by a principal and holds mapKey → value entries; values are encrypted on the client under a vetKey and the canister only ever stores ciphertext. Owners share maps with other principals at three access levels. This is the default starting point for any encrypted-storage app (password manager, encrypted notes, vault).

Use the `vetkeys` skill instead when you need lower-level primitives: identity-based encryption (IBE), threshold BLS signatures, timelock encryption, or your own symmetric-key scheme.

LayerRustMotokoFrontend
Packageic-vetkeys 0.9ic-vetkeys 0.6 (moc ≥ 1.13.0, core ≥ 2.6.1)@icp-sdk/vetkeys 0.7
Backendexport_encrypted_maps_canister! macroEncryptedMapsCanister mixin@icp-sdk/vetkeys/encrypted_maps
Use @icp-sdk/vetkeys (≥0.7), not the legacy @dfinity/vetkeys (frozen at 0.4). 0.5 and 0.6 carried @icp-sdk/core as a plain dependency and could nest a second copy of it; 0.7 peers it as ^5 || ^6, with an identical API. Frontend agent/identity come from @icp-sdk/core, not @dfinity/agent.

Concepts

  • Map — identified by (mapOwner: Principal, mapName: bytes). Contains mapKey → encryptedValue entries. mapName and mapKey are byte arrays, max 32 bytes each.
  • Access rights — Read, ReadWrite, ReadWriteManage (manage = may grant/revoke others). The owner always has full rights.
  • Client-side encryption — the frontend fetches a per-map vetKey and encrypts/decrypts locally; the canister enforces access control and stores ciphertext. Sharing a map re-encrypts the map key for the new user automatically.
  • Key name & domain separator are immutable once any value is encrypted — they feed key derivation, so changing them makes stored values undecryptable. See pitfalls.

Backend — the whole canister in a few lines

The generator emits the #[init]/#[post_upgrade], the stable state, and every endpoint the @icp-sdk/vetkeys frontend expects — so the Candid matches the client by construction. Do not hand-write the ~200 lines of delegation.

Rust — export_encrypted_maps_canister!

rust
use ic_stable_structures::memory_manager::{MemoryId, MemoryManager, VirtualMemory};
use ic_stable_structures::DefaultMemoryImpl;
use std::cell::RefCell;

type Memory = VirtualMemory<DefaultMemoryImpl>;

thread_local! {
    static MEMORY_MANAGER: RefCell<MemoryManager<DefaultMemoryImpl>> =
        RefCell::new(MemoryManager::init(DefaultMemoryImpl::default()));
}

fn memory(id: u8) -> Memory {
    MEMORY_MANAGER.with(|m| m.borrow().get(MemoryId::new(id)))
}

// Arg 1: the domain separator that isolates this app's derived keys (keep it
// stable forever). Then four Memory instances, in order: domain-separator config,
// access control, shared keys, encrypted values.
ic_vetkeys::export_encrypted_maps_canister!(
    "password_manager_app",
    [memory(0), memory(1), memory(2), memory(3)],
);

ic_cdk::export_candid!();

The generated #[init] takes the vetKD key name (test_key_1 / key_1) as a String argument — pass it via init_args in icp.yaml.

Motoko — EncryptedMapsCanister mixin

motoko
import EncryptedMapsCanister "mo:ic-vetkeys/encrypted_maps/Canister";
import EncryptedMaps "mo:ic-vetkeys/encrypted_maps/EncryptedMaps";
import Types "mo:ic-vetkeys/Types";
import Runtime "mo:core/Runtime";

persistent actor PasswordManager {
  // `transient`: the key name is baked into `encryptedMapsState` at install and never re-read.
  transient let keyName = Runtime.envVar<system>("VETKD_KEY_NAME") ?? "test_key_1";

  // Arg 2 is the domain separator; like the key name it must stay stable for the life of the canister.
  let encryptedMapsState = EncryptedMaps.newEncryptedMapsState<Types.AccessRights>(
    { curve = #bls12_381_g2; name = keyName },
    "password_manager_app",
  );

  // The mixin contributes the full endpoint set (vetKD key, access control, map-name, value endpoints)
  // as snake_case methods, exactly what the frontend client calls.
  include EncryptedMapsCanister(encryptedMapsState);
};

In a persistent actor the encryptedMapsState binding is stable and persists across upgrades with no stable keyword; the actor owns it, so it stays a plain, migratable variable. Set VETKD_KEY_NAME at deploy time via canister settings (see the icp-cli skill).

Frontend (TypeScript)

typescript
import { HttpAgent, type Identity } from "@icp-sdk/core/agent";
import { safeGetCanisterEnv } from "@icp-sdk/core/agent/canister-env";
import {
  DefaultEncryptedMapsClient,
  EncryptedMaps,
  IndexedDbDerivedKeyMaterialCache,
  type AccessRights,
} from "@icp-sdk/vetkeys/encrypted_maps";

export async function createEncryptedMaps(
  identity: Identity, canisterId: string, host: string,
): Promise<EncryptedMaps> {
  // rootKey from the canister env (never fetchRootKey() in shipped code); undefined on mainnet
  const rootKey = safeGetCanisterEnv()?.IC_ROOT_KEY;
  const agent = await HttpAgent.create({ identity, host, rootKey });
  // Since 0.5.0 derived key material is cached in memory only by default.
  // Opt into cross-reload persistence, namespaced by principal; clearCache() on logout.
  const cache = new IndexedDbDerivedKeyMaterialCache(`vetkeys-${identity.getPrincipal().toText()}`);
  return new EncryptedMaps(new DefaultEncryptedMapsClient(agent, canisterId), { cache });
}
typescript
const owner = myPrincipal;                              // Principal from @icp-sdk/core/principal
const mapName = new TextEncoder().encode("my-vault");   // ≤ 32 bytes
const mapKey  = new TextEncoder().encode("github.com"); // ≤ 32 bytes

// Store / read / remove (encryption happens client-side)
await encryptedMaps.setValue(owner, mapName, mapKey, new TextEncoder().encode("s3cr3t"));
const value = await encryptedMaps.getValue(owner, mapName, mapKey); // Uint8Array (empty if absent)
await encryptedMaps.removeEncryptedValue(owner, mapName, mapKey);

// Share the map with another principal (AccessRights is a Candid variant, not a string)
const rights: AccessRights = { ReadWrite: null };        // or { Read: null } / { ReadWriteManage: null }
await encryptedMaps.setUserRights(owner, mapName, otherPrincipal, rights);
const theirRights = await encryptedMaps.getUserRights(owner, mapName, otherPrincipal);

// Everything the caller can access (owned + shared)
const maps = await encryptedMaps.getAllAccessibleMaps();

await encryptedMaps.clearCache();                        // on logout / identity switch

KeyManager — the layer beneath (use only when EncryptedMaps doesn't fit)

EncryptedMaps is built on `KeyManager`, which derives and shares access-controlled vetKeys keyed by name. Reach for KeyManager directly only when you need access-controlled key derivation (e.g. handing each client a per-resource symmetric or IBE key to use themselves) rather than encrypted key-value storage — most apps want EncryptedMaps.

Caveat: there is no ready-made canister generator for KeyManager yet (dfinity/vetkeys#422) — unlike EncryptedMaps, you wire the endpoints by hand. In Rust, ic_vetkeys::key_manager::KeyManager::init takes the domain separator, the VetKDKeyId, and three Memory instances (config, access control, shared keys), and exposes get_vetkey_verification_key, get_encrypted_vetkey, get_user_rights, set_user_rights, remove_user. Motoko mirrors this via KeyManager.newKeyManagerState + the KeyManager class; the frontend uses @icp-sdk/vetkeys/key_manager (KeyManager + DefaultKeyManagerClient).

Pitfalls

  1. Use the generator, don't hand-write endpoints. Rust export_encrypted_maps_canister!, Motoko include EncryptedMapsCanister(state). Hand-written delegation drifts from the Candid the frontend client expects and breaks silently.
  1. Domain separator and vetKD key name are immutable once data exists. Both feed key derivation; changing either makes every stored value undecryptable. In Motoko the VETKD_KEY_NAME env var is captured into stable state at first install — editing it on a later upgrade is silently ignored (only a reinstall, which drops all data, switches keys). Because test_key_1 is also a valid mainnet key, a production deploy that forgets to set VETKD_KEY_NAME silently runs on it — assert the expected key at deploy time.
  1. Derived key material is in-memory by default since 0.5.0 (was IndexedDB). Pass IndexedDbDerivedKeyMaterialCache to persist it across reloads, and call clearCache() on logout / identity change. Old @dfinity/vetkeys 0.1–0.4 IndexedDB entries remain at rest after upgrading — clear them once.
  1. Client construction changed. DefaultEncryptedMapsClient takes a ready HttpAgent (await HttpAgent.create({ identity, host, rootKey })), not HttpAgentOptions. Agent/identity come from @icp-sdk/core.
  1. `AccessRights` is a Candid variant, not a string — { ReadWrite: null }, not "ReadWrite". Three levels: Read, ReadWrite, ReadWriteManage.
  1. `mapName` and `mapKey` are byte arrays, ≤ 32 bytes each — encode strings with TextEncoder.
  1. Keep per-value app state consistent via the control-plane variant. If you store metadata alongside each value, use custom_value_endpoints (Rust) / EncryptedMapsControlPlaneCanister (Motoko) and own the value endpoints — see references/metadata.md. Don't also expose the library's raw value mutators, or the two stores desync.
  1. Don't re-init state on upgrade. The macro/mixin generate the lifecycle hooks; stable memory survives upgrades. Adding your own post_upgrade that rebuilds state corrupts it.
  1. Cycles. vetkd_derive_key (used under the hood) costs cycles — test_key_1 and key_1 cost the same locally and on mainnet, and the library attaches the right amount (excess refunded). Keep the canister funded. (See the vetkeys skill for the cost table.)

Additional References

  • Metadata / custom value endpoints: references/metadata.md
  • Lower-level vetKeys (IBE, BLS, timelock, symmetric, offline derivation): the `vetkeys` skill
  • Canonical examples: motoko/vetkeys/password_manager, rust/vetkeys/password_manager in dfinity/examples

Deploy & verify

Provisioning and generic deploy steps belong to the `icp-cli` skill. EncryptedMaps-specific checks:

bash
icp deploy backend                                         # local replica provisions test_key_1
# From the frontend: setValue then getValue round-trips the plaintext for the owner;
# a principal without rights gets an access-control error on getValue.
来自同一仓库

更多 Skills

全部 Skills
dfinity
社区

autoupgrade-icp-cli

One-time installer that keeps a project's Internet Computer CLI toolchain current. Sets up a SessionStart hook plus a script that compares the installed icp and ic-wasm against the latest release and either reports the upgrade or applies it, using whichever channel each tool was installed from (npm, Homebrew, or the shell installer). Use when a user wants to install, bootstrap, or enable automatic icp-cli / ic-wasm updates, asks to stop running an outdated icp, asks how to upgrade or check the v

1小时安装量
1
GitHub Stars
39
最近更新
11月11日
dfinity
社区

buy-cycles

Buy cycles with a credit card for the CLI's own identity with icp cycles buy, through CyclePay's on-chain gateway, then continue deploying. Use when a mainnet deploy or canister creation fails for lack of cycles, the user has no ICP, no wallet or no exchange account, or asks to pay for cycles by card, Stripe, fiat or USD. Do NOT use for converting ICP you already hold (cycles-management: icp cycles mint), for topping up a canister from an existing balance, or for Internet Identity sign-in (agent

1小时安装量
1
GitHub Stars
39
最近更新
11月11日
dfinity
社区

canhelp

Display a human-readable summary of a canister's interface given its mainnet canister ID or a human-readable name. Like --help but for canisters. Only for mainnet canisters — for local canisters, read the generated .did file in your project directly.

1小时安装量
1
GitHub Stars
39
最近更新
11月11日
dfinity
社区

canister-security

IC-specific security patterns for canister development in Motoko and Rust. Covers access control, anonymous principal rejection, reentrancy prevention (CallerGuard pattern), async safety (saga pattern), callback trap handling, cycle drain protection, and safe upgrade patterns. Use when writing or modifying any canister that modifies state, handles tokens, makes inter-canister calls, or implements access control.

1小时安装量
1
GitHub Stars
39
最近更新
11月11日