Skip to main content

tom_pqc 0.1.1 copy "tom_pqc: ^0.1.1" to clipboard
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 age v1.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_pqc makes 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 by dispose().

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

0
likes
150
points
98
downloads

Documentation

API reference

Publisher

unverified uploader

Weekly Downloads

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.

Repository (GitHub)
View/report issues

Topics

#cryptography #post-quantum #ffi

License

BSD-3-Clause (license)

Dependencies

code_assets, crypto, cryptography, ffi, hooks, logging, meta, native_toolchain_c

More

Packages that depend on tom_pqc