Kernel-Bypass PQC Benchmarking

This is a public, demo/review version of a larger project. The full high-rate NIC-lab campaign is private, so the public results here come from a smaller lab-scale subset and some numbers differ from the full private work. Only rows under results/final/ are treated as public evidence.

Overview

This repository is a systems/security benchmarking project for post-quantum cryptography (PQC) over high-performance networking paths. It implements a mutually authenticated PQC handshake, an AES-256-GCM data plane, and multiple Linux/kernel-bypass transport backends so their latency and throughput tradeoffs can be compared with the same cryptographic protocol.

The codebase is organized as reproducible experiment source, benchmark tooling, final validated result artifacts, and concise documentation. Generated binaries, local logs, paper build artifacts, debug scripts, and failed result files are intentionally excluded.

Motivation

PQC algorithms increase key, ciphertext, and signature sizes compared with classical elliptic-curve mechanisms. In latency-sensitive systems, the networking stack can amplify that cost through copies, syscalls, context switches, packet segmentation, and kernel scheduling. This project studies whether kernel-bypass and userspace TCP stacks can recover performance headroom while preserving a PQC-authenticated session setup.

System Architecture

The architecture has four layers:

• Protocol layer: four-message PQC handshake, transcript binding, SHAKE256 key derivation, AES-256-GCM encrypted request/response data path.
• Transport layer: Linux TCP/UDP baselines, AF_PACKET packet_mmap variants, eBPF/XDP AF_XDP, DPDK UDP, F-Stack, mTCP, Seastar, IX/lwIP, and netmap experiments.
• Benchmark layer: handshake timing, per-message timing, PPS/Mbps monitoring, CPU-cycle and resource metrics where supported.
• Result layer: raw final CSV/text artifacts plus results/final/validated_results.csv, generated by scripts/analyze_results.py.

More detail is in docs/architecture.md, docs/protocol.md, and docs/backend_matrix.md.

Kernel-Bypass Networking Approach

The repository compares several approaches with different kernel involvement:

• Linux kernel TCP and UDP baselines for ordinary socket behavior.
• AF_PACKET and packet_mmap to reduce receive-path copies while retaining kernel packet processing.
• eBPF/XDP with AF_XDP to redirect selected traffic before the normal kernel stack.
• DPDK poll-mode drivers for direct userspace NIC access and UDP fragmentation/reassembly.
• F-Stack, mTCP, and Seastar to run TCP semantics in userspace over DPDK.
• IX/lwIP and netmap prototypes for additional userspace dataplane coverage.

The final validated throughput set covers LinuxKernel, UDP_Linux, DPDK, eBPF/XDP, F-Stack, mTCP, and Seastar. Other implementations are included as source when they are useful for architecture review but are not treated as final result sources unless listed in results/final. See docs/backend_matrix.md for the full backend map.

PQC Algorithms And Cryptographic Components

The implementation uses liboqs for Kyber/ML-KEM and Dilithium/ML-DSA families, OpenSSL for SHAKE256 and AES-256-GCM, and a length-prefixed JSON wire format for TCP modes. The default configured suite is:

KYBER768+DILITHIUM3+SHAKE256+AESGCM

The C++ handshake benchmark also supports security-level sweeps through:

• Kyber512 with Dilithium2
• Kyber768 with Dilithium3
• Kyber1024 with Dilithium5

The Python fallback paths use classical primitives only for development when liboqs is unavailable; final PQC measurements should be produced with liboqs.

Benchmarking Methodology

Benchmarks measure:

• Handshake latency by phase: KEM keygen, Dilithium signing/verification, KEM encapsulation/decapsulation, send/receive waits, and key derivation.
• CPU cycles and resource metrics where Linux perf counters are available.
• Per-second packet rate and throughput via interface counters.
• Message timing on established sessions for encrypt, send, receive, and decrypt phases.

For PPS/Mbps logs, the validated summary uses active samples, defined as rows where RX or TX packets were nonzero. Raw files are preserved so idle samples and short runs are visible. The audit and notes are in results/summaries/csv_audit.md.

Hardware And Software Requirements

Minimum for source review and default build:

• Linux for execution of network experiments
• C++17 compiler
• Python 3.8+
• OpenSSL 3.x
• liboqs and liboqs-python
• nlohmann-json

Kernel-bypass backends need additional stack-specific dependencies:

• DPDK and hugepages for DPDK, F-Stack, mTCP, Seastar, and IX modes
• F-Stack for experiments/fstack-dpdk
• mTCP for experiments/mtcp-dpdk
• Seastar with native network stack support for experiments/seastar-dpdk
• clang, libbpf, libxdp, libelf, and a Linux kernel with XDP support for experiments/ebpf_xdp
• netmap for experiments/netmap_generic

Build Instructions

Install the base dependencies on a Linux host, build liboqs, then run the target you need:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

scripts/build.sh default
scripts/build.sh udp-linux
scripts/build.sh handshake

Kernel-bypass examples:

LIBOQS_ROOT=/opt/liboqs scripts/build.sh dpdk
FSTACK_ROOT=/usr/local LIBOQS_ROOT=/opt/liboqs scripts/build.sh fstack
MTCP_ROOT=/opt/mtcp LIBOQS_ROOT=/opt/liboqs scripts/build.sh mtcp
SEASTAR_DIR=/opt/seastar/build/release LIBOQS_ROOT=/opt/liboqs scripts/build.sh seastar

Run Instructions

Sample default handshake benchmark on one Linux host:

scripts/build.sh handshake
mkdir -p results/local

# Terminal 1
experiments/handshake_benchmarks/bench_server --ip 127.0.0.1 --port 5020

# Terminal 2
scripts/run_benchmark.sh handshake-default -n 20 --warmup 3 --server-ip 127.0.0.1 \
  -o "$PWD/results/local/sample_handshake_default.csv"

Sample F-Stack handshake benchmark on a two-host DPDK lab:

# Server host
cd experiments/fstack-dpdk
sudo ./run_server.sh --conf config.ini

# Client host
cd experiments/handshake_benchmarks
sudo ./run_handshake_bench.sh --mode fstack -n 100 --warmup 5 \
  --server-ip 10.10.0.2 --pci 0000:02:00.1 --driver ice \
  -o ../../results/final/fstack_level3_sample.csv

Adjust IPs, MACs, PCI addresses, interfaces, and DPDK driver names to your lab before running kernel-bypass modes.

Results Summary

The trusted final result source is results/final/validated_results.csv. It contains 55 validated summary rows with throughput, latency, packet-rate, CPU-cycle, context-switch, page-fault, CPU-time, and memory fields where the raw artifacts provide them:

• 42 throughput rows from final PPS/Mbps logs.
• 12 handshake rows from Level1, Level3, and Level5 reports across four transports.
• 1 packet_mmap per-iteration handshake summary.

Selected validated results:

Metric	Best observed validated row
DPDK UDP throughput	965.334 Mbps total at 512-byte payload
Seastar TCP throughput	1187.422 Mbps total at 8192-byte payload
F-Stack TCP throughput	1121.369 Mbps total at 8192-byte payload
Level3 handshake, default TCP	4.77 ms mean total
Level3 handshake, F-Stack	2.03 ms mean total
Level3 handshake, Seastar	1.96 ms mean total

See results/summaries/results_summary.md for the full readable summary.

Generated result figures:

• figures/results/throughput_tcp_backends.svg
• figures/results/throughput_udp_backends.svg
• figures/results/level3_handshake_breakdown.svg

CSV And Result Files

Included final artifacts:

• results/final/throughput_logs/: raw final PPS/Mbps logs organized by backend.
• results/final/handshake_reports/: raw final text reports for Level1, Level3, and Level5 handshake runs.
• results/final/packet_mmap_handshake_iterations.csv: complete packet_mmap per-iteration handshake CSV.
• results/final/validated_results.csv: generated trusted summary across the included raw artifacts.

Regenerate the trusted summary with:

scripts/run_benchmark.sh analyze
scripts/run_benchmark.sh plot

For one-off log inspection:

scripts/run_benchmark.sh summarize-pps results/final/throughput_logs/DPDK/512pps_log.csv

Reproducibility Notes

The kernel-bypass results depend on NIC model, driver, PCI binding, hugepage setup, CPU isolation, queue count, payload size, and whether clocks are synchronized for message timing. The included results use lab RFC1918 addressing (10.10.0.1 and 10.10.0.2) and sanitized example MAC addresses. Replace them with your own lab values before running.

Every included raw result artifact is hashed in validated_results.csv, and every excluded CSV/result artifact is documented in results/summaries/csv_audit.md.

Limitations

• The repository contains a research protocol, not a production TLS implementation.
• Final validated results are from the included artifacts only; no numbers are invented.
• The result set compares networking backends running PQC, not a full classical-versus-PQC TLS baseline.
• Kernel-bypass builds cannot be fully validated on macOS because the backends require Linux kernel facilities, DPDK, and NIC binding.
• Some source backends are included for engineering review but are not part of the final validated result table.