CIRCL (Cloudflare Interoperable, Reusable Cryptographic Library) is a collection of cryptographic primitives written in Go. The goal of this library is to be used as a tool for experimental deployment of cryptographic algorithms targeting Post-Quantum (PQ) Cryptography.
🚨 This library is offered as-is, and without a guarantee. Therefore, it is expected that changes in the code, repository, and API occur in the future. We recommend to take caution before using this library in a production application since part of its content is experimental. All security issues must be reported, please notify us immediately following the instructions given in our Security Policy.
group/, oprf/, blindsign/, secretsharing/, tss/rsa/, zk/, ecc/p384/) have all been removed from this fork; the packages retained here are implemented to be constant time in their core operations.
🔒 This fork is purpose-built for QuantumCoin blockchain and is not offered as a general-purpose cryptographic library.
It is supported only for building and operating QuantumCoin nodes, wallets, dApps and tooling. Every design decision, security review and applicability assessment in this repository assumes that narrow deployment context. Concretely, this means:
- Analysis is scoped to known consumers. The security review in
SECURITY_AUDIT.mdestablishes whether each finding is reachable by tracing call sites in the QuantumCoin node and SDKs at specific commits. Those conclusions are evidence about those consumers, not general statements about the library. - The schemes depend on caller-side invariants. The hybrid signature schemes rely on properties the library does not itself enforce — for example that identity is derived from a hash of the complete composite public key, that messages are exactly 32 bytes, and that randomness comes from a CSPRNG. These hold in QuantumCoin software; they are not guaranteed for arbitrary callers. The audit index lists them explicitly.
- Some schemes implement pre-standardization drafts. Schemes 1–2 realize Round 3 Dilithium2 and SPHINCS+, not the finalized FIPS 204 / FIPS 205 algorithms, and are retained for wallet backward compatibility.
- No FIPS conformance or CMVP validation is claimed for any part of this fork.
If you need general-purpose post-quantum cryptography in Go, use upstream Cloudflare CIRCL rather than this fork.
This repository is a fork of CIRCL that adds hybrid digital signature schemes combining classical (Ed25519) and post-quantum (lattice-based and hash-based) components. Hybrid signatures reduce single-point-of-failure risk: if one algorithm family is broken — whether classical or PQC — the remaining components still protect authenticity. The QuantumCoin blockchain uses these hybrid PQC signature schemes.
| Scheme ID | Package | Mode | Components | PK + Sig | Verify ops/s¹ |
|---|---|---|---|---|---|
| 1 | hybrideds | Compact | Ed25519 + Dilithium2 (SPHINCS+ key present, not signed) | 3,966 B | ~10,970 |
| 2 | hybrideds | Full | Ed25519 + Dilithium2 + SPHINCS+-SHAKE-256f | 53,782 B | ~270 |
| 3 | hybridedmldsaslhdsa | Compact | Ed25519 + ML-DSA-44 (SLH-DSA key present, not signed) | 3,926 B | ~9,980 |
| 4 | hybridedmldsaslhdsa | Full | Ed25519 + ML-DSA-44 + SLH-DSA-SHAKE-256f | 53,782 B | ~290 |
| 5 | hybridedmldsaslhdsa5 | Full | Ed25519 + ML-DSA-87 + SLH-DSA-SHAKE-256s (NIST Level 5) | 37,205 B | ~470 |
¹ Verify operations per second measured with go test -bench on an AMD Ryzen 7 5800X (single-threaded, Go 1.24, Windows/amd64).
These hybrid schemes do not modify any underlying cryptographic primitive; each component algorithm is invoked exactly as specified by its NIST standard. This approach is consistent with NIST guidance on combining NIST-approved and post-quantum signature algorithms as a transition strategy to post-quantum cryptography (see NIST IR 8547).
Compact mode signs with Ed25519 and the lattice-based component only (ML-DSA or Dilithium). The hash-based component's (SLH-DSA / SPHINCS+) public key is part of the composite key but is not used for signing — keeping signatures small and verification fast. Full mode signs with all three components; it can serve as a break-glass mechanism (activated when an imminent threat is detected) or as the default signing mode for maximum assurance.
Schemes 3–5 conform to finalized NIST standards: ML-DSA (FIPS 204), SLH-DSA (FIPS 205), and Ed25519 ([FIPS 186-5] § 7.8). They use context strings for domain separation in ML-DSA and SLH-DSA signing. For new designs, prefer schemes 3–5. Schemes 1–2 use pre-final NIST drafts (Dilithium / SPHINCS+) and a nonce-based compact construction; see the hybrideds README for details.
For audit, validation, and independent per-component verification of hybrid signatures (e.g. cross-checking against PQClean, liboqs, or other implementations), see the hybridparser package. It provides:
- ParseHybrid: verify a hybrid signature and extract per-component public keys and signatures (hex-encoded) for independent re-verification.
- CheckHybrid: reconstruct and verify using both the composite hybrid verifier and each component's verifier.
The hybridparser README describes how to decode the hex components and pass them to external DSA implementations for conformance audits against FIPS 204, FIPS 205, and FIPS 186-5. Use hybridparser for audit and tooling only; production verification must use each hybrid scheme's own APIs.
This fork maintains an ongoing internal security review of the hybrid signature schemes and their supporting code. Results are published in SECURITY_AUDIT.md, with detailed write-ups in audit/, rather than kept private, so that integrators and external reviewers can see what has been examined, what was found, and what remains open.
Start with the audit index. It lists every recorded finding with its severity, links to the detailed write-ups, and — separately from severity — states whether each issue is actually reachable in the library's intended consumers.
A few conventions worth knowing:
- Findings are only recorded once confirmed by executing code, never by inspection alone. Anything that could not be reproduced is discarded rather than listed speculatively.
- Severity and reachability are rated on two independent axes, each with published criteria, so ratings are reproducible rather than intuitive. Severity describes the defect in the code itself, judged without assuming any particular caller; reachability describes whether a supported consumer API can actually trigger it, pinned to specific consumer commits. Deliberately separating them means a genuine defect is neither overstated nor dismissed merely because no current consumer reaches it — the index states both directions explicitly.
- Findings carry a CWE classification where one fits, and the reachability axis follows VEX justification semantics.
- Where practical, findings ship with executable tests in the affected package, so each documented issue can be independently reproduced and so that a future fix produces a visible signal.
Please continue to report security issues through our Security Policy; the audit directory documents review findings and is not a substitute for coordinated disclosure.
You can get CIRCL by fetching:
go get -u github.com/quantumcoinproject/circlAlternatively, look at the Cloudflare Go fork to see how to integrate CIRCL natively in Go.
| KEM: Key Encapsulation Methods |
|---|
- ML-KEM: modes 512, 768, 1024 (FIPS-203).
- X25519MLKEM768: hybrid KEM of ML-KEM-768 and X25519 (draft-kwiatkowski-tls-ecdhe-mlkem).
| Digital Signature Schemes |
|---|
- ML-DSA: modes 44, 65, 87 (FIPS 204).
- SLH-DSA: twelve parameter sets, pure and pre-hash signing (FIPS 205).
| XOF: eXtendable Output Functions |
|---|
- SHAKE128 and SHAKE256 (FIPS 202).
- BLAKE2X: BLAKE2XB and BLAKE2XS (Blake2x)
- KangarooTwelve: fast hashing based on Keccak-p. (KangarooTwelve).
- SIMD Keccak f1600 Permutation.
| Integers |
|---|
- Safe primes generation.
- Integer encoding: wNAF, regular signed digit, mLSBSet representations.
| Finite Fields |
|---|
- Fp25519.
Library comes with number of make targets which can be used for testing and benchmarking:
testperforms testing of the binary.benchruns benchmarks.coverproduces coverage.lintruns set of linters on the code base.
To contribute, fork this repository and make your changes, and then make a Pull Request. A Pull Request requires approval of the admin team and a successful CI build.
To cite CIRCL, use one of the following formats and update the version and date you accessed this project.
APA Style
Faz-Hernandez, A. and Kwiatkowski, K. (2019). Introducing CIRCL:
An Advanced Cryptographic Library. Cloudflare. Available at
https://github.com/cloudflare/circl. v1.6.1 Accessed Apr, 2025.
BibTeX Source
@manual{circl,
title = {Introducing CIRCL: An Advanced Cryptographic Library},
author = {Armando Faz-Hernandez and Kris Kwiatkowski},
organization = {Cloudflare},
abstract = {{CIRCL (Cloudflare Interoperable, Reusable Cryptographic Library) is
a collection of cryptographic primitives written in Go. The goal
of this library is to be used as a tool for experimental
deployment of cryptographic algorithms targeting Post-Quantum (PQ)}},
note = {Available at \url{https://github.com/cloudflare/circl}. v1.6.1 Accessed Apr, 2025},
month = jun,
year = {2019}
}CFF Style
See attached CITATION.cff file.
The project is licensed under the BSD-3-Clause License.