encrypted-maps

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Encrypted Maps (vetKeys)

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
Package
ic-vetkeys
0.9
ic-vetkeys
0.6 (moc ≥ 1.13.0, core ≥ 2.6.1)
@icp-sdk/vetkeys
0.7
Backend
export_encrypted_maps_canister!
macro
EncryptedMapsCanister
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
.
EncryptedMaps
是一个现成的 vetKeys 库,用于支持访问控制的端到端加密键值存储。每个 map 均由一个 principal 拥有,并保存
mapKey → value
条目;值在客户端基于 vetKey 加密,而 canister 仅存储密文。所有者可以按三种访问级别将 map 共享给其他 principals。这是所有加密存储应用(密码管理器、加密笔记、金库)的默认起点。
当你需要更底层的原语时,请改用
vetkeys
skill
:identity-based encryption(IBE)、threshold BLS signatures、timelock encryption,或你自己的 symmetric-key scheme。
层级RustMotoko前端
包
ic-vetkeys
0.9
ic-vetkeys
0.6(moc ≥ 1.13.0,core ≥ 2.6.1)
@icp-sdk/vetkeys
0.7
后端
export_encrypted_maps_canister!
宏
EncryptedMapsCanister
mixin
@icp-sdk/vetkeys/encrypted_maps
使用
@icp-sdk/vetkeys
(≥0.7),不要使用冻结在 0.4 的旧版
@dfinity/vetkeys
。0.5 和 0.6 将
@icp-sdk/core
作为普通依赖项引入,因此可能会嵌套第二份副本;0.7 使用
^5 || ^6
将其作为 peer dependency,且 API 保持不变。前端 agent/identity 来自
@icp-sdk/core
,而不是
@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.
  • Map — 通过
    (mapOwner: Principal, mapName: bytes)
    标识。包含
    mapKey → encryptedValue
    条目。
    mapName
    和
    mapKey
    均为字节数组,每个最长 32 字节。
  • Access rights —
    Read
    、
    ReadWrite
    、
    ReadWriteManage
    (manage 表示可以授予或撤销他人的权限)。所有者始终拥有完整权限。
  • 客户端加密 — 前端获取每个 map 对应的 vetKey,并在本地进行加密和解密;canister 负责强制执行访问控制并存储密文。共享 map 时,会自动为新用户重新加密 map key。
  • 一旦有任何值被加密,密钥名称与 domain separator 就不可更改 — 二者都会参与密钥派生,因此更改它们会导致已存储的值无法解密。请参阅常见问题。

Backend — the whole canister in a few lines

后端——几行代码构建整个 canister

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.
生成器会生成
#[init]
/
#[post_upgrade]
、稳定状态,以及
@icp-sdk/vetkeys
前端所期望的所有 endpoint,因此从结构上保证 Candid 与客户端一致。不要手写约 200 行的 delegation 代码。

Rust —
export_encrypted_maps_canister!

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
.
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!();
生成的
#[init]
接受 vetKD 密钥名称(
test_key_1
/
key_1
)作为
String
参数——请通过
icp.yaml
中的
init_args
传入。

Motoko —
EncryptedMapsCanister
mixin

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).
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);
};
在
persistent actor
中,
encryptedMapsState
绑定是稳定的,升级后无需使用
stable
关键字即可持久化;actor 拥有它,因此它仍是普通且可迁移的变量。部署时通过 canister 设置配置
VETKD_KEY_NAME
(请参阅
icp-cli
skill)。

Frontend (TypeScript)

前端(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
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)

KeyManager——底层能力(仅在 EncryptedMaps 不适用时使用)

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
).
EncryptedMaps
构建于
KeyManager
之上,后者按名称派生并共享支持访问控制的 vetKeys。只有当你需要支持访问控制的密钥派生(例如,为每个客户端提供按资源划分的对称密钥或 IBE 密钥供其自行使用),而不是加密键值存储时,才应直接使用
KeyManager
——大多数应用都需要
EncryptedMaps
。
注意:目前尚未提供适用于 KeyManager 的现成 canister 生成器(dfinity/vetkeys#422)——与 EncryptedMaps 不同,你需要手动连接各个 endpoint。在 Rust 中,
ic_vetkeys::key_manager::KeyManager::init
接受 domain separator、
VETKDKeyId
和三个
Memory
实例(配置、访问控制、共享密钥),并公开
get_vetkey_verification_key
、
get_encrypted_vetkey
、
get_user_rights
、
set_user_rights
、
remove_user
。Motoko 通过
KeyManager.newKeyManagerState
和
KeyManager
class 提供对应能力;前端使用
@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.
  2. 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.
  3. 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.
  4. Client construction changed.
    DefaultEncryptedMapsClient
    takes a ready
    HttpAgent
    (
    await HttpAgent.create({ identity, host, rootKey })
    ), not
    HttpAgentOptions
    . Agent/identity come from
    @icp-sdk/core
    .
  5. AccessRights
    is a Candid variant, not a string
    —
    { ReadWrite: null }
    , not
    "ReadWrite"
    . Three levels:
    Read
    ,
    ReadWrite
    ,
    ReadWriteManage
    .
  6. mapName
    and
    mapKey
    are byte arrays, ≤ 32 bytes each
    — encode strings with
    TextEncoder
    .
  7. 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.
  8. 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.
  9. 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.)
  1. 使用生成器,不要手写 endpoint。 Rust 使用
    export_encrypted_maps_canister!
    ,Motoko 使用
    include EncryptedMapsCanister(state)
    。手写 delegation 会逐渐偏离前端客户端所期望的 Candid,并且会在悄无声息中导致故障。
  2. 一旦已有数据,domain separator 和 vetKD 密钥名称便不可更改。 二者都会参与密钥派生;更改任意一个都会导致所有已存储的值无法解密。在 Motoko 中,
    VETKD_KEY_NAME
    环境变量会在首次安装时被捕获到稳定状态中——后续升级时修改它会被静默忽略(只有
    reinstall
    才会切换密钥,而这会删除所有数据)。由于
    test_key_1
    同时也是有效的主网密钥,生产环境部署时若忘记设置
    VETKD_KEY_NAME
    ,就会悄无声息地使用它运行——请在部署时断言预期的密钥。
  3. 从 0.5.0 开始,派生密钥材料默认仅缓存在内存中(此前使用 IndexedDB)。传入
    IndexedDbDerivedKeyMaterialCache
    以在页面重新加载后继续持久化,并在退出登录或切换 identity 时调用
    clearCache()
    。升级后,旧的
    @dfinity/vetkeys
    0.1–0.4 IndexedDB 条目仍会保留在磁盘上——请一次性清除。
  4. 客户端构造方式已经改变。
    DefaultEncryptedMapsClient
    接受已创建的
    HttpAgent
    (
    await HttpAgent.create({ identity, host, rootKey })
    ),而不是
    HttpAgentOptions
    。Agent/identity 来自
    @icp-sdk/core
    。
  5. AccessRights
    是 Candid variant,而不是字符串
    ——应使用
    { ReadWrite: null }
    ,而不是
    "ReadWrite"
    。共有三个级别:
    Read
    、
    ReadWrite
    、
    ReadWriteManage
    。
  6. mapName
    和
    mapKey
    是字节数组,每个最长 32 字节
    ——请使用
    TextEncoder
    编码字符串。
  7. 通过 control-plane 变体保持每个值的应用状态一致。 如果要在每个值旁存储元数据,请使用
    custom_value_endpoints
    (Rust)或
    EncryptedMapsControlPlaneCanister
    (Motoko),并自行实现 value endpoints——请参阅
    references/metadata.md
    。不要同时暴露库原生的 value mutators,否则两个存储区会失去同步。
  8. 升级时不要重新初始化状态。 宏或 mixin 会生成生命周期 hooks,稳定内存会在升级后继续保留。添加自己的
    post_upgrade
    并重新构建状态会破坏已有状态。
  9. Cycles。 底层使用的
    vetkd_derive_key
    会消耗 cycles——
    test_key_1
    和
    key_1
    在本地及主网上的成本相同,库会附加正确的 cycles 数量(超出部分会退还)。请确保 canister 拥有充足资金。(费用表请参阅
    vetkeys
    skill。)

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
  • 元数据/自定义 value endpoints:
    references/metadata.md
  • 更底层的 vetKeys(IBE、BLS、timelock、对称加密、离线派生):
    vetkeys
    skill
  • 规范示例:dfinity/examples 中的
    motoko/vetkeys/password_manager
    、
    rust/vetkeys/password_manager

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
资源准备和通用部署步骤属于
icp-cli
skill。EncryptedMaps 专属检查如下:
bash
icp deploy backend                                         # local replica provisions test_key_1

From the frontend: setValue then getValue round-trips the plaintext for the owner;

From the frontend: setValue then getValue round-trips the plaintext for the owner;

a principal without rights gets an access-control error on getValue.

a principal without rights gets an access-control error on getValue.

undefined
undefined