Crypto Utilities

These are the low-level cryptographic functions used internally by the CDR SDK. You typically won’t need to call these directly unless you’re building custom decryption flows.

All crypto functions require WASM to be initialized first via initWasm().

The current Aeneid release also includes SGX attestation verification utilities, including verifyAttestation(), for checking validator attestations against expected enclave measurements and security version values.

Functions

initWasm
tdh2Encrypt
tdh2Verify
tdh2Combine
decryptPartial
parseSgxQuote
verifyAttestation
uuidToLabel

initWasm

Initializes the WebAssembly module required for all TDH2 cryptographic operations. Must be called once before any other crypto function.

Function	Type
`initWasm`	`() => Promise<void>`

Example

import { initWasm } from "@piplabs/cdr-sdk";

await initWasm();
// Now TDH2 functions are ready to use

Throws WasmNotInitializedError if you call any TDH2 function before initWasm() completes.

tdh2Encrypt

Encrypts plaintext using TDH2 threshold encryption against the DKG global public key.

Function	Type
`tdh2Encrypt`	`(params: TDH2EncryptParams) => Promise<TDH2Ciphertext>`

Parameters:

params.plaintext: Uint8Array - The data to encrypt
params.globalPubKey: Uint8Array - DKG global public key (34 bytes with Ed25519 prefix)
params.label: Uint8Array - 32-byte label binding ciphertext to a specific vault

Example

import { tdh2Encrypt, uuidToLabel } from "@piplabs/cdr-sdk";

const ciphertext = await tdh2Encrypt({
  plaintext: new TextEncoder().encode("secret"),
  globalPubKey,
  label: uuidToLabel(42),
});

TDH2Ciphertext

interface TDH2Ciphertext {
  raw: Uint8Array;   // serialized ciphertext (cb-mpc format)
  label: Uint8Array; // 32-byte context binding
}

tdh2Verify

Validates a TDH2 ciphertext without decrypting. Useful for checking integrity.

Function	Type
`tdh2Verify`	`(params: TDH2VerifyParams) => Promise<boolean>`

Parameters:

params.ciphertext: Uint8Array - The raw ciphertext bytes
params.globalPubKey: Uint8Array - DKG global public key
params.label: Uint8Array - The 32-byte label used during encryption

Example

import { tdh2Verify } from "@piplabs/cdr-sdk";

const isValid = await tdh2Verify({
  ciphertext: ciphertext.raw,
  globalPubKey,
  label: uuidToLabel(42),
});

console.log(`Ciphertext valid: ${isValid}`);

tdh2Combine

Combines threshold partial decryptions to recover the original plaintext.

Function	Type
`tdh2Combine`	`(params: TDH2CombineParams) => Promise<Uint8Array>`

Parameters:

params.ciphertext: TDH2Ciphertext - The encrypted data ({ raw, label })
params.partials: DecryptedPartial[] - Array of decrypted partials (must have >= threshold)
params.globalPubKey: Uint8Array - DKG global public key
params.label: Uint8Array - 32-byte label
params.threshold: number - Minimum number of partials required

Example

import { tdh2Combine } from "@piplabs/cdr-sdk";

const plaintext = await tdh2Combine({
  ciphertext,
  partials: decryptedPartials,
  globalPubKey,
  label: uuidToLabel(42),
  threshold: 2,
});

DecryptedPartial

interface DecryptedPartial {
  name: string;         // validator name: key in the access structure
  pubShare: Uint8Array; // 34 bytes (Ed25519 with 0x043f prefix)
  partial: Uint8Array;  // raw decrypted partial bytes
}

decryptPartial

Decrypts a single encrypted partial decryption from a validator using ECIES (ECDH + HKDF + AES-256-GCM).

Function	Type
`decryptPartial`	`(params: DecryptPartialParams) => Promise<Uint8Array>`

Parameters:

params.encryptedPartial: Uint8Array - The encrypted partial (nonce || ciphertext || tag)
params.ephemeralPubKey: Uint8Array - Validator’s ephemeral public key (65 bytes, uncompressed secp256k1)
params.recipientPrivKey: Uint8Array - Your ephemeral private key (32 bytes, secp256k1)

Example

import { decryptPartial } from "@piplabs/cdr-sdk";

const rawPartial = await decryptPartial({
  encryptedPartial: partialBytes,
  ephemeralPubKey: validatorEphemeralPubKey,
  recipientPrivKey: myEphemeralPrivKey,
});

ECIES Protocol:

ECDH: sharedPoint = secp256k1(recipientPrivKey, ephemeralPubKey)
HKDF-SHA256: aesKey = hkdf(sha256, sharedSecret, info="dkg-tdh2-partial", 32)
AES-256-GCM: decrypt with 12-byte nonce from the encrypted partial

verifyAttestation

Verifies a validator SGX attestation document against the expected enclave measurements and minimum security version checks. Use it with the data returned by observer.getValidatorAttestations() when your application wants an explicit MRENCLAVE, MRSIGNER, and SVN trust check. Parameters:

report: Uint8Array - Raw SGX DCAP Quote v3 bytes
config.expectedMrEnclave (optional): `0x${string}` - Expected enclave measurement
config.expectedMrSigner (optional): `0x${string}` - Expected signer measurement
config.minSecurityVersion (optional): number - Minimum allowed ISV SVN

Example

import { verifyAttestation } from "@piplabs/cdr-sdk";

const result = await verifyAttestation(report, {
  expectedMrEnclave: "0x51c08cf3...",
  expectedMrSigner: "0xa6f9d44c...",
  minSecurityVersion: 1,
});

if (!result.valid) {
  console.error(result.error);
}

verifyAttestation() performs client-side field checks. The quote signature chain itself is verified on-chain; this helper is an extra allowlist / policy check for SDK consumers.

parseSgxQuote

Parses the key fields from an SGX DCAP Quote v3 without applying any policy.

Function	Type
`parseSgxQuote`	`(report: Uint8Array) => { mrEnclave, mrSigner, securityVersion }`

Parameters:

report: Uint8Array - Raw SGX DCAP Quote v3 bytes

Returns:

mrEnclave: `0x${string}` - Parsed enclave measurement
mrSigner: `0x${string}` - Parsed signer measurement
securityVersion: number - Parsed ISV SVN

Example

import { parseSgxQuote } from "@piplabs/cdr-sdk";

const fields = parseSgxQuote(report);
console.log(fields.mrEnclave);
console.log(fields.mrSigner);
console.log(fields.securityVersion);

uuidToLabel

Derives a deterministic 32-byte label from a vault UUID. Used to bind ciphertext to a specific vault.

Function	Type
`uuidToLabel`	`(uuid: number) => Uint8Array`

Parameters:

uuid: number - The vault UUID (uint32)

Returns a 32-byte Uint8Array: 28 zero bytes followed by the 4-byte big-endian UUID.

Example

import { uuidToLabel } from "@piplabs/cdr-sdk";

const label = uuidToLabel(42);
// Uint8Array(32) [0, 0, ..., 0, 0, 0, 0, 42]

Get Started

CDR SDK

Protocol SDK (IP & Licensing)

Crypto Utilities