Each block is the call the matching program in example/ runs. Paste
it after import 'package:pqtransport/pqtransport.dart'; and
import 'package:swissarmyknife/swissarmyknife.dart';.
TLS 1.3#
serverName is SNI. A raw public key does not check that name.
peerAuthenticated is true only after CertificateVerify.
onlyShares forces one group. X.509 is
certificateTypes: [TlsCertificateType.x509] plus caller anchors.
final crypto = PqTransportCrypto();
final identity = PqTlsServerIdentity.generate(crypto);
final (a, b) = MemoryByteSocket.pair();
final client = PqTlsSocket.client(
a,
crypto: crypto,
serverName: 'app.example',
alpnProtocols: const [httpAlpnH1],
);
final server = PqTlsSocket.server(
b,
crypto: crypto,
identity: identity,
alpnProtocols: const [httpAlpnH1],
);
final hs = await Future.wait([server.handshake(), client.handshake()]);
final sent = await client.send(Uint8List.fromList('ping'.codeUnits));
final got = await server.applicationData.first;
final key = client.exporter('app', Uint8List(0), 32);
hs must succeed, client.peerAuthenticated is true, and
client.negotiatedGroup is TlsNamedGroup.x25519MlKem768. The
program is example/tls13.dart.
HTTP/1.1#
Listen on the server before the client writes. roundTrip follows
ALPN. A silent drop from h2 or h3 fails unless allowDowngrade
is set.
server.applicationData.listen((raw) async {
await server.send(
encodeHttp1Response(
PqHttpResponse(
status: 200,
headers: const {'content-type': 'text/plain'},
body: Uint8List.fromList('pq-ok'.codeUnits),
version: HttpVersion.h1,
),
),
);
});
await Future.wait([server.handshake(), client.handshake()]);
final res = await PqHttpClient().roundTrip(
tls: client,
request: PqHttpRequest(
method: 'GET',
uri: Uri.parse('https://app.example/health'),
),
);
The handshake uses alpnProtocols: const [httpAlpnH1]. The program
is example/http1.dart.
HTTP/2#
Start accept before roundTripH2. ALPN must be h2.
final client = PqTlsSocket.client(
a,
crypto: crypto,
alpnProtocols: const [httpAlpnH2],
);
final server = PqTlsSocket.server(
b,
crypto: crypto,
identity: identity,
alpnProtocols: const [httpAlpnH2],
);
await Future.wait([server.handshake(), client.handshake()]);
final h2 = PqHttp2Session.server(server);
final serving = () async {
final accepted = await h2.accept(timeout: const Duration(seconds: 20));
final (id, _) = accepted.valueOrNull!;
return h2.respond(
id,
PqHttpResponse(
status: 200,
headers: const {'content-type': 'text/plain'},
body: Uint8List.fromList('h2-ok'.codeUnits),
version: HttpVersion.h2,
),
);
}();
final res = await PqHttpClient(prefer: HttpVersion.h2).roundTripH2(
tls: client,
request: PqHttpRequest(
method: 'GET',
uri: Uri.parse('https://app.example/health'),
),
);
await serving;
The program is example/http2.dart.
HTTP/3#
PqQuicConn.pair links the two ends in memory. A real socket uses
PqQuicConn.client and sends the datagram from deliver.
roundTripH3 refuses any ALPN other than h3.
final (client, server) = PqQuicConn.pair(alpnProtocols: const [httpAlpnH3]);
await Future.wait([client.handshake(), server.handshake()]);
final h3 = PqHttp3Session.server(server);
final serving = () async {
final accepted = await h3.accept();
final (id, _) = accepted.valueOrNull!;
return h3.respond(
id,
PqHttpResponse(
status: 200,
headers: const {'content-type': 'text/plain'},
body: Uint8List.fromList('pq-h3'.codeUnits),
version: HttpVersion.h3,
),
);
}();
final res = await PqHttpClient(prefer: HttpVersion.h3).roundTripH3(
conn: client,
request: PqHttpRequest(
method: 'GET',
uri: Uri.parse('https://app.example/health'),
),
);
await serving;
The program is example/http3.dart. This is not curl --http3.
DNS stub#
exchange and tcp return the raw message. lookup returns that
one answer. resolve follows CNAME. Neither checks a signature. A
truncated UDP answer is retried once over tcp.
final dns = PqDnsClient(
exchange: (query) async => reply(query, truncated: false),
tcp: (query) async => reply(query, truncated: false),
);
final one = await dns.lookup('alias.example.', DnsType.a);
final chased = await dns.resolve('alias.example.', DnsType.a);
one stops at the CNAME. chased is the A record at the target.
reply echoes id and the question, and sets dnsFlagTc
when
truncated is true. The program is example/dns_stub.dart.
DNSSEC#
Pass lookup, not resolve. CNAME hops are checked inside
authenticateDns. The AD bit is not read.
final anchor = DnsTrustAnchor.dnskey(zone: 'example.com.', dnskey: key);
final auth = await authenticateDns(
name: 'www.example.com.',
type: DnsType.a,
anchor: anchor,
lookup: lookup,
now: DateTime.utc(2026, 6, 1),
);
key is a DnsDnskey with flags: dnssecZoneKeyFlag,
protocol: dnssecProtocol, and algorithm: dnssecAlgorithmEd25519.
A DS anchor is DnsTrustAnchor.ds. The root publishes two KSKs, so
pin both:
final root = DnsTrustAnchor.dsSet(
zone: '.',
ds: [
DnsDs(
name: '.',
keyTag: 20326,
algorithm: dnssecAlgorithmRsaSha256,
digestType: dnssecDigestSha256,
digest: digest20326,
),
DnsDs(
name: '.',
keyTag: 38696,
algorithm: dnssecAlgorithmRsaSha256,
digestType: dnssecDigestSha256,
digest: digest38696,
),
],
);
Those two digests are the digest-type-2 records in the IANA root
anchors. The signed zone is example/dns_validate.dart. The live
query of yardenah.com is example/dns_live.dart.
auth.valueOrNull is DnsAuthData when the chain verified, or
DnsAuthDenial for a secure NXDOMAIN or NODATA. Anything else is
auth.errorOrNull.
Iterative resolver#
Queries to authoritative servers do not set RD. The sender retries a truncated answer over TCP. The NSEC3 iteration ceiling defaults to 0.
final walker = DnsIterativeResolver(
hints: [
DnsHint(
'a.root-servers.net.',
[Uint8List.fromList(const [198, 41, 0, 4])],
),
],
anchor: root,
send: (query, nameserver, addresses) async {
final wire = encodeDnsMessage(query).valueOrNull!;
final raw = await ask(addresses, wire);
return decodeDnsMessage(raw);
},
);
final walked = await walker.lookup('example.com.', DnsType.a);
walked.valueOrNull!.security is DnsSecurity.secure, insecure,
or bogus.
DoH#
The handshake selects ALPN h2. The template may end in {?dns}.
Any other { fails. exchange is what PqDnsResolver
calls.
lookup still does not validate. HTTP/3 is DohClient.h3 on a
PqQuicConn whose ALPN is h3.
final template = DohUriTemplate.parse(
'https://dns.example/dns-query{?dns}',
).valueOrNull!;
final http = PqHttpClient(prefer: HttpVersion.h2);
final post = DohClient.h2(client, template: template, http: http);
final get = DohClient.h2(
client,
template: template,
http: http,
useGet: true,
);
final query = encodeDnsMessage(
DnsMessage(
id: 0x0d07,
questions: [DnsQuestion(name: 'www.example.', type: DnsType.a)],
),
).valueOrNull!;
final posted = await post.query(query);
final gotten = await get.query(query);
final looked = await PqDnsResolver(
doh: post.exchange,
).lookup('www.example.', DnsType.a);
The server reads the request with dohQueryFromRequest and answers
with dohResponse. The program is example/doh.dart.
DoT#
ALPN must be dot. The DNS message has a 2-byte length prefix.
final client = PqTlsSocket.client(
a,
crypto: crypto,
alpnProtocols: const [dnsAlpnDot],
);
final server = PqTlsSocket.server(
b,
crypto: crypto,
identity: identity,
alpnProtocols: const [dnsAlpnDot],
);
final serving = () async {
final reader = DnsTcpReader();
await for (final chunk in server.applicationData) {
reader.add(chunk);
final q = reader.next();
if (q == null) continue;
return server.send(encodeDnsTcp(answer));
}
}();
await Future.wait([server.handshake(), client.handshake()]);
final got = await DotClient(client).query(query);
await serving;
query is encodeDnsMessage(...). The program is example/dot.dart.
Encrypted UDP#
final net = MemoryDatagramNetwork();
final aEp = const PqEndpoint('127.0.0.1', 4242);
final bEp = const PqEndpoint('127.0.0.1', 4243);
final a = PqEncryptedUdpSocket(
raw: PqUdpSocket(channel: net.bind(aEp), throttleWindow: Duration.zero),
crypto: crypto,
);
final b = PqEncryptedUdpSocket(
raw: PqUdpSocket(channel: net.bind(bEp), throttleWindow: Duration.zero),
crypto: crypto,
);
final kem = crypto.kemKeyGen();
final salt = crypto.randomBytes(16);
final flight = (await a.initiate(
peerKemPublicKey: kem.publicKey,
deploymentSalt: salt,
)).valueOrNull!;
final reply = (await b.accept(
kemSecretKey: kem.secretKey,
initiatorFlight: flight,
deploymentSalt: salt,
)).valueOrNull!;
await a.completeInitiate(responderClassicalPublic: reply);
await a.send(Uint8List.fromList('hello'.codeUnits), bEp);
The program is example/encrypted_udp_peer.dart.
mDNS#
final net = MemoryDatagramNetwork();
final server = PqMdnsServer(
channel: net.bind(const PqEndpoint('10.0.0.1', mdnsPort)),
);
await server.beginProbe('printer._pq._tcp.local.');
server.completeProbe(collision: false);
server.completeProbe(collision: false);
await server.announce(
DnsA(
name: 'printer._pq._tcp.local.',
address: Uint8List.fromList(const [10, 0, 0, 1]),
),
);
A signed TXT is named arguments, not a positional call:
final identity = PqTlsServerIdentity.generate(crypto);
final txt = signTxt(
crypto: crypto,
secretKey: identity.secretKey,
name: 'printer._pq._tcp.local.',
body: const ['pqtransport=1'],
);
final ok = verifyTxt(
crypto: crypto,
publicKey: identity.publicKey,
txt: txt.valueOrNull!,
);
The program is example/mdns_discovery.dart. A real LAN joins
224.0.0.251 with joinMdnsGroups on IoDatagramChannel.
Length-filter a share#
final share = requireLength(raw, x25519MlKem768ClientShareBytes);
final parsed = decodeClientShare(HybridGroup.x25519MlKem768, share);
Live NIST group#
final crypto = PqTransportCrypto();
final r = PqTlsClient(
crypto: crypto,
group: HybridGroup.secP256r1MlKem768,
).startHandshake();
SecP384r1MLKEM1024 needs PqForgeProfile.maximum.
Profile / group mismatch still fails closed#
final crypto = PqTransportCrypto(profile: PqForgeProfile.maximum);
final r = await PqTlsClient(
crypto: crypto,
group: HybridGroup.x25519MlKem768,
).startHandshake();
r is a failure. Maximum is ML-KEM-1024. X25519MLKEM768 needs 768.
Servers#
Shelf and Relic do not take a dart:io SecurityContext on this
path. The handshake is pqtransport. Serverpod's API server and
insights server still build that context inside Serverpod. This
package does not pretend a SecurityContext can hold an ML-DSA
certificate. Serverpod's web server is Relic. If you construct that
web server yourself, pass PqRelicAdapter instead of IOAdapter.
import 'package:pqtransport/shelf.dart';
import 'package:shelf/shelf.dart';
final shelf = await serveShelf(
(request) => Response.ok('shelf-ok ${request.requestedUri.path}'),
InternetAddress.loopbackIPv4,
0,
identity: identity,
);
import 'package:pqtransport/relic.dart';
import 'package:relic_core/relic_core.dart';
final adapter = await PqRelicAdapter.bind(
InternetAddress.loopbackIPv4,
0,
identity: identity,
);
final relic = RelicServer(() => adapter);
await relic.mountAndStart(
(request) =>
Response.ok(body: Body.fromString('relic-ok ${request.url.path}')),
);
identity is a PqTlsServerIdentity. ALPN offers h2 and
http/1.1. Pass quic: true to also accept HTTP/3 on the same
port. Shelf hijacks HTTP/1.1. Relic Hijack detaches HTTP/1.1, and
Relic WebSocketUpgrade completes an RFC 6455 handshake on that
connection, including permessage-deflate on the VM. The test client
is this package. It is not a browser. HTTP/2 does not hijack, and
the HTTP/2 and HTTP/3 extended CONNECT tunnels are not that codec.
The tests are test/io/framework_test.dart.
Foreign servers are the Peers page. OpenSSL 3.5.9 is the
TLS peer, including s_server -max_send_frag 512, which splits both
ServerHello and a 2048-octet HTTP/1.1 body. curl linked to that
OpenSSL is the HTTP/1.1 client against PqHttpServer (chunked body,
one connection for two responses, a new connection after
Connection: close). quiche 0.30.0 is the HTTP/3 peer for one GET
both ways. That is not curl --http3 and not a complete RFC 9114
stack. Extended CONNECT is libnghttp2 and quiche. HTTP/2
PRIORITY_UPDATE is libnghttp2 1.66.0 (u=1, i recorded by this
server). The QPACK dynamic table at capacity 4096 is libnghttp3
1.11.0, both directions. quiche 0.30.0 stays at capacity 0. HTTP
datagrams are the quiche flights. CONNECT-UDP is masque-go v0.6.0 and CONNECT-IP
is connect-ip-go v0.6.0, both directions. curl 8.23.0 with
nghttp2 completes one HTTP/2 GET. libnghttp2 completes extended
CONNECT. curl wss:// does not. The interop job runs picoquic
1.1.54.0. It did not complete. noq 1.5.0 (bb1c63ee) with rustls
0.23.46 on aws-lc-rs did: path 1, ML-DSA-65 checked by rustls,
X25519MLKEM768 after HelloRetryRequest. Not every RFC 10069 frame.