Tom PQC
Published on pub.dev as tom_pqc 0.1.1.
Tom PQC is part of the Tom framework by al-the-bear. Distributed under the terms in this package's license — see LICENSE.
Post-quantum cryptography for Dart: ML-KEM-768, ML-DSA-65, X-Wing and composite ML-DSA-65 + Ed25519 (RFC 10073), via FFI to vendored mlkem-native and mldsa-native C code.
Overview
tom_pqc offers the two NIST post-quantum standards at security category 3
and the hybrids built on them:
- ML-KEM-768 (FIPS 203), the module-lattice key-encapsulation mechanism: a sender encapsulates a fresh shared secret to a receiver's public key, and only the receiver's secret key decapsulates it;
- ML-DSA-65 (FIPS 204), the module-lattice signature scheme;
- MLKEM768-X25519 (X-Wing), a hybrid KEM that stays secure while either
ML-KEM-768 or X25519 holds; it is the KEM of
agev1.3's post-quantum recipients; - ML-DSA-65 + Ed25519, the composite signature of RFC 10073
(
id-MLDSA65-Ed25519-SHA512), valid only when both halves verify; - SHA3-256 and SHAKE256 (FIPS 202).
The post-quantum algorithms run in vetted, portable C — the PQ Code Package's
mlkem-native and
mldsa-native, vendored
unchanged at pinned commits; the classical halves of the hybrids come from
cryptography. The package's build
hook compiles that C for the target of the build, and the Dart API reaches it
through dart:ffi. Nothing is downloaded at build time and the package ships
no binaries. Secret keys, seeds and shared secrets
live in native memory (SecretBytes) and are overwritten when disposed.
Installation
dart pub add tom_pqc
or in pubspec.yaml:
dependencies:
tom_pqc: ^0.1.0
Dart SDK ^3.10.0.
A C compiler. The build hook (hook/build.dart) compiles the vendored C
with native_toolchain_c, which looks for the platform's compiler: clang
from the Xcode command-line tools on macOS, clang on the PATH on Linux
(a native Linux build does not use gcc), MSVC from Visual Studio or its Build
Tools (with the C++ build tools) on Windows. The hook runs on
the first dart run, dart test or build of a package that depends on
tom_pqc and is cached afterwards.
Building an executable. A package with a build hook is compiled with
dart build cli, not dart compile exe, which refuses it ('dart compile' does not support build hooks, use 'dart build' instead):
dart build cli --target bin/my_app.dart
The bundle holds the executable in bin/ and the native library
(libtom_pqc.dylib, libtom_pqc.so or tom_pqc.dll) in lib/; ship the
bundle as a whole. Flutter desktop builds bundle the library themselves.
Features
Algorithms
| Class | Standard | What it offers |
|---|---|---|
MlKem768 |
FIPS 203 | key pairs (fresh, or from a 64-byte seed d ‖ z), encapsulate, decapsulate, the encapsulation- and decapsulation-key checks |
MlDsa65 |
FIPS 204 | key pairs from a 32-byte seed (the interoperable private key) or an expanded secret key, hedged sign with a context of up to 255 bytes, verify |
MlKem768X25519 |
X-Wing (draft-connolly-cfrg-xwing-kem, MLKEM768-X25519 of draft-ietf-hpke-pq) |
a 32-byte secret key (a seed), encapsulate, decapsulate; a low-order X25519 share is refused |
MlDsa65Ed25519 |
RFC 10073 id-MLDSA65-Ed25519-SHA512 |
a 64-byte secret key (two seeds), sign with an application context of up to 255 bytes, verify that needs both halves |
Sha3 |
FIPS 202 | SHA3-256 and SHAKE256, also over SecretBytes |
Secrets and errors
| Feature | What it does |
|---|---|
SecretBytes |
native memory for secret keys, seeds and shared secrets; extractBytes() copies them to the Dart heap, dispose() overwrites and frees them, a NativeFinalizer does the same for an object collected undisposed |
| Randomness | the operating system's generator: SecRandomCopyBytes on macOS, getrandom on Linux, BCryptGenRandom on Windows |
TomPqcException |
a key that fails a FIPS check, a low-order X25519 share, a failure of the C code; a value of the wrong length is an ArgumentError |
Quick start
import 'dart:convert';
import 'dart:typed_data';
import 'package:tom_pqc/tom_pqc.dart';
Future<void> main() async {
final message = Uint8List.fromList(utf8.encode('demo message'));
// ML-KEM-768: the receiver publishes its public key; the sender
// encapsulates a fresh shared secret to it.
final receiver = MlKem768.generateKeyPair();
final sent = MlKem768.encapsulate(receiver.publicKey);
final received = MlKem768.decapsulate(sent.ciphertext, receiver.secretKey);
print(base64.encode(sent.sharedSecret.extractBytes()) ==
base64.encode(received.extractBytes())); // true
print(sent.ciphertext.length); // 1088
// ML-DSA-65: sign and verify.
final signer = MlDsa65.generateKeyPair();
final signature = MlDsa65.sign(message, signer.secretKey);
print(signature.length); // 3309
print(MlDsa65.verify(message, signature, signer.publicKey)); // true
// Overwrite the secrets as soon as they are no longer needed.
sent.sharedSecret.dispose();
received.dispose();
receiver.dispose();
signer.dispose();
}
Example projects
| Sample | Demonstrates |
|---|---|
example/tom_pqc_example.dart |
The four schemes in a few lines each: an ML-KEM-768 key exchange, an ML-DSA-65 signature with a context, an X-Wing key exchange and a composite signature |
Usage
The snippets below use message, a Uint8List.
ML-KEM-768
// A key pair from a 64-byte seed: the same seed always gives the same pair,
// so the seed is the secret key's compact form (the one age stores).
final seed = MlKem768.generateSeed();
final pair = MlKem768.keyPairFromSeed(seed);
// FIPS 203's key checks, for keys from elsewhere.
print(MlKem768.isValidPublicKey(pair.publicKey)); // true
print(MlKem768.isValidSecretKey(pair.secretKey)); // true
final sent = MlKem768.encapsulate(pair.publicKey);
final received = MlKem768.decapsulate(sent.ciphertext, pair.secretKey);
sent.sharedSecret.dispose();
received.dispose();
pair.dispose();
seed.dispose();
encapsulate throws TomPqcException for a public key that fails FIPS 203's
modulus check. A ciphertext not made for the key does not fail to
decapsulate: FIPS 203's implicit rejection returns a secret no sender knows,
so the failure shows when the two sides use their secrets.
ML-DSA-65
final context = Uint8List.fromList(utf8.encode('demo/context'));
final signer = MlDsa65.generateKeyPair();
final signature = MlDsa65.sign(message, signer.secretKey, context: context);
print(MlDsa65.verify(message, signature, signer.publicKey, context: context)); // true
print(MlDsa65.verify(message, signature, signer.publicKey)); // false: other context
// The 32-byte seed is the key to store; it gives the same key pair again.
final seed = SecretBytes.fromBytes(signer.seed!.extractBytes());
final again = MlDsa65.keyPairFromSeed(seed);
again.dispose(); // disposes the seed it keeps
signer.dispose();
Signing is hedged (fresh randomness mixed into each signature), so two
signatures of one message differ. verify answers false for malformed
input rather than throwing. keyPairFromSecretKey takes an expanded
4,032-byte secret key instead of a seed.
MLKEM768-X25519 (X-Wing)
The hybrids are asynchronous, because their classical halves are:
final pair = await MlKem768X25519.generateKeyPair();
final capsule = await MlKem768X25519.encapsulate(pair.publicKey);
final opened = await MlKem768X25519.decapsulate(
capsule.ciphertext,
pair.secretKey,
);
// capsule.sharedSecret and opened hold the same 32 bytes.
// The public key follows from the 32-byte secret key.
final publicKey = await MlKem768X25519.publicKey(pair.secretKey);
capsule.sharedSecret.dispose();
opened.dispose();
pair.dispose();
The shared secret is SHA3-256 of the ML-KEM and X25519 shared secrets, the
X25519 ciphertext and public key, and the X-Wing label. A low-order X25519
share throws TomPqcException; a wrong ML-KEM half yields an unrelated secret,
as in ML-KEM.
Composite ML-DSA-65 + Ed25519 (RFC 10073)
final context = Uint8List.fromList(utf8.encode('demo/context'));
final composite = await MlDsa65Ed25519.generateKeyPair();
final signature = await MlDsa65Ed25519.sign(
message,
composite.secretKey,
context: context,
);
print(await MlDsa65Ed25519.verify(
message,
signature,
composite.publicKey,
context: context,
)); // true
composite.dispose();
Both halves sign the message representative
Prefix ‖ Label ‖ len(ctx) ‖ ctx ‖ SHA-512(M) (MlDsa65Ed25519.representative);
the signature is the ML-DSA-65 signature followed by the Ed25519 signature,
and verify answers true only when both verify.
SHA3-256 and SHAKE256
final digest = Sha3.sha3256(message); // 32 bytes
final stream = Sha3.shake256(message, 64); // any length
sha3256Secret and shake256Secret take and answer SecretBytes, for
hashing a secret without copying it to the Dart heap.
Secrets in memory
final secret = SecretBytes.fromBytes(Uint8List(32));
final copy = secret.extractBytes(); // a Dart heap copy, yours to overwrite
secret.dispose();
print(secret.isDisposed); // true
Dispose every key pair, seed and shared secret as soon as it is no longer
needed. A key pair's dispose() disposes its secret key (and an ML-DSA-65
pair its seed).
Key sizes
The classes' …Length constants hold them; all sizes in bytes:
| Scheme | Public key | Secret key | Seed | Ciphertext / signature | Shared secret |
|---|---|---|---|---|---|
| ML-KEM-768 | 1,184 | 2,400 | 64 | ciphertext 1,088 | 32 |
| ML-DSA-65 | 1,952 | 4,032 (expanded) | 32 | signature 3,309 | — |
| MLKEM768-X25519 | 1,216 | 32 (the seed) | — | ciphertext 1,120 | 32 |
| ML-DSA-65 + Ed25519 | 1,984 | 64 (two seeds) | — | signature 3,373 | — |
Architecture
hybrids MlKem768X25519 MlDsa65Ed25519
| \ / |
| package:cryptography |
| (X25519, Ed25519) |
v v
Dart API MlKem768 Sha3 MlDsa65 SecretBytes
\ | /
PqcBackend (internal, not exported)
| dart:ffi
native libtom_pqc, built by hook/build.dart
tom_pqc.h: the backend interface, the only exported symbols
/ | \
mlkem-native mldsa-native OS random generator
(ML-KEM, SHA3) (ML-DSA)
The Dart API calls the C code only through a small backend interface
(native/tom_pqc.h, PqcBackend on the Dart side); the hybrids are built on
the Dart API, never on a C library directly. Each vendored library is compiled
as one unit with all of its symbols static, so the native library exports
nothing but that interface, and another C implementation could replace them
without changing the Dart API, provided it passes the same known-answer tests.
Only the libraries' portable C is vendored; their assembly back ends are not.
| Type | Responsibility |
|---|---|
MlKem768, MlKem768KeyPair, MlKem768Encapsulation |
ML-KEM-768 |
MlDsa65, MlDsa65KeyPair |
ML-DSA-65 |
MlKem768X25519, MlKem768X25519KeyPair, MlKem768X25519Encapsulation |
X-Wing |
MlDsa65Ed25519, MlDsa65Ed25519KeyPair |
the RFC 10073 composite signature |
Sha3 |
SHA3-256, SHAKE256 |
SecretBytes |
secrets in native memory |
TomPqcException |
the package's failures |
Test vectors
The suite checks the package against:
- NIST's ACVP known-answer vectors for ML-KEM-768 (key generation, encapsulation, decapsulation, both key checks) and ML-DSA-65 (key generation; signing, deterministic and hedged, through the external, internal and external-mu interfaces; verification);
- every ML-KEM-768 and ML-DSA-65 case of Project Wycheproof;
- the X-Wing draft's test vectors and RFC 10073's composite vector;
- every hybrid file of the age testkit, decrypted through a minimal age reader with this package's MLKEM768-X25519;
- a cross-check with Go's standard library (
crypto/mlkem,crypto/mldsa,crypto/hpke).
Each set is kept as its source wrote it, with its origin and commit;
THIRD_PARTY.md lists them.
Platforms
| Platform | Status |
|---|---|
| macOS (arm64) | supported, verified |
| Linux (x64) | supported, verified |
| Windows (x64) | supported, verified |
| iOS, Android | not built yet |
| Web | not supported (dart:ffi) |
The library is bundled by dart run and dart test, by dart build cli and
by Flutter desktop release builds.
Limits
- One parameter set each. ML-KEM-768 and ML-DSA-65 only; HashML-DSA (the pre-hash variant of FIPS 204) is not offered.
- Side channels. The post-quantum code is the vendored libraries' portable
C, compiled as their authors wrote it;
tom_pqcmakes no side-channel claim of its own beyond it. - The classical halves pass the Dart heap. X25519 and Ed25519 run in
package:cryptography, so the hybrids' classical key bytes are on the Dart heap briefly and are overwritten after use. - Copies are the caller's.
extractBytes()copies a secret to the Dart heap; that copy is not overwritten bydispose().
Licence
tom_pqc's own code (the Dart library, the build hook, the tools and the C
glue under native/) is BSD-3-Clause, see LICENSE. The vendored
mlkem-native (v2.0.0) and mldsa-native (v2.0.0) are available under
Apache-2.0 OR ISC OR MIT and are used under MIT; their licences are kept as
native/mlkem-native/LICENSE and
native/mldsa-native/LICENSE.
THIRD_PARTY.md names the vendored files, their origin and
commit, the Dart dependencies' licences and the licences of the test vectors.
Further documentation
| Document | Covers |
|---|---|
doc/pqc.md |
the user guide: concepts, every scheme with examples, secrets in memory, errors, platforms and limits |
example/ |
the runnable example |
THIRD_PARTY.md |
the vendored C, its commits and licences; the test vectors and their sources |
CHANGELOG.md |
the releases |
| API reference | every public type and member |
| mlkem-native, mldsa-native | the C implementations and their verification |
| FIPS 203, FIPS 204, RFC 10073 | the standards |
Status
Version 0.1.1, published on pub.dev.
dart test from the package root runs the known-answer and cross-check suites
listed under Test vectors, the API's behaviour and the licence
checks; the build hook compiles the C on the first run.
Repository: github.com/al-the-bear/tom_basics — tom_pqc
Libraries
- tom_pqc
- Post-quantum cryptography for Dart: ML-KEM-768 (FIPS 203), ML-DSA-65
(FIPS 204), and the hybrids built on them — the KEM MLKEM768-X25519
(X-Wing,
age's hybrid recipients) and the composite signature ML-DSA-65 + Ed25519 of RFC 10073.