PQCP Inclusion Proposal: `ml-kem` and `ml-dsa` — Portable C++20 constexpr Header-Only Zero-Dependency Implementations of FIPS 203 & FIPS 204

[itzmeanjan]

Proposer: Anjan Roy (Github: @itzmeanjan)
Repositories:

• https://github.com/itzmeanjan/ml-kem (FIPS 203 / ML-KEM)
• https://github.com/itzmeanjan/ml-dsa (FIPS 204 / ML-DSA)

Current licenses:

• ml-kem: BSD-3-Clause
• ml-dsa: MIT

(To be relicensed to Apache 2.0 — see section below)

---

Overview

I would like to propose two related projects for consideration as PQCP sub-projects:

• ml-kem — a C++20 implementation of ML-KEM (NIST FIPS 203), supporting all three parameter sets.
• ml-dsa — a C++20 implementation of ML-DSA (NIST FIPS 204), supporting all three parameter sets, with both hedged (randomized) and deterministic signing modes, and pre-hash signing via only SHA3 family of functions.

Both libraries are header-only, fully constexpr, portable, have zero third-party dependencies and written in C++20. Integration into existing C++ projects requires no build system dependency beyond pointing the compiler at the include/ directory or with CMake FetchContent passing git repository URL.

---

How these complement existing PQCP implementations?

The existing PQCP portfolio covers C90, Assembly, Jasmin, and Rust — but has no C++ implementations at all. These two projects will fill that gap.

Project	Language	Primary focus	Formal verification
mlkem-native	C90 + Assembly	Native performance, platform-optimized assembly	CBMC + HOL Light
mlkem-libjade	Jasmin	Formally verified native code	EasyCrypt
rust-libcrux	Rust	Formally verified, portable + AVX2	Yes
liboqs	C	Unified multi-algorithm API wrapping reference implementations	No
ml-kem (this proposal)	C++20	Header-only, fully compile-time evaluable, proven absence of core language undefined behaviour (UB)	Not yet
ml-dsa (this proposal)	C++20	Header-only, fully compile-time evaluable, proven absence of core language undefined behaviour (UB)	Not yet

What value does ml-kem and ml-dsa bring?

• The public API uses statically-sized std::span throughout — no raw pointers, no implicit buffer size arguments. No pointer arithmetic. Key, ciphertext, and signature sizes are encoded in the type system itself, making API misuse a compile-time error rather than a runtime bug.
• The two libraries and all their first-party dependencies are fully constexpr - meaning not only one can fully compile-time evaluate them, they also prevent a class of core C++ language undefined behaviours (UB) such as buffer overflow, out of bounds access, use after free etc. - a feature required by C++ standard.
• Known-answer test (KAT) vectors can be validated via static_assert at compile time, costing higher compilation latency but zero runtime cost. Compiler simply fails to compile the program if ml-kem or ml-dsa has a bug, that gets triggered by the deployed KAT.
• For firmware and embedded C++ targets where seeds are known at build time, keys and shared secrets can be computed entirely by the compiler and baked into the binary as constants.
• [[nodiscard]] on for functions returning a value — the compiler warns if the caller ignores the return value. This prevents a class of API misuse bugs at compile time.
• consteval parameter validation — invalid parameter combinations are rejected at compile time, not at runtime.
• We compile with -Wall -Wextra -Wpedantic -Wshadow -Wconversion -Wformat=2 -Wcast-qual -Wold-style-cast -Wundef -Werror compiler flags, i.e., treating any warning as compile-time error.
• clang-tidy based static analysis is integrated — it's configured with WarningsAsErrors: '*' across bugprone, cert, clang-analyzer, concurrency, cppcoreguidelines, hicpp, modernize, performance, portability, and readability checks. It helps us maintain high code quality.

A representative example for ML-KEM-512 — full keygen, encaps, and decaps executed entirely at compile-time:

/**
 * Filename: compile-time-ml-kem-512.cpp
 *
 * Use `cmake --install` to install ml-kem system-wide and compile with:
 *
 * $ g++ -std=c++20 -Wall -Wextra -Wpedantic -fconstexpr-ops-limit=67108864 compile-time-ml-kem-512.cpp && ./a.out
 * $ clang++ -std=c++20 -Wall -Wextra -Wpedantic -fconstexpr-steps=33554432 compile-time-ml-kem-512.cpp && ./a.out
 */

#include "ml_kem/ml_kem_512.hpp"
#include <string_view>

// Compile-time hex character to nibble conversion.
constexpr uint8_t
hex_digit(char c)
{
  if (c >= '0' && c <= '9') return static_cast<uint8_t>(c - '0');
  if (c >= 'a' && c <= 'f') return static_cast<uint8_t>(c - 'a' + 10);
  if (c >= 'A' && c <= 'F') return static_cast<uint8_t>(c - 'A' + 10);
  return 0;
}

// Compile-time hex string to byte array conversion.
template<size_t L>
constexpr std::array<uint8_t, L>
from_hex(std::string_view str)
{
  std::array<uint8_t, L> res{};
  for (size_t i = 0; i < L; i++) {
    res[i] = static_cast<uint8_t>((hex_digit(str[2 * i]) << 4) | hex_digit(str[(2 * i) + 1]));
  }
  return res;
}

// Compile-time evaluation of ML-KEM-512 keygen, encapsulation and decapsulation, using seeds from KAT vectors.
constexpr bool
eval_ml_kem_512()
{
  constexpr auto seed_d = from_hex<32>("7c9935a0b07694aa0c6d10e4db6b1add2fd81a25ccb148032dcd739936737f2d");
  constexpr auto seed_z = from_hex<32>("b505d7cfad1b497499323c8686325e4792f267aafa3f87ca60d01cb54f29202a");
  constexpr auto seed_m = from_hex<32>("eb4a7c66ef4eba2ddb38c88d8bc706b1d639002198172a7b1942eca8f6c001ba");

  std::array<uint8_t, ml_kem_512::PKEY_BYTE_LEN> pubkey{};
  std::array<uint8_t, ml_kem_512::SKEY_BYTE_LEN> seckey{};
  std::array<uint8_t, ml_kem_512::CIPHER_TEXT_BYTE_LEN> cipher{};
  std::array<uint8_t, ml_kem_512::SHARED_SECRET_BYTE_LEN> sender_key{};
  std::array<uint8_t, ml_kem_512::SHARED_SECRET_BYTE_LEN> receiver_key{};

  ml_kem_512::keygen(seed_d, seed_z, pubkey, seckey);
  const auto encaps_ok = ml_kem_512::encapsulate(seed_m, pubkey, cipher, sender_key);
  ml_kem_512::decapsulate(seckey, cipher, receiver_key);

  return encaps_ok && (sender_key == receiver_key);
}

int
main()
{
  // Entire ML-KEM-512 keygen + encaps + decaps round-trip, evaluated at compile-time.
  static_assert(eval_ml_kem_512(), "ML-KEM-512 keygen/encaps/decaps must be correct at compile-time");
  return 0;
}

The same pattern works for ML-DSA: compile-time keygen, signing and verification. This is not possible with any current PQCP implementation. This opens the door for moving most validations to program compilation time, instead of runtime.

One primary goal of these two libraries is to be high-assurance, by using modern C++ language features and compiler tooling to enforce strictness at compile-time - reduce runtime liabilities.

---

Known Gaps

• ml-dsa pre-hash mode is not yet implemented for SHA2 family of hash functions.
• Structure-aware fuzzing work not yet finalized.
• No constant-timeness enforcement using Valgrind (dynamic analysis) and Binsec (static/ symbolic analysis) yet. Work in progress.
• No platform specific optimisation yet - 4x SIMD parallel keccak-based hashing would bring better performance on table.
• No formal proof of memory safety or functional correctness.
• Neither implementation has been audited by third-party.

---

Performance

ml-kem-768:

Platform	keygen	encaps	decaps
Intel x86_64, GCC 14	19.3 µs	21.9 µs	25.8 µs
Graviton4 aarch64, GCC 13	28.8 µs	32.8 µs	39.3 µs

ml-dsa-65:

Platform	keygen	sign (min)	verify
Intel x86_64, GCC 14	82.1 µs	587 µs	86.3 µs
Graviton4 aarch64, GCC 13	126.2 µs	879 µs	134.4 µs

These are portable implementations without any platform-specific intrinsics or assembly, yet. These performance numbers are ~3x slower compared to baseline mlkem-native and mldsa-native, which feature 4x SIMD parallel keccak-based hashing and hand-optimized NTT implementation.

---

Dependency Chain

ml-kem CMake dependencies:

Dependency	Role	Main Author	License
subtle	Constant-time comparison utilities	@itzmeanjan	MIT
sha3	FIPS 202 hash functions and XOFs, used internally	@itzmeanjan	BSD-2-Clause
RandomShake	TurboSHAKE256-based CSPRNG, used in tests/examples only	@itzmeanjan	BSD-2-Clause
google-test	Test runner	Google	Apache 2.0
google-benchmark	Benchmark runner harness	Google	Apache 2.0

ml-dsa CMake dependencies:

Dependency	Role	Main Author	License
sha3	FIPS 202 hash functions and XOFs, used internally	@itzmeanjan	BSD-2-Clause
RandomShake	TurboSHAKE256-based CSPRNG, used in tests/examples only	@itzmeanjan	BSD-2-Clause
google-test	Test runner	Google	Apache 2.0
google-benchmark	Benchmark runner harness	Google	Apache 2.0

---

License

Current state:

• ml-kem is BSD-3-Clause
• ml-dsa is MIT
• All first-party CMake dependencies (sha3, subtle, RandomShake) are BSD-2-Clause or MIT

Plan:
We will open a dedicated GitHub issue in each affected repository, explicitly asking every contributor to confirm their consent to relicense their contributions under Apache 2.0. The contributor set is small:

• ml-kem: 3 contributors
• ml-dsa: 2 contributors
• sha3, subtle, RandomShake: 2 contributors

Once all consents are received, all LICENSE files, SPDX headers, and NOTICE files will be updated. Given the small set of external contributors, we expect this process to complete before or shortly after any TSC vote.

---

Governance Readiness

We will adopt the PQCA Code of Conduct and prepare CONTRIBUTING.md, SECURITY.md, and GOVERNANCE.md documents prior to onboarding. We understand and accept the requirement to transfer repository assets to the Linux Foundation upon acceptance. We target the Incubation stage of the PQCA Production project lifecycle.

---

Current Maintainers

• Anjan Roy (@itzmeanjan) — primary author and maintainer

We are seeking a second maintainer. Introductions from the TSC community — particularly anyone with C++ PQC interest — would be more than welcome.

---

Roadmap

1. Apache 2.0 relicensing — Open consent issues and complete the process across all affected repos.
2. Second maintainer — Recruit and onboard a maintainer from a separate organization.
3. Security audit — Engage a third-party auditor to formally assess timing safety and correctness. This is the most significant current gap relative to high-assurance status. Help from PQCP would really help make this happen.
4. Filling known gaps — We acknowledge there are gaps in these two implementations, which can be bridged to make them even more high-assurance. In coming days, improving upon that would stay on focus.

---

Community Interest

• ml-kem: 127 stars, 44 forks, 610 commits
• ml-dsa: 58 stars, 9 forks, 481 commits

No production deployments have been confirmed to date. The fork counts suggest active experimentation by others in the community.

---

Personal Opinion

I believe both of these projects ml-kem and ml-dsa, offer a genuinely complementary addition to the PQCP portfolio, serving the C++ developer ecosystem with a zero-dependency, fully compile-time-evaluable implementation that none of the existing sub-projects address. I welcome TSC feedback and I am happy to present at one of the upcoming TSC meetings.

---

References

• ml-kem: https://github.com/itzmeanjan/ml-kem
• ml-dsa: https://github.com/itzmeanjan/ml-dsa
• sha3: https://github.com/itzmeanjan/sha3
• subtle: https://github.com/itzmeanjan/subtle
• RandomShake: https://github.com/itzmeanjan/RandomShake
• NIST FIPS 203: https://doi.org/10.6028/NIST.FIPS.203
• NIST FIPS 204: https://doi.org/10.6028/NIST.FIPS.204

[mkannwischer]

@itzmeanjan - thanks for your proposal. @pq-code-package/pqcp-tsc, please review and discuss.

@itzmeanjan: Could you comment on any current or potential consumers of these implementations?

[itzmeanjan]

Thanks Matthias. @mkannwischer I'm not aware of any current consumers.

I don't also have any potential future customers in mind. Though I believe, many C++ projects should find both of these valuable, due to the added benefits.

[hanno-becker]

Hi @itzmeanjan,

Thank you for this well-documented proposal!

The central question for me is: What added value does a new project bring to consumers of the PQCP? My view is that collaboration on a small number of well-vetted implementations leads to better results than a large variety of different ones.

Three points stand out:

1. Beyond an idiomatic C++ API, I do not see a sufficient benefit over the existing mlkem/mldsa-native implementations. The compile-time evaluation capability is interesting, but I don't think it alone justifies a new project. I think the right approach is to provide language bindings to existing implementations, not to add entirely new ones.
2. ml-kem and ml-dsa come with no formal assurance beyond what the idiomatic use of the language gives you. All verification work is aspirational and without concrete plans, which in my mind does not pass the "high-assurance" bar of the PQCP.
3. ml-kem and ml-dsa do not consider the integration of performance optimizations. Experience shows that this tends to have major impact on library design.

Speaking for myself, I oppose the addition of ml-kem and ml-dsa as PQCP projects on these grounds. I appreciate the care in the API design, but I believe a new project needs to bring novel capabilities not achievable through existing projects, and meet a high bar for formal assurance and preferably also performance. That said, we are working on language bindings for mlkem/mldsa-native — a Rust binding is in progress. A C++ binding would be welcome and useful in the same vein, and given your experience, I'd be happy to collaborate on it.

Some more comments below.

Kind regards,
Hanno

---

The public API uses statically-sized std::span throughout — no raw pointers, no implicit buffer size arguments. No pointer arithmetic. Key, ciphertext, and signature sizes are encoded in the type system itself, making API misuse a compile-time error rather than a runtime bug.

The lack of idiomatic language bindings to existing PQCP projects is a gap, I agree. However, this gap should be filled by providing wrappers, not entirely new implementations. As an example, we are working on an idiomatic Rust binding for mlkem/mldsa-native. Similarly, I agree that for C++ users, a modern C++ binding would be desirable — but that should be a wrapper, not a new implementation.

The two libraries and all their first-party dependencies are fully constexpr - meaning not only one can fully compile-time evaluate them, they also prevent a class of core C++ language undefined behaviours (UB) such as buffer overflow, out of bounds access, use after free etc. - a feature required by C++ standard.

I agree that the principled use of such idioms can avoid classes of UB, similar to how Rust is inherently memory-safe. However, seeing that mlkem/mldsa-native are already proved memory-safe and type-safe using CBMC, I do not see added value here.

Known-answer test (KAT) vectors can be validated via static_assert at compile time, costing higher compilation latency but zero runtime cost. Compiler simply fails to compile the program if ml-kem or ml-dsa has a bug, that gets triggered by the deployed KAT.

This sounds more like a development convenience than a user-facing feature. A user should not rely on compile-time checks to validate the code, but instead should always test the final binary. And if they do, it is unclear what added benefit the slower compile-time check brings. The source of truth is ultimately the final binary.

For firmware and embedded C++ targets where seeds are known at build time, keys and shared secrets can be computed entirely by the compiler and baked into the binary as constants.

This is an interesting capability, but I'd like to see evidence that compile-time key generation is an established practice in embedded C++ deployments before accepting it as a justification for a new PQCP project.

[[nodiscard]] on for functions returning a value — the compiler warns if the caller ignores the return value. This prevents a class of API misuse bugs at compile time.

This is a property of the public API. For internal APIs, the same hardening already exists in mlkem/mldsa-native.

consteval parameter validation — invalid parameter combinations are rejected at compile time, not at runtime.
I don't think this has an equivalent on the C side. However, all function pre-conditions are expressed in CBMC and verified to be met at all call-sites.

We compile with -Wall -Wextra -Wpedantic ... compiler flags
clang-tidy based static analysis is integrated ...

While useful, I don't see the usage of those flags/tools as a distinguishing feature of any implementation.

[itzmeanjan]

Hi @hanno-becker ,

Thanks for your feedback.

The central question for me is: What added value does a new project bring to consumers of the PQCP? My view is that collaboration on a small number of well-vetted implementations leads to better results than a large variety of different ones.

• The guarantees a fully constexpr implementation brings, can't be replicated by building wrappers on top of a C/assembly implementation. At least not today.
• std::span based API essentially prevents a large class of issues at program compile-time itself, which one would discover only after running the program, when written in C.
• std::span based API allows use to resolve all subspan arithmetic (think pointer arithmetic) at program compile-time itself. Much better than discovering it at runtime, with ASAN.
• To provide better constant-timeness guarantees I continue working on Is it actually constant-time? itzmeanjan/subtle#7, which is used in ml-kem. And the learning from that PR on various techniques such as integrating symbolic analysis tool binsec, to be applied on ml-kem and ml-dsa. This would make ml-kem and ml-dsa much more reliable.
• We have a very clear pathway of how to do 4x SIMD parallel keccak hashing, for faster ml-kem and ml-dsa. In my recent presentation at RWPQC (see slides linked at my personal website https://itzmeanjan.in/pages/talks.html), I showed there is a 3x gap between mlkem-native (the state of the art baseline) and ml-kem (the one I'm proposing). And with AVX2+NEON backend support, we can make that gap much smaller.
• To add more to constexpr - it prevents core language UB, at program compile-time. C language at its current form, can't do that which requires one to use other tools which are not part of core language. It's always better to have some feature part of the language itself.
• The use of clang-tidy and enabling all compiler warnings (and treating any warnings as errors) is not a feature of the implementation on itself. Though it shows that the implementation doesn't have any such issues. But one can very easily replicate that in a C implementation. And that should be the case. Happy to work on that front.
• Given that ml-kem and ml-dsa both are libraries, our first class users are developers. And having the ability of running a KAT validation pipeline on whole or part of ML-KEM or ML-DSA, at program compile-time, is a useful feature. A programmer would want that.

Simply, there are some values, which ml-kem and ml-dsa brings on the table, which can be replicated on a C/ assembly library or by building a C++/ Rust wrapper. And there are some, which can't today be replicated. One needs a pure language implementation for that. And working with cross-language wrappers were never great - speaking as a software engineer. Assumptions break at language boundaries. Having a first class implementation in a language which can exploit the features the language has to offer is actually great.

I'd not argue that ml-kem and ml-dsa improves upon mlkem-native and mldsa-native from all points of views. It can never. Nor would mlkem-native and mldsa-native be able to completely supersede ml-kem and ml-dsa, at least not anytime soon, given how slow the C language ISO committee moves. Also ml-kem would never match mlkem-native performance, we can reduce the gap, drastically. Right now we are 3x apart, we can be much closer. That's all because of these memory safety abstractions - there are never truly zero-cost. Given that I'd like to represent my proposal as a mere addition, not a replacement for anything existing.

[hanno-becker]

@itzmeanjan Thank you for the reply. I don't see additional arguments though regarding the added value that the new implementations bring. My position is thus unchanged.

I think it's best to hear more opinions from @pq-code-package/pqcp-tsc at this point.

[mkannwischer]

During the 2026-03-19 TSC meeting @itzmeanjan presented his proposal and a number of questions have been discussed. I'll upload the minutes tomorrow, please take a look. @itzmeanjan, could you share the slides you have presented during the meeting?

The TSC has decided to continue discussions in this issue for another week until March 26, 2026. Then we will do an offline vote to approve/reject the proposal until April 2, 2026.

@pq-code-package/pqcp-tsc, please continue to discuss here.

[mkannwischer]

@itzmeanjan, there are two non-technical points I would like to confirm before the vote:

1. The PQCP Charter, Section 7, requires all incoming projects to be Apache 2.0 licensed. Could you confirm that, should the projects be admitted to the PQCP, you will relicense them to Apache 2.0 prior to moving them under the PQCP umbrella?

2. Our practice has been to require at least two maintainers to ensure long-term maintainability. Could you confirm that you will add another maintainer prior to joining the PQCP?

If we can make admission conditional on these two points, the vote can focus exclusively on the technical merits of the proposal.

[itzmeanjan]

could you share the slides you have presented during the meeting?

I prepared these slides on Libreoffice. Not sure how it would render on other presentation software.
pqcp-tsc-presentation.odp

[itzmeanjan]

The PQCP Charter, Section 7, requires all incoming projects to be Apache 2.0 licensed. Could you confirm that, should the projects be admitted to the PQCP, you will relicense them to Apache 2.0 prior to moving them under the PQCP umbrella?

I can confirm that both ml-kem and ml-dsa, including their first-party dependencies for constant-timeness and sha3 hashing, will be relicensed to Apache 2.0. I am the author of all those libraries. They are all linked in my proposal.

Our practice has been to require at least two maintainers to ensure long-term maintainability. Could you confirm that you will add another maintainer prior to joining the PQCP?

For past three and half years, I was the sole maintainer of these two projects. In the other words, they started as my weekend projects. I do not have another maintainer ready to jump in. So I will start looking for one. I will post on LinkedIn, if that interests some.

That being said, I'd like to stress, even if I do not find another eligible maintainer, I will be there to continue maintaining it, as I have been doing for past years. These are my pet projects, so I will always want to see them successful, i.e., deployed in real-world. And I will continue putting effort from my side, even if they get the chance of moving under PQCP umbrella.

[itzmeanjan]

An update on AVX2 intrinsic based backend support (PR itzmeanjan/ml-kem#76) on ml-kem C++20 library. I'm working on adding 4x SIMD parallel hashing backend for sampling part of ml-kem, on x86 target.

Following are the numbers for ml-kem-768 parameter, run on Intel x86_64, machine, compiled with GCC-15.2.

A. mlkem-native (C backend + AVX2 FIPS 202 hashing) vs. mlkem C++ (AVX2 hashing)

It takes ~5% more time to run mlkem (C++) compared to the baseline of mlkem-native.

B. mlkem-native (Full assembly backend) vs. mlkem C++ (AVX2 hashing)

It takes ~106% more time to run mlkem (C++) compared to the baseline of mlkem-native.

I demonstrated the ratio for case B in my RWPQC 2026 presentation - it was ~3.
Now as we have partial support for avx2 hashing backend, the ratio has dropped to ~2.

[mkannwischer]

Thanks @itzmeanjan for providing the additional data!

The vote has now opened and we hope to have votes in by Thursday, April 2nd at 11:59 PT.
@pq-code-package/pqcp-tsc, please vote. If there are any questions or you did not get the invitation to vote, please contact me.

[itzmeanjan]

Thanks @itzmeanjan for providing the additional data!

The vote has now opened and we hope to have votes in by Thursday, April 2nd at 11:59 PT. @pq-code-package/pqcp-tsc, please vote. If there are any questions or you did not get the invitation to vote, please contact me.

Thank you very much for oraganizing the vote @mkannwischer 🙏