@pqc-sdk/core / pqc

Variable: pqc

const pqc: object

SDK entry point: post-quantum hybrid encryption and digital signatures with safe defaults, zero configuration.

Type Declaration

decrypt

decrypt: (ciphertext, secretKey) => Promise<Uint8Array<ArrayBufferLike>>

Decrypts a ciphertext produced by encrypt. If the ciphertext was tampered with or the key does not match, it throws PqcError with code DECRYPTION_FAILED — it never returns corrupted data.

Parameters

ciphertext

Uint8Array

secretKey

SecretKey<"ml-kem-768">

Returns

Promise<Uint8Array<ArrayBufferLike>>

Example

import { pqc } from '@pqc-sdk/core';

const plaintext = await pqc.decrypt(ciphertext, pair.secretKey);
new TextDecoder().decode(plaintext);

encrypt

encrypt: (data, publicKey) => Promise<Uint8Array<ArrayBufferLike>>

Hybrid encryption: encapsulates a secret with ML-KEM-768 (FIPS 203) and encrypts the data with AES-256-GCM using that secret. The result is a single self-contained Uint8Array that only decrypt can open.

Parameters

data

string | Uint8Array<ArrayBufferLike>

publicKey

PublicKey<"ml-kem-768">

Returns

Promise<Uint8Array<ArrayBufferLike>>

Example

import { pqc } from '@pqc-sdk/core';

const pair = await pqc.keys.generate();
const ciphertext = await pqc.encrypt('sensitive data', pair.publicKey);

keys

readonly keys: object

keys.deserialize

deserialize: {(serialized): PqcKey; <A, U>(serialized, expected): PqcKey<A, U>; }

Call Signature

(serialized): PqcKey

Rebuilds a key from the serialize format. Validates version, algorithm, use and length; on any problem it throws PqcError with code INVALID_SERIALIZED_KEY or INVALID_KEY.

Pass expected to assert the algorithm and use, getting back a narrow key type (e.g. PublicKey<'ml-kem-768'>) that drops straight into encrypt / sign without an as never cast. A mismatch throws WRONG_ALGORITHM or WRONG_KEY_USE.

Parameters

serialized

string

Returns

PqcKey

Example

import { pqc } from '@pqc-sdk/core';

const token = pqc.keys.serialize((await pqc.keys.generate()).publicKey);
// Narrow to a typed key by asserting the expected algorithm and use:
const publicKey = pqc.keys.deserialize(token, { algorithm: 'ml-kem-768', use: 'public' });
const ciphertext = await pqc.encrypt('payload', publicKey);

Call Signature

<A, U>(serialized, expected): PqcKey<A, U>

Rebuilds a key from the serialize format. Validates version, algorithm, use and length; on any problem it throws PqcError with code INVALID_SERIALIZED_KEY or INVALID_KEY.

Pass expected to assert the algorithm and use, getting back a narrow key type (e.g. PublicKey<'ml-kem-768'>) that drops straight into encrypt / sign without an as never cast. A mismatch throws WRONG_ALGORITHM or WRONG_KEY_USE.

Type Parameters

A

A extends Algorithm

U

U extends KeyUse

Parameters

serialized

string

expected

ExpectedKey<A, U>

Returns

PqcKey<A, U>

Example

import { pqc } from '@pqc-sdk/core';

const token = pqc.keys.serialize((await pqc.keys.generate()).publicKey);
// Narrow to a typed key by asserting the expected algorithm and use:
const publicKey = pqc.keys.deserialize(token, { algorithm: 'ml-kem-768', use: 'public' });
const ciphertext = await pqc.encrypt('payload', publicKey);

keys.generate

generate: {(): Promise<KeyPair<"ml-kem-768">>; <A>(options): Promise<KeyPair<A>>; (options?): Promise<KeyPair<Algorithm>>; }

Call Signature

(): Promise<KeyPair<"ml-kem-768">>

Generates a post-quantum key pair. With no options it generates ML-KEM-768, ready for pqc.encrypt.

Returns

Promise<KeyPair<"ml-kem-768">>

Example

import { pqc } from '@pqc-sdk/core';

const encryption = await pqc.keys.generate();
const signing = await pqc.keys.generate({ algorithm: 'ml-dsa-65' });

Call Signature

<A>(options): Promise<KeyPair<A>>

Generates a post-quantum key pair. With no options it generates ML-KEM-768, ready for pqc.encrypt.

Type Parameters

A

A extends Algorithm

Parameters

options

GenerateOptions<A> & object

Returns

Promise<KeyPair<A>>

Example

import { pqc } from '@pqc-sdk/core';

const encryption = await pqc.keys.generate();
const signing = await pqc.keys.generate({ algorithm: 'ml-dsa-65' });

Call Signature

(options?): Promise<KeyPair<Algorithm>>

Generates a post-quantum key pair. With no options it generates ML-KEM-768, ready for pqc.encrypt.

Parameters

options?

GenerateOptions<Algorithm>

Returns

Promise<KeyPair<Algorithm>>

Example

import { pqc } from '@pqc-sdk/core';

const encryption = await pqc.keys.generate();
const signing = await pqc.keys.generate({ algorithm: 'ml-dsa-65' });

keys.serialize

serialize: (key) => string

Serializes a key to a portable string: pqcv1.<algorithm>.<use>.<base64url>.

Parameters

key

PqcKey

Returns

string

Example

import { pqc } from '@pqc-sdk/core';

const pair = await pqc.keys.generate();
const token = pqc.keys.serialize(pair.publicKey);
// "pqcv1.ml-kem-768.public.h1q3…"

sign

sign: (data, secretKey, options?) => Promise<Uint8Array<ArrayBufferLike>>

Signs data with ML-DSA-65 (FIPS 204) in hedged mode (randomized signing, the standard's default). Returns the 3309-byte signature.

Parameters

data

string | Uint8Array<ArrayBufferLike>

secretKey

SecretKey<"ml-dsa-65">

options?

SignatureOptions

Returns

Promise<Uint8Array<ArrayBufferLike>>

Example

import { pqc } from '@pqc-sdk/core';

const pair = await pqc.keys.generate({ algorithm: 'ml-dsa-65' });
const signature = await pqc.sign(document, pair.secretKey);

verify

verify: (data, signature, publicKey, options?) => Promise<boolean>

Verifies an ML-DSA-65 signature. Returns false for invalid or malformed signatures (it never throws because of a corrupted signature); it only throws if the key is not ML-DSA.

Parameters

data

string | Uint8Array<ArrayBufferLike>

signature

Uint8Array

publicKey

PublicKey<"ml-dsa-65">

options?

SignatureOptions

Returns

Promise<boolean>

Example

import { pqc } from '@pqc-sdk/core';

const valid = await pqc.verify(document, signature, pair.publicKey);
if (!valid) throw new Error('invalid signature');

Example

import { pqc } from '@pqc-sdk/core';

// Encryption (ML-KEM-768 + AES-256-GCM)
const pair = await pqc.keys.generate();
const ciphertext = await pqc.encrypt('hello', pair.publicKey);
const plaintext = await pqc.decrypt(ciphertext, pair.secretKey);

// Signatures (ML-DSA-65)
const signer = await pqc.keys.generate({ algorithm: 'ml-dsa-65' });
const signature = await pqc.sign('document', signer.secretKey);
await pqc.verify('document', signature, signer.publicKey); // true