C κΈ°λ° PQC λͺ¨λ κ°μΈ νλ‘μ νΈμ
λλ€.
λͺ©νλ KEM + Signatureλ₯Ό κ³΅ν΅ API/CLI/ν
μ€νΈ/λ²€μΉλ§ν¬/λ¬ΈμνκΉμ§ μ°κ²°ν΄μ μ€μ κ°λ° μλμ 보μ¬μ£Όλ κ²μ
λλ€.
| Focus | Summary |
|---|---|
| Why this architecture | pqc_module(κ³΅ν΅ μΈν°νμ΄μ€)μ pqc_kem/pqc_sig(μκ³ λ¦¬μ¦ κ³μΈ΅)λ₯Ό λΆλ¦¬ν΄, CLI/ν
μ€νΈ μ½λλ₯Ό μ μ§ν μ± λ°±μλ(Dummy β PQClean Ref)λ₯Ό κ΅μ²΄ν μ μλλ‘ μ€κ³νμ΅λλ€. |
| Direct project value | κ³΅ν΅ API, μν μ½λ κΈ°λ° μ€λ₯ νλ¦, CLI/ν μ€νΈ/λ²€μΉλ§ν¬/CI μ°κ²°, KAT/λ³μ‘°/μ€ν¨ κ²½λ‘ κ²μ¦μ μ§μ μ€κ³νκ³ ν΅ν©νμ΅λλ€. |
| Security boundary | νμ΅/μ°Έμ‘° ꡬν ν΅ν©μ΄ λͺ©μ μ΄λ©°, side-channel λμ, production hardening, thread-safety, μΈμ¦(FIPS/KCMVP), μ΄μ ν€κ΄λ¦¬(HSM/κ°μ¬μΆμ )λ νμ¬ λ²μ λ°μ λλ€. |
| Test evidence | μ μ κ²½λ‘(λΌμ΄λνΈλ¦½/KAT) + μ€ν¨ κ²½λ‘(λ³μ‘° μ λ ₯, κΈΈμ΄ μ€λ₯, λΉ λ©μμ§, λλ½/μμ νμΌ)λ₯Ό CIμμ μλ κ²μ¦ν©λλ€. |
flowchart LR
U["User / CI"] --> CLI["pqc_cli (src/main.c)"]
CLI --> API["pqc_module API (include/pqc_module.h)"]
API --> KEM["pqc_kem backend selector"]
API --> SIG["pqc_sig backend selector"]
KEM --> DKM["Dummy ML-KEM"]
KEM --> RKM["PQClean ML-KEM Ref"]
SIG --> DSI["Dummy ML-DSA"]
SIG --> RSI["PQClean ML-DSA Ref"]
API --> T["Tests (ctest)"]
API --> B["Benchmark (pqc_cli benchmark)"]
Latest sample (mlkem-ref + mldsa-ref, iterations=1000):
| KEM keygen (ms) | KEM encaps (ms) | KEM decaps (ms) | SIG keygen (ms) | SIG sign (ms) | SIG verify (ms) |
|---|---|---|---|---|---|
| 0.402 | 0.420 | 0.102 | 0.547 | 1.326 | 0.230 |
μ°Έκ³ : νκ²½/μ»΄νμΌ μ΅μ
μ λ°λΌ κ°μ λ¬λΌμ§ μ μμΌλ©°, μλ³Έ κ²°κ³Όλ bench_result.csvμ docs/benchmark.mdλ₯Ό κΈ°μ€μΌλ‘ κ°±μ ν©λλ€.
μ΄ νλ‘μ νΈλ κ³΅ν΅ API κ³μΈ΅(pqc_module)κ³Ό μκ³ λ¦¬μ¦ μ’
μ κ³μΈ΅(pqc_kem, pqc_sig)μ λΆλ¦¬ν ꡬ쑰μ
λλ€.
μ΄λ κ² λΆλ¦¬νλ©΄ CLI/ν
μ€νΈ μ½λλ₯Ό μ μ§ν μ± λ°±μλ(λλ―Έ β PQClean μ°Έμ‘° ꡬν)λ₯Ό κ΅μ²΄ν μ μμ΄, ꡬν λ³κ²½ λλΉ κ²μ¦/λ¬Έμ/μ΄μ νλ¦μ μμ μ μΌλ‘ μ μ§ν μ μμ΅λλ€.
μ΄ μ μ₯μλ νμ΅/μ°Έμ‘° ꡬν ν΅ν© μ€μ¬μ
λλ€.
μ¦, side-channel μν, production hardening, thread-safety, μΈμ¦ λμ(FIPS/KCMVP), μ΄μ ν€κ΄λ¦¬(HSM/κ°μ¬μΆμ )λ νμ¬ λ²μμ ν¬ν¨νμ§ μμ΅λλ€.
λλ―Έ λ°±μλλ API/CLI/ν
μ€νΈ νλ¦ κ²μ¦μ©μ΄λ©°, rand() κΈ°λ° ν
μ€νΈ RNGλ₯Ό μ¬μ©νλ―λ‘ μνΈνμ μ©λλ‘ μ¬μ©νλ©΄ μ λ©λλ€.
| What | Current Coverage |
|---|---|
| KEM correctness | roundtrip/repeat/tamper (test_kem, test_ref_kem) |
| Signature correctness | roundtrip/tamper/length/empty message (test_sig) |
| KAT-style check | stored ML-DSA vector verify + stored secret-key sign/verify (test_kat_mldsa) |
| Failure-case handling | tampered ciphertext/signature, invalid lengths, empty message, missing/corrupted input files |
| CI/Quality | Linux+Windows CI, cppcheck quality workflow |
- API:
pqc_kem_keypair,pqc_kem_encaps,pqc_kem_decaps - CLI:
keygen,encaps,decaps - μκ³ λ¦¬μ¦ μ ν:
--alg <dummy|mlkem-ref>
- API:
pqc_sig_keypair,pqc_sig_sign,pqc_sig_verify - CLI:
sig-keygen,sign,verify - μκ³ λ¦¬μ¦ μ ν:
--sig-alg <dummy-dsa|mldsa-ref>
- 곡μ λ²€μΉ μνΈλ¦¬ν¬μΈνΈλ
pqc_cli benchmarkνλλ‘ ν΅μΌλμ΄ μμ΅λλ€. bench/parse_results.pyλ λ²€μΉ κ²°κ³Ό(TXT/CSV) μμ½ νμμ λλ€.
| Area | Dummy | PQClean Ref | Notes |
|---|---|---|---|
| ML-KEM-768 | Yes | Yes (mlkem-ref) |
KEM keygen/encaps/decaps ꡬν |
| ML-DSA-65 | Yes | Yes (mldsa-ref) |
Signature keygen/sign/verify ꡬν |
| CLI | Yes | Yes | KEM/Signature/Benchmark ν΅ν© |
| Tests | Yes | Yes | λ¨μ/μμ±/KAT ν¬ν¨ |
| CI | Yes | Yes | Linux + Windows(MSYS2 MinGW) |
| Condition | KEM Backend | Signature Backend |
|---|---|---|
third_party/mlkem_pqclean + common μ‘΄μ¬, third_party/mldsa_pqclean μ‘΄μ¬ |
Dummy + ML-KEM Ref | Dummy + ML-DSA Ref |
| ML-KEM κ²½λ‘ λ―Έμ‘΄μ¬ | Dummy only | (ML-DSA 쑰건μ λ°λ¦) |
| ML-DSA κ²½λ‘ λ―Έμ‘΄μ¬ | (ML-KEM 쑰건μ λ°λ¦) | Dummy only |
μ°Έκ³ :
- KEM Ref νμ± νλκ·Έ:
PQC_ENABLE_MLKEM_REF - Signature Ref νμ± νλκ·Έ:
PQC_ENABLE_MLDSA_REF
pqc-crypto-module-lab/
ββ CMakeLists.txt
ββ README.md
ββ docs/
β ββ architecture.md
β ββ benchmark.md
β ββ security.md
β ββ cli.md
β ββ troubleshooting.md
β ββ portfolio-summary.md
ββ include/
β ββ pqc_module.h
ββ src/
β ββ main.c
β ββ pqc_module.c
β ββ pqc_kem.c
β ββ pqc_sig.c
β ββ pqc_kem_backend.h
β ββ pqc_sig_backend.h
β ββ pqc_utils.c
ββ tests/
β ββ test_kem.c
β ββ test_ref_kem.c
β ββ test_sig.c
β ββ test_negative.c
β ββ test_kat_mldsa.c
β ββ data/
β ββ bad.ct
β ββ bad.sec
β ββ kat_mldsa_msg.txt
β ββ kat_mldsa_pub.key
β ββ kat_mldsa_sec.key
β ββ kat_mldsa.sig
ββ bench/
β ββ parse_results.py
ββ third_party/
β ββ mlkem_pqclean/
β ββ mldsa_pqclean/
β ββ README.md
ββ scripts/
β ββ build_linux.sh
β ββ build_windows.bat
β ββ run_all.sh
β ββ run_all_windows.bat
ββ .github/workflows/
ββ ci.yml
ββ quality.yml
ββ codeql.yml
cmake -S . -B build
cmake --build buildWarning policy:
- GCC/Clang builds enable
-Wall -Wextra -Wpedantic. - MSVC builds enable
/W4. - Third-party reference code is kept vendored and documented separately; project code should stay warning-clean under the enabled policy.
Windows μμ:
set CMAKE_EXE=C:\path\to\cmake.exe
set CC=C:\path\to\gcc.exe
set TOOLCHAIN_BIN=C:\path\to\w64devkit\bin
scripts\build_windows.bat./build/pqc_cli info --alg mlkem-ref --sig-alg mldsa-ref
./build/pqc_cli keygen --alg mlkem-ref --pub kem_pub.key --sec kem_sec.key
./build/pqc_cli sig-keygen --sig-alg mldsa-ref --pub sig_pub.key --sec sig_sec.key
./build/pqc_cli sign --sig-alg mldsa-ref --sec sig_sec.key --msg message.txt --sig message.sig
./build/pqc_cli verify --sig-alg mldsa-ref --pub sig_pub.key --msg message.txt --sig message.sig
./build/pqc_cli benchmark --alg mlkem-ref --sig-alg mldsa-ref --iterations 1000 --out bench_result.csvctest --test-dir build --output-on-failureν μ€νΈ λ²μ μμ½:
- KEM roundtrip/repeat/tamper
- Signature roundtrip/tamper/empty message/length error
- CLI νμΌ μ€λ₯ μΌμ΄μ€
- ML-DSA KAT(μ μ₯λ λ²‘ν° verify + μ μ₯λ secret key sign/verify)
| Test | Purpose |
|---|---|
test_kem |
KEM μ μ/λ°λ³΅/λ³μ‘° ciphertext μ€ν¨ |
test_ref_kem |
ML-KEM μ°Έμ‘° λ°±μλ roundtrip |
test_sig |
μλͺ μ μ/λ³μ‘°/κΈΈμ΄ μ€λ₯/λΉ λ©μμ§ |
test_kat_mldsa |
μ μ₯λ ML-DSA λ²‘ν° verify, μ μ₯λ secret key sign/verify, λ³μ‘° signature/public key μ€ν¨ |
test_negative |
μκ³ λ¦¬μ¦/μ λ ₯ μ€λ₯ μ²λ¦¬ |
cli_missing_input_file |
CLI μ λ ₯ νμΌ λλ½ μ€ν¨ |
cli_corrupted_key_file |
CLI μμ ν€ νμΌ μ€ν¨ |
quality.yml |
cppcheck κΈ°λ° μ μ μ κ² μλν |
- νλ‘μ νΈλ PQClean μ°Έμ‘° ꡬνμ ν΅ν©ν΄ λμν©λλ€.
- KAT μ±κ²©μ κ²μ¦μ νμ¬ μ μ₯λ ML-DSA 곡κ°ν€/λΉλ°ν€/λ©μμ§/μλͺ 벑ν°λ₯Ό μ¬μ©ν©λλ€.
- μλν λ²μ: μ μ₯λ μλͺ verify, μ μ₯λ secret key κΈ°λ° signβverify, λ³μ‘° signature/public key μ€ν¨ νμΈ.
- μμ§ NIST/PQClean 곡μ λ²‘ν° μ 체λ₯Ό μλ λ°λ³΅νλ μνλ μλλλ€.
- ν₯ν κ°μ : NIST/PQClean 곡μ λ²‘ν° κΈ°λ° μλ KAT νμ₯.
- λ―Όκ° λ°μ΄ν°(λΉλ°ν€/곡μ λΉλ°/μλͺ λ΄λΆκ°) μλ¬Έμ λ‘κ·Έμ μΆλ ₯νμ§ μμ΅λλ€.
- λ―Όκ° λ²νΌλ
secure_memzeroλ‘ μ 리ν©λλ€. - λλ―Έ μκ³ λ¦¬μ¦μ
rand()κΈ°λ° ν μ€νΈ RNGλ₯Ό μ¬μ©νλ―λ‘ production μ¬μ© κΈμ§μ λλ€. - νμ± μκ³ λ¦¬μ¦ μ νμ νλ‘μΈμ€ μ μ μνλ₯Ό μ¬μ©νλ―λ‘ thread-safe APIκ° μλλλ€.
- constant-time/side-channel μμ λμμ νμ¬ λ²μ λ°μ λλ€.
- μ΄ μ μ₯μλ νμ΅/ν¬νΈν΄λ¦¬μ€ λͺ©μ μ΄λ©° μμ© λ°°ν¬ μμ€μ 보μ¦μ μ 곡νμ§ μμ΅λλ€.
GitHub Actions (.github/workflows/ci.yml):
- Ubuntu: configure/build/test + smoke benchmark
- Windows(MSYS2 MinGW): configure/build/test + smoke benchmark
- λ νκ²½ λͺ¨λ benchmark CSV νμ± ν
bench_summary.txtμμ± - benchmark μ°μΆλ¬Ό(
bench_result.csv,bench_summary.txt) μν°ν©νΈ μ λ‘λ
μ μ μ κ² (.github/workflows/quality.yml):
cppcheckμ€ν (warning/style/performance/portability)
보μ μ κ² (.github/workflows/codeql.yml):
- CodeQL C/C++ λΆμ (push/PR + μ£Όκ° μ€μΌμ€)
GitHub Aboutμ μλ κ°μ κΆμ₯ν©λλ€.
- Description:
C-based PQC crypto module lab integrating ML-KEM-768 and ML-DSA-65 with unified API, CLI, tests, benchmarks, and CI.
- Topics:
pqc,ml-kem,ml-dsa,cryptography,c,cmake,pqclean