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).

Ver código-fonte

Como usar

  1. Copie o comando e verifique o pacote antes de instalar no seu ambiente de agente.
  2. Consulte no original as ferramentas, credenciais e ambientes necessários.
  3. Descreva os dados de entrada e a entrega esperada; confira a saída com as fontes.
npx skills add https://github.com/dfinity/icskills --skill encrypted-maps

Antes de começar

  • A instalação não inclui assinatura de modelo, franquia API ou acesso aos seus arquivos.
  • Estrelas e instalações indicam atividade, não um teste independente de qualidade ou segurança.
Documento original do Skill

Renderizado do repositório de origem, preservando títulos, exemplos, código, tabelas, links e imagens.

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.
do mesmo repositório

Mais Skills

Todos os Skills
dfinity
Comunidade

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

Instalações / 1h
1
GitHub Stars
39
Atualizado
11 de nov.
dfinity
Comunidade

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

Instalações / 1h
1
GitHub Stars
39
Atualizado
11 de nov.
dfinity
Comunidade

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.

Instalações / 1h
1
GitHub Stars
39
Atualizado
11 de nov.
dfinity
Comunidade

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.

Instalações / 1h
1
GitHub Stars
39
Atualizado
11 de nov.