tom_pqc 0.1.1
tom_pqc: ^0.1.1 copied to clipboard
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.
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