@icp-sdk/vetkeys - v0.5.0
    Preparing search index...

    Class EncryptedMaps

    The EncryptedMaps frontend library facilitates interaction with an EncryptedMaps-enabled canister on the Internet Computer (ICP). It allows web applications to securely store, retrieve, and manage encrypted key-value pairs within named maps while handling user access control and key sharing.

    • Encrypted Key-Value Storage: Store and retrieve encrypted key-value pairs within named maps.
    • Retrieve Encrypted VetKeys: Fetch encrypted VetKeys and decrypt them locally using a transport secret key.
    • Shared Maps Access Information: Query which maps a user has access to.
    • Manage User Access: Assign, modify, and revoke user rights on stored maps.
    • Retrieve VetKey Verification Key: Fetch the public verification key for validating VetKeys.
    • Access Rights should be carefully managed to prevent unauthorized access.
    • VetKeys should be decrypted only in trusted environments such as user browsers to prevent leaks.
    • Derived key material is cached in memory by default (InMemoryDerivedKeyMaterialCache), so it never touches disk and is discarded on page reload. Persisting it across reloads with IndexedDbDerivedKeyMaterialCache is an explicit, opt-in trade-off: the persisted handle is non-extractable, but any same-origin code can use it to decrypt without an authenticated session for as long as it is stored.
    • The cache belongs to a single authenticated identity. Identity lifecycle is the caller's responsibility, so to avoid serving one identity's key material to another on the same origin:
    Index

    Constructors

    constructor

    Properties

    canisterClient verificationKey

    Methods

    clearCache decryptFor encryptFor getAccessibleSharedMapNames getAllAccessibleMaps getAllAccessibleValues getDerivedKeyMaterial getDerivedKeyMaterialOrFetchIfNeeded getOwnedNonEmptyMapNames getSharedUserAccessForMap getUserRights getValue getValuesForMap getVetkeyVerificationKey removeEncryptedValue removeMapValues removeUser setUserRights setValue

    Constructors

    • Creates a new instance of the EncryptedMaps client.

      Parameters

      Returns EncryptedMaps

      import { EncryptedMaps } from "@icp-sdk/vetkeys/encrypted_maps";

      const encryptedMaps = new EncryptedMaps(encryptedMapsClientInstance);

      import {
          EncryptedMaps,
          IndexedDbDerivedKeyMaterialCache,
      } from "@icp-sdk/vetkeys/encrypted_maps";

      const encryptedMaps = new EncryptedMaps(encryptedMapsClientInstance, {
          // Namespace the store per identity so one identity's cached keys are
          // never served to another on the same origin.
          cache: new IndexedDbDerivedKeyMaterialCache(`vetkeys-${myPrincipal}`),
      });
      // Remember to call encryptedMaps.clearCache() on logout / identity change.

    Properties

    canisterClient: EncryptedMapsClient

    The client instance for interacting with the EncryptedMaps canister.

    verificationKey: Uint8Array<ArrayBufferLike> = undefined

    The cached verification key for validating encrypted VetKeys.

    Methods

    • Clears all cached derived key material.

      Strongly recommended on logout or whenever the authenticated identity changes: the cache belongs to a single identity, so clearing it (or discarding the EncryptedMaps instance) prevents one identity's key material from being served to another, and drops the still-usable decryption capability that otherwise lingers. This matters most with IndexedDbDerivedKeyMaterialCache, where cached key handles persist across sessions until cleared.

      Returns Promise<void>

    • Decrypts a value for a specific map and key.

      Parameters

      • mapOwner: Principal

        The principal of the map owner

      • mapName: Uint8Array

        The name/identifier of the map

      • mapKey: Uint8Array

        The key to decrypt for

      • encryptedValue: Uint8Array

        The value to decrypt

      Returns Promise<Uint8Array<ArrayBufferLike>>

      Promise resolving to the decrypted value

    • Encrypts a value for a specific map and key.

      Parameters

      • mapOwner: Principal

        The principal of the map owner

      • mapName: Uint8Array

        The name/identifier of the map

      • mapKey: Uint8Array

        The key to encrypt for

      • cleartext: Uint8Array

        The value to encrypt

      Returns Promise<Uint8Array<ArrayBufferLike>>

      Promise resolving to the encrypted value

    • Retrieves a list of maps that were shared with the user and the user still has access to.

      Returns Promise<[Principal, Uint8Array<ArrayBufferLike>][]>

      Promise resolving to an array of [Principal, Uint8Array] pairs representing accessible map identifiers.

      const sharedMaps = await encryptedMaps.getAccessibleSharedMapNames();
      console.log("Shared Maps:", sharedMaps);

    • Retrieves all accessible maps with their decrypted values.

      Returns Promise<MapData[]>

      Promise resolving to an array of map data

    • Retrieves all accessible values across all maps the user has access to.

      Returns Promise<
          [
              [Principal, Uint8Array<ArrayBufferLike>],
              [Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>][],
          ][],
      >

      Promise resolving to an array of map data with decrypted values

    • Derives a key material for a specific map.

      Parameters

      • mapOwner: Principal

        The principal of the map owner

      • mapName: Uint8Array

        The name/identifier of the map

      Returns Promise<DerivedKeyMaterial>

      Promise resolving to the derived key material

      Error if the operation fails

    • Gets or fetches the derived key material for a map.

      Parameters

      • mapOwner: Principal

        The principal of the map owner

      • mapName: Uint8Array

        The name/identifier of the map

      Returns Promise<DerivedKeyMaterial>

      Promise resolving to the derived key material

    • Retrieves a list of non-empty maps owned by the caller.

      Returns Promise<Uint8Array<ArrayBufferLike>[]>

      Promise resolving to an array of map names

    • Gets all users that have access to a map and their access rights.

      Parameters

      • owner: Principal

        The principal of the map owner

      • mapName: Uint8Array

        The name/identifier of the map

      Returns Promise<[Principal, AccessRights][]>

      Promise resolving to an array of user-access rights pairs

      Error if the operation fails

    • Checks a user's access rights.

      Parameters

      • owner: Principal

        The principal of the map owner

      • mapName: Uint8Array

        The name/identifier of the map

      • user: Principal

        The principal of the user to check rights for

      Returns Promise<AccessRights>

      Promise resolving to the user's access rights if they exist

      const userRights = await encryptedMaps.getUserRights(owner, mapName, user);
      console.log("User Access Rights:", userRights);

      Error if the operation fails

    • Retrieves and decrypts a stored value from a map.

      Parameters

      • mapOwner: Principal

        The principal of the map owner

      • mapName: Uint8Array

        The name/identifier of the map

      • mapKey: Uint8Array

        The key to retrieve

      Returns Promise<Uint8Array<ArrayBufferLike>>

      Promise resolving to the decrypted value

      const mapOwner = Principal.fromText("aaaaa-aa");
      const mapName = "passwords";
      const mapKey = "email_account";

      const storedValue = await encryptedMaps.getValue(mapOwner, mapName, mapKey);
      console.log("Decrypted Value:", new TextDecoder().decode(storedValue));

      Error if the operation fails

    • Retrieves all values from a specific map.

      Parameters

      • mapOwner: Principal

        The principal of the map owner

      • mapName: Uint8Array

        The name/identifier of the map

      Returns Promise<[Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>][]>

      Promise resolving to an array of key-value pairs

      Error if the operation fails

    • Retrieves the public verification key for validating encrypted VetKeys. The vetkeys obtained via getVetkey are verified using this key, and, therefore, this method is not needed for using getVetkey.

      Returns Promise<Uint8Array<ArrayBufferLike>>

      Promise resolving to the verification key bytes

      const verificationKey = await encryptedMaps.getVetkeyVerificationKey();
      console.log("Verification Key:", verificationKey);

    • Removes a value from a map.

      Parameters

      • mapOwner: Principal

        The principal of the map owner

      • mapName: Uint8Array

        The name/identifier of the map

      • mapKey: Uint8Array

        The key to remove

      Returns Promise<Uint8Array<ArrayBufferLike>>

      Promise resolving to the removed value if it existed

      Error if the operation fails

    • Removes all values from a map.

      Parameters

      • mapOwner: Principal

        The principal of the map owner

      • mapName: Uint8Array

        The name/identifier of the map

      Returns Promise<Uint8Array<ArrayBufferLike>[]>

      Promise resolving to an array of removed keys

      Error if the operation fails

    • Revokes a user's access.

      Parameters

      • owner: Principal

        The principal of the map owner

      • mapName: Uint8Array

        The name/identifier of the map

      • user: Principal

        The principal of the user to remove

      Returns Promise<AccessRights>

      Promise resolving to the previous access rights if they existed

      const removalResult = await encryptedMaps.removeUser(owner, mapName, user);
      console.log("User Removed:", removalResult);

      Error if the operation fails

    • Grants or modifies access rights for a user.

      Parameters

      • owner: Principal

        The principal of the map owner

      • mapName: Uint8Array

        The name/identifier of the map

      • user: Principal

        The principal of the user to grant/modify rights for

      • userRights: AccessRights

        The access rights to grant

      Returns Promise<AccessRights>

      Promise resolving to the previous access rights if they existed

      const owner = Principal.fromText("aaaaa-aa");
      const user = Principal.fromText("bbbbbb-bb");
      const accessRights = { ReadWrite: null };

      const result = await encryptedMaps.setUserRights(
        owner,
        mapName,
        user,
        accessRights,
      );
      console.log("Access Rights Updated:", result);

      Error if the operation fails

    • Stores an encrypted value in a map.

      Parameters

      • mapOwner: Principal

        The principal of the map owner

      • mapName: Uint8Array

        The name/identifier of the map

      • mapKey: Uint8Array

        The key to store

      • data: Uint8Array

        The value to store

      Returns Promise<Uint8Array<ArrayBufferLike>>

      Promise resolving to the previous value if it existed

      const value = new TextEncoder().encode("my_secure_password");
      const result = await encryptedMaps.setValue(mapOwner, mapName, mapKey, value);
      console.log("Replaced Value:", result);

      Error if the operation fails

    Settings

    Member Visibility

    On This Page

    Core FeaturesSecurity Considerations
    Constructors
    Properties
    Methods