From 3a9f2abfd585a5e6bd007b27c9fb35efe21063d8 Mon Sep 17 00:00:00 2001 From: "Ganyu (Bruce) Xu" Date: Thu, 25 Sep 2025 12:17:44 -0400 Subject: [PATCH] documentation; make primary implementation monospaced Signed-off-by: Ganyu (Bruce) Xu --- README.md | 48 ++++++++++++++--------------- scripts/update_alg_support_table.py | 15 ++++++--- 2 files changed, 34 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 08ec33864..722979bb9 100644 --- a/README.md +++ b/README.md @@ -55,34 +55,34 @@ All names other than `ML-KEM` and `ML-DSA` are subject to change. `liboqs` makes ### KEMs -| Algorithm family | Standardization status | Primary implementation | -|:--------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------| -| [NTRU-Prime](./docs/algorithms/kem/ntruprime.md) | [Not selected](https://csrc.nist.gov/CSRC/media/Projects/post-quantum-cryptography/documents/round-3/submissions/NTRU-Prime-Round3.zip) | [PQClean/PQClean@4c9e5a3](https://github.com/PQClean/PQClean/commit/4c9e5a3aa715cc8d1d0e377e4e6e682ebd7602d6) | -| [HQC](./docs/algorithms/kem/hqc.md) | [Selected by NIST](https://pqc-hqc.org/doc/hqc_specifications_2025_08_22.pdf) | [PQClean/PQClean@1eacfda](https://github.com/PQClean/PQClean/commit/1eacfdafc15ddc5d5759d0b85b4cef26627df181) | -| [FrodoKEM](./docs/algorithms/kem/frodokem.md) | [Not selected](https://csrc.nist.gov/CSRC/media/Projects/post-quantum-cryptography/documents/round-3/submissions/FrodoKEM-Round3.zip) | [microsoft/PQCrypto-LWEKE@b6609d3](https://github.com/microsoft/PQCrypto-LWEKE/commit/b6609d30a9982318d7f2937aa3c7b92147b917a2) | -| [BIKE](./docs/algorithms/kem/bike.md) | [Not selected](https://csrc.nist.gov/csrc/media/Projects/post-quantum-cryptography/documents/round-4/submissions/BIKE-Round4.zip) | [awslabs/bike-kem](https://github.com/awslabs/bike-kem) | -| [NTRU](./docs/algorithms/kem/ntru.md) | [Not selected](https://csrc.nist.gov/CSRC/media/Projects/post-quantum-cryptography/documents/round-3/submissions/NTRU-Round3.zip) | [PQClean/PQClean@4c9e5a3](https://github.com/PQClean/PQClean/commit/4c9e5a3aa715cc8d1d0e377e4e6e682ebd7602d6) | -| [ML-KEM](./docs/algorithms/kem/ml_kem.md) | [Standardized by NIST](https://csrc.nist.gov/pubs/fips/203/final) | [pq-code-package/mlkem-native@048fc2a](https://github.com/pq-code-package/mlkem-native/commit/048fc2a7a7b4ba0ad4c989c1ac82491aa94d5bfa) | -| [Classic McEliece](./docs/algorithms/kem/classic_mceliece.md) | [Under ISO consideration](https://classic.mceliece.org/mceliece-spec-20221023.pdf) | [PQClean/PQClean@1eacfda](https://github.com/PQClean/PQClean/commit/1eacfdafc15ddc5d5759d0b85b4cef26627df181) | -| [Kyber](./docs/algorithms/kem/kyber.md) | [Selected by NIST](https://csrc.nist.gov/CSRC/media/Projects/post-quantum-cryptography/documents/round-3/submissions/Kyber-Round3.zip) | [pq-crystals/kyber@441c051](https://github.com/pq-crystals/kyber/commit/441c0519a07e8b86c8d079954a6b10bd31d29efc) | +| Algorithm family | Standardization status | Primary implementation | +|:--------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------| +| [NTRU-Prime](./docs/algorithms/kem/ntruprime.md) | [Not selected](https://csrc.nist.gov/CSRC/media/Projects/post-quantum-cryptography/documents/round-3/submissions/NTRU-Prime-Round3.zip) | [`PQClean/PQClean@4c9e5a3`](https://github.com/PQClean/PQClean/commit/4c9e5a3aa715cc8d1d0e377e4e6e682ebd7602d6) | +| [HQC](./docs/algorithms/kem/hqc.md) | [Selected by NIST](https://pqc-hqc.org/doc/hqc_specifications_2025_08_22.pdf) | [`PQClean/PQClean@1eacfda`](https://github.com/PQClean/PQClean/commit/1eacfdafc15ddc5d5759d0b85b4cef26627df181) | +| [FrodoKEM](./docs/algorithms/kem/frodokem.md) | [Not selected](https://csrc.nist.gov/CSRC/media/Projects/post-quantum-cryptography/documents/round-3/submissions/FrodoKEM-Round3.zip) | [`microsoft/PQCrypto-LWEKE@b6609d3`](https://github.com/microsoft/PQCrypto-LWEKE/commit/b6609d30a9982318d7f2937aa3c7b92147b917a2) | +| [BIKE](./docs/algorithms/kem/bike.md) | [Not selected](https://csrc.nist.gov/csrc/media/Projects/post-quantum-cryptography/documents/round-4/submissions/BIKE-Round4.zip) | [`awslabs/bike-kem`](https://github.com/awslabs/bike-kem) | +| [NTRU](./docs/algorithms/kem/ntru.md) | [Not selected](https://csrc.nist.gov/CSRC/media/Projects/post-quantum-cryptography/documents/round-3/submissions/NTRU-Round3.zip) | [`PQClean/PQClean@4c9e5a3`](https://github.com/PQClean/PQClean/commit/4c9e5a3aa715cc8d1d0e377e4e6e682ebd7602d6) | +| [ML-KEM](./docs/algorithms/kem/ml_kem.md) | [Standardized by NIST](https://csrc.nist.gov/pubs/fips/203/final) | [`pq-code-package/mlkem-native@048fc2a`](https://github.com/pq-code-package/mlkem-native/commit/048fc2a7a7b4ba0ad4c989c1ac82491aa94d5bfa) | +| [Classic McEliece](./docs/algorithms/kem/classic_mceliece.md) | [Under ISO consideration](https://classic.mceliece.org/mceliece-spec-20221023.pdf) | [`PQClean/PQClean@1eacfda`](https://github.com/PQClean/PQClean/commit/1eacfdafc15ddc5d5759d0b85b4cef26627df181) | +| [Kyber](./docs/algorithms/kem/kyber.md) | [Selected by NIST](https://csrc.nist.gov/CSRC/media/Projects/post-quantum-cryptography/documents/round-3/submissions/Kyber-Round3.zip) | [`pq-crystals/kyber@441c051`](https://github.com/pq-crystals/kyber/commit/441c0519a07e8b86c8d079954a6b10bd31d29efc) | ### Digital signatures -| Algorithm family | Standardization status | Primary implementation | -|:---------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------| -| [Falcon](./docs/algorithms/sig/falcon.md) | [Selected by NIST](https://csrc.nist.gov/CSRC/media/Projects/post-quantum-cryptography/documents/round-3/submissions/Falcon-Round3.zip) | [PQClean/PQClean@1eacfda](https://github.com/PQClean/PQClean/commit/1eacfdafc15ddc5d5759d0b85b4cef26627df181) | -| [SLH-DSA](./docs/algorithms/sig/slh_dsa.md) | [Standardized by NIST](https://csrc.nist.gov/pubs/fips/205/final) | [pq-code-package/slhdsa-c@a0fc1ff](https://github.com/pq-code-package/slhdsa-c/commit/a0fc1ff253930060d0246aebca06c2538eb92b88) | -| [UOV](./docs/algorithms/sig/uov.md) | [Under NIST consideration](https://csrc.nist.gov/csrc/media/Projects/pqc-dig-sig/documents/round-2/spec-files/uov-spec-round2-web.pdf) | [pqov/pqov@7e0832b](https://github.com/pqov/pqov/commit/7e0832b6732a476119742c4acabd11b7c767aefb) | -| [MAYO](./docs/algorithms/sig/mayo.md) | [Under NIST consideration](https://csrc.nist.gov/csrc/media/Projects/pqc-dig-sig/documents/round-2/spec-files/mayo-spec-round2-web.pdf) | [PQCMayo/MAYO-C@4b7cd94](https://github.com/PQCMayo/MAYO-C/commit/4b7cd94c96b9522864efe40c6ad1fa269584a807) | -| [CROSS](./docs/algorithms/sig/cross.md) | [Under NIST consideration](https://www.cross-crypto.com/CROSS_Specification_v2.2.pdf) | [CROSS-signature/CROSS-lib-oqs@c8f7411](https://github.com/CROSS-signature/CROSS-lib-oqs/commit/c8f7411fed136f0e37600973fa3dbed53465e54f) | -| [SNOVA](./docs/algorithms/sig/snova.md) | [Under NIST consideration](https://csrc.nist.gov/csrc/media/Projects/pqc-dig-sig/documents/round-2/spec-files/snova-spec-round2-web.pdf) | [vacuas/SNOVA@1c3ca6f](https://github.com/vacuas/SNOVA/commit/1c3ca6f4f7286c0bde98d7d6f222cf63b9d52bff) | -| [ML-DSA](./docs/algorithms/sig/ml_dsa.md) | [Standardized by NIST](https://csrc.nist.gov/pubs/fips/204/final) | [pq-crystals/dilithium@444cdcc](https://github.com/pq-crystals/dilithium/commit/444cdcc84eb36b66fe27b3a2529ee48f6d8150c2) | -| [SPHINCS+](./docs/algorithms/sig/sphincs.md) | [Selected by NIST](https://csrc.nist.gov/CSRC/media/Projects/post-quantum-cryptography/documents/round-3/submissions/SPHINCS-Round3.zip) | [PQClean/PQClean@1eacfda](https://github.com/PQClean/PQClean/commit/1eacfdafc15ddc5d5759d0b85b4cef26627df181) | +| Algorithm family | Standardization status | Primary implementation | +|:---------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------| +| [Falcon](./docs/algorithms/sig/falcon.md) | [Selected by NIST](https://csrc.nist.gov/CSRC/media/Projects/post-quantum-cryptography/documents/round-3/submissions/Falcon-Round3.zip) | [`PQClean/PQClean@1eacfda`](https://github.com/PQClean/PQClean/commit/1eacfdafc15ddc5d5759d0b85b4cef26627df181) | +| [SLH-DSA](./docs/algorithms/sig/slh_dsa.md) | [Standardized by NIST](https://csrc.nist.gov/pubs/fips/205/final) | [`pq-code-package/slhdsa-c@a0fc1ff`](https://github.com/pq-code-package/slhdsa-c/commit/a0fc1ff253930060d0246aebca06c2538eb92b88) | +| [UOV](./docs/algorithms/sig/uov.md) | [Under NIST consideration](https://csrc.nist.gov/csrc/media/Projects/pqc-dig-sig/documents/round-2/spec-files/uov-spec-round2-web.pdf) | [`pqov/pqov@7e0832b`](https://github.com/pqov/pqov/commit/7e0832b6732a476119742c4acabd11b7c767aefb) | +| [MAYO](./docs/algorithms/sig/mayo.md) | [Under NIST consideration](https://csrc.nist.gov/csrc/media/Projects/pqc-dig-sig/documents/round-2/spec-files/mayo-spec-round2-web.pdf) | [`PQCMayo/MAYO-C@4b7cd94`](https://github.com/PQCMayo/MAYO-C/commit/4b7cd94c96b9522864efe40c6ad1fa269584a807) | +| [CROSS](./docs/algorithms/sig/cross.md) | [Under NIST consideration](https://www.cross-crypto.com/CROSS_Specification_v2.2.pdf) | [`CROSS-signature/CROSS-lib-oqs@c8f7411`](https://github.com/CROSS-signature/CROSS-lib-oqs/commit/c8f7411fed136f0e37600973fa3dbed53465e54f) | +| [SNOVA](./docs/algorithms/sig/snova.md) | [Under NIST consideration](https://csrc.nist.gov/csrc/media/Projects/pqc-dig-sig/documents/round-2/spec-files/snova-spec-round2-web.pdf) | [`vacuas/SNOVA@1c3ca6f`](https://github.com/vacuas/SNOVA/commit/1c3ca6f4f7286c0bde98d7d6f222cf63b9d52bff) | +| [ML-DSA](./docs/algorithms/sig/ml_dsa.md) | [Standardized by NIST](https://csrc.nist.gov/pubs/fips/204/final) | [`pq-crystals/dilithium@444cdcc`](https://github.com/pq-crystals/dilithium/commit/444cdcc84eb36b66fe27b3a2529ee48f6d8150c2) | +| [SPHINCS+](./docs/algorithms/sig/sphincs.md) | [Selected by NIST](https://csrc.nist.gov/CSRC/media/Projects/post-quantum-cryptography/documents/round-3/submissions/SPHINCS-Round3.zip) | [`PQClean/PQClean@1eacfda`](https://github.com/PQClean/PQClean/commit/1eacfdafc15ddc5d5759d0b85b4cef26627df181) | ### Stateful digital signatures -| Algorithm family | Standardization status | Primary implementation | -|:-------------------------------------------|:-----------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------| -| [XMSS](./docs/algorithms/sig_stfl/xmss.md) | [Standardized by Internet Research Task Force (IRTF), approved by NIST](https://www.rfc-editor.org/info/rfc8391) | [XMSS/xmss-reference](https://github.com/XMSS/xmss-reference) | -| [LMS](./docs/algorithms/sig_stfl/lms.md) | [Standardized by Internet Research Task Force (IRTF), approved by NIST](https://www.rfc-editor.org/info/rfc8554) | [cisco/hash-sigs](https://github.com/cisco/hash-sigs) | +| Algorithm family | Standardization status | Primary implementation | +|:-------------------------------------------|:-----------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------| +| [XMSS](./docs/algorithms/sig_stfl/xmss.md) | [Standardized by Internet Research Task Force (IRTF), approved by NIST](https://www.rfc-editor.org/info/rfc8391) | [`XMSS/xmss-reference`](https://github.com/XMSS/xmss-reference) | +| [LMS](./docs/algorithms/sig_stfl/lms.md) | [Standardized by Internet Research Task Force (IRTF), approved by NIST](https://www.rfc-editor.org/info/rfc8554) | [`cisco/hash-sigs`](https://github.com/cisco/hash-sigs) | Note that for algorithms marked with a dagger (†), liboqs contains at least one implementation that uses a large amount of stack space; this may cause failures when run in threads or in constrained environments. For more information, consult the algorithm information sheets in the [docs/algorithms](https://github.com/open-quantum-safe/liboqs/tree/main/docs/algorithms) folder. diff --git a/scripts/update_alg_support_table.py b/scripts/update_alg_support_table.py index 0cff2d53a..a87f63e6a 100755 --- a/scripts/update_alg_support_table.py +++ b/scripts/update_alg_support_table.py @@ -1,6 +1,13 @@ #!/usr/bin/env python3 # SPDX-License-Identifier: MIT +"""Helper functions for rendering the Algorithm Support table in README.md + +This is a separate module to facilitate code formatting and other dev tools, +but it is not meant to be run by itself. Instead, run the legacy +scripts/update_docs_from_yaml.py to invoke update_readme in this module. +""" + import os import tabulate @@ -24,7 +31,7 @@ def format_upstream_source(source: str) -> str: / otherwise with a link to the repository """ - # TODO: we might get GitLab or other non-GH link, but we will figure it out when it comes + # TODO: we might get GitLab or other non-GH link in the future but oh well prefix = "https://github.com/" if not prefix in source: raise ValueError(f"Non-GitHub source {source}") @@ -38,7 +45,7 @@ def format_upstream_source(source: str) -> str: if "commit/" in url: commit = tokens[3][:COMMIT_HASH_LEN] output += f"@{commit}" - return f"[{output}]({url})" + return f"[`{output}`]({url})" def render_alg_support_tbl(doc_dir: str) -> str: @@ -76,9 +83,7 @@ def render_alg_support_tbl(doc_dir: str) -> str: return tbl -def update_readme( - liboqs_dir: str, -): +def update_readme(liboqs_dir: str): """Per liboqs/issues/2045, update README.md with an algorithm support table The algorithm support table is a summary of individual algorithms currently