@dfinity/vetkeys - v0.1.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.
    import { EncryptedMaps } from "@dfinity/vetkeys/encrypted_maps";

    // Initialize the EncryptedMaps Client
    const encryptedMaps = new EncryptedMaps(encryptedMapsClientInstance);

    // Retrieve shared maps
    const sharedMaps = await encryptedMaps.getAccessibleSharedMapNames();

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

    // Store an encrypted value
    const value = new TextEncoder().encode("my_secure_password");
    const result = await encryptedMaps.setValue(mapOwner, mapName, mapKey, value);

    // Retrieve a stored value
    const storedValue = await encryptedMaps.getValue(mapOwner, mapName, mapKey);

    // Manage user access rights
    const user = Principal.fromText("bbbbbb-bb");
    const accessRights = { ReadWrite: null };
    const result = await encryptedMaps.setUserRights(mapOwner, mapName, user, accessRights);
    Index

    Constructors

    constructor

    Properties

    canisterClient verificationKey

    Methods

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

    Constructors

    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

    • 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.get_user_rights(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.remove_user(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