Skip to main content

vetKD API

Verifiably encrypted threshold key derivation (vetKD) is a distributed protocol for securely deriving cryptographic keys, referred to as vetKeys. The vetKD API allows canisters to request vetKeys derived using this protocol. Since the key derivation is deterministic, the same inputs will produce the same key, allowing canisters to retrieve keys reliably. Canisters can generate an unlimited number of unique keys by providing different inputs.

Below is a summary of the vetKD API methods and their parameters, described in Candid notation.

  // Derives keys based on the provided inputs.
  vetkd_derive_key : (record {
    // Arbitrary data used to derive keys. This acts as a key identifier - different
    // inputs will result in different derived keys. The input does not need to be random.
    input : blob;
    // A domain separator to ensure that keys are derived within a specific context,
    // preventing collisions between different applications or use cases.
    context : blob;
    // The recipient’s public key, used to encrypt the derived key for secure transport.
    transport_public_key : blob;
    // The master key from which the derived key is created.
    key_id : record { curve : vetkd_curve; name : text };
  }) -> (record { encrypted_key : blob; });

  // Returns a public key that can be used to verify keys derived using `vetkd_derive_key`.
  vetkd_public_key : (record {
    // Optional. If provided, the method returns the public key associated with
    // the specified `canister_id`. If omitted (`null`), the public key for
    // the calling canister is returned.
    canister_id : opt canister_id;
    // Same as in `vetkd_derive_key`.
    context : blob;
    // Same as in `vetkd_derive_key`.
    key_id : record { curve : vetkd_curve; name : text };
  }) -> (record { public_key : blob; });

The full vetKD API specification can be found in the IC interface specification.

Available master keys​

The following key names are supported for curve bls12_381_g2:

  • key_1: Production key available on the ICP mainnet (resides on subnet pzp6e and backed up on uzr34).

  • test_key_1: Test key available on the ICP mainnet (resides on subnet fuqsr and backed up on 2fq7c).

  • dfx_test_key: Only available on the local development environment started by dfx.

Note that any canister on the ICP can use any available master key, independent of the subnet on which the canister or the key resides, because the management canister automatically redirects the calls for obtaining vetKeys to the subnet where the master key resides.

Obtaining a vetKey​

Deriving a vetKey typically involves both the frontend and backend components of a dapp, as the transport key is usually provided by the user.

vetKD protocol flow

Step 1: Implement canister endpoints​

Expose the vetKD endpoints in the backend canister API so that the frontend can retrieve and verify vetKeys.

In this example, an encoding of the caller's identity is used as part of the context parameter to VetKDDeriveKeyArgs. Since the dapp uses the caller's identity for derivation, the dapp is sure that the vetKey returned is both unique to that caller and input, and that caller is the only party which can retrieve that particular key.

Using the caller-provided input parameter, the caller can derive arbitrarily many unique vetKeys that only that user can retrieve and decrypt.

import Array "mo:base/Array";
import Blob "mo:base/Blob";
import ManagementCanister "mo:ic-vetkeys/ManagementCanister";
import Nat8 "mo:base/Nat8";
import Principal "mo:base/Principal";
import Text "mo:base/Text";

actor class () {
  let DOMAIN_SEPARATOR = Blob.toArray(Text.encodeUtf8("example-vetkd-dapp"));

  /// Derive encrypted vetKey for caller's principal.
  public shared ({caller}) func vetkd_derive_key(transportKey : Blob, input : Blob) : async Blob {
    await ManagementCanister.vetKdDeriveKey(input, context(caller), testKeyId(), transportKey)
  };

  public shared ({caller}) func publicKey() : async Blob {
    await ManagementCanister.vetKdPublicKey(null, context(caller), testKeyId())
  };

  private func testKeyId() : ManagementCanister.VetKdKeyid {
    {curve = #bls12_381_g2; name = "test_key_1"}
  };

  private func context(principal : Principal) : Blob {
    let principalBytes = Blob.toArray(Principal.toBlob(principal));
    let flattened = Array.flatten([[Nat8.fromNat(DOMAIN_SEPARATOR.size())], DOMAIN_SEPARATOR, principalBytes]);
    Blob.fromArray(flattened);
  }
}


Step 2: Generate a transport key pair and pass the transport public key to the canister​

In this step, the frontend generates a transport private key and passes the corresponding transport public key to the canister in order to obtain the encrypted vetKeys that can only be decrypted by the frontend.

import { DerivedPublicKey, TransportSecretKey, EncryptedVetKey } from "@dfinity/vetkeys";

const transportSecretKey = TransportSecretKey.random();
const canisterClient = // get canister client, usually auto-generated code from canister's candid interface
// unique `input` should be provided for each derived vetKey
// we only need one vetKey in this example, so we choose to have the simplest possible `input` - an empty vector
const input = new Uint8Array(0);
// the called canister uses the caller's principal as part of `context` when calling the management canisters `vetkd_derive_key` endpoint under the hood (see code in Step 1)
const encryptedVetKeyBytes = await canisterClient.vetkd_derive_key(transportSecretKey.publicKeyBytes(), input);
const encryptedVetKey = EncryptedVetKey(encryptedVetKeyBytes);

Step 3: Retrieve the vetKD public key from the backend canister​

Once retrieved, you must decrypt and verify the received encrypted vetKey.

// the called canister uses the caller's principal as part of `context` when calling the management canisters `vetkd_public_key` endpoint under the hood (see code in Step 1)
const publicKeyBytes = await canisterClient.vetkd_public_key();
const publicKey = DerivedPublicKey.deserialize(publicKeyBytes);
// pass `input` from Step 2 to the verification function
const vetKey = encryptedVetKey.decryptAndVerify(transportSecretKey, publicKey, input);

API fees​

The fees for the vetKD APIs are defined below. The threshold vetKD test key resides on the 13-node application subnet fuqsr, while the threshold vetKD production key resides on the 34-node-sized fiduciary subnet pzp6e. The subnet size where the vetKD key resides and the vetKeys are computed defines the resulting cost. The size of the subnet of the calling canister does not matter for the fees. For costs in USD, the USD/XDR exchange rate as of May 22, 2025, has been used.

If a canister using this feature is intended to be blackholed or used by other canisters, it's recommended to send more cycles with each call than the currently advertised cost. This ensures that, if the subnet's size increases in the future (leading to higher signature costs), the call will still succeed. Any unused cycles are automatically refunded.

Fees for deriving one vetKey using the vetkd_derive_key API of the management canister:

Key type (key name)                 Cycles                    USD                        Signing subnet (size)
Production key (key_1)  26_153_846_153              $0.0354325                  pzp6e (34)
Test key (test_key_1)10_000_000_000              $0.0135482                  fuqsr (13)

Resources​