@dfinity/certificate-verification
TypeScript icon, indicating that this package has built-in type declarations

2.6.0 • Public • Published

Certificate Verification

Certificate verification on the Internet Computer is the process of verifying that a canister's response to a query call has gone through consensus with other replicas hosting the same canister.

This package partially encapsulates the protocol for such verification. It performs the following actions:

  • Decoding of the certificate and the canister provided tree
  • Verification of the certificate's root of trust
  • Verification of the certificate's delegations (if any)
  • Decoding of a canister provided merkle tree
  • Verification that the canister provided merkle tree's root hash matches the canister's certified data

Usage

In the following example, canister is an actor created with @dfinity/agent-js for a canister with the following candid:

type certified_response = record {
  "data" : nat32;
  "certificate" : blob;
  "witness" : blob;
};

service : {
  "get_data" : () -> (certified_response) query;
};

Check ic-certification for details on how to create certificate and witness inside your canister.

calculateDataHash is a userland provided function that can calculate the hash of the data returned from the canister. This must be calculated in the same way on the canister and the frontend.

const { data, certificate, witness } = await canister.get_data();

const tree = await verifyCertification({
  canisterId: Principal.fromText(canisterId),
  encodedCertificate: new Uint8Array(certificate).buffer,
  encodedTree: new Uint8Array(witness).buffer,
  rootKey: agent.rootKey,
  maxCertificateTimeOffsetMs: 50000,
});

const treeDataHash = lookup_path(['count'], tree);
const responseDataHash = calculateDataHash(data);

if (treeDataHash !== responseDataHash) {
  // The data returned from the canister does not match the certified data.
}

Examples

See the certified counter example for a full e2e example of how to create a certification and verify it using this package.

/@dfinity/certificate-verification/

    Package Sidebar

    Install

    npm i @dfinity/certificate-verification

    Weekly Downloads

    24

    Version

    2.6.0

    License

    Apache-2.0

    Unpacked Size

    16.7 kB

    Total Files

    9

    Last publish

    Collaborators

    • keplervital
    • dfx-json
    • dfn_wndlng
    • nathan.mcgrath.dfinity
    • frederikrothenberger
    • bitdivine
    • ielashi
    • dayyildiz
    • eric-swanson-dfinity
    • krpeacock
    • npm-dfinity-org