More readable algorithm support in README.md (#2286)

xuganyu96 · web-flow · commit 796aa120b1ed · 2025-10-02T10:14:24.000-04:00
* algorithm support table should replace the list of algorithms; minor refactor w.r.t. shebang, imports, and unnecessary global states

Signed-off-by: Ganyu (Bruce) Xu &lt;g66xu@uwaterloo.ca&gt;

* still need to fill in the content

Signed-off-by: Ganyu (Bruce) Xu &lt;g66xu@uwaterloo.ca&gt;

* first draft of alg support table

Signed-off-by: Ganyu (Bruce) Xu &lt;g66xu@uwaterloo.ca&gt;

* some refactoring

Signed-off-by: Ganyu (Bruce) Xu &lt;g66xu@uwaterloo.ca&gt;

* wrap standardization status with url to spec

Signed-off-by: Ganyu (Bruce) Xu &lt;g66xu@uwaterloo.ca&gt;

* Use split with no argument to split against any whitespace, not just space

Signed-off-by: Ganyu (Bruce) Xu &lt;g66xu@uwaterloo.ca&gt;

* documentation; make primary implementation monospaced

Signed-off-by: Ganyu (Bruce) Xu &lt;g66xu@uwaterloo.ca&gt;

* docs/algorithms/sig/sld_dsa.yml is generated from a Jinja template elsewhere

Signed-off-by: Ganyu (Bruce) Xu &lt;g66xu@uwaterloo.ca&gt;

* fixed invalid markdown anchors

Signed-off-by: Ganyu (Bruce) Xu &lt;g66xu@uwaterloo.ca&gt;

* algorithm family names will not link to docs/algorithms markdowns because Doxygen cannot handle them

Signed-off-by: Ganyu (Bruce) Xu &lt;g66xu@uwaterloo.ca&gt;

* add git diff to basic check for debugging purpose

Signed-off-by: Ganyu (Bruce) Xu &lt;g66xu@uwaterloo.ca&gt;

* resolved failure to consistently produce the same README.md

Signed-off-by: Ganyu (Bruce) Xu &lt;g66xu@uwaterloo.ca&gt;

* rephrasing standardization status for PQC third round candidates

Signed-off-by: Ganyu (Bruce) Xu &lt;g66xu@uwaterloo.ca&gt;

* improved explanation for NTRU's standardization status

Signed-off-by: Ganyu (Bruce) Xu &lt;g66xu@uwaterloo.ca&gt;

* another try at improving phrasing of standardization status

Signed-off-by: Ganyu (Bruce) Xu &lt;g66xu@uwaterloo.ca&gt;

* fixed typo

Signed-off-by: Ganyu (Bruce) Xu &lt;g66xu@uwaterloo.ca&gt;

* removed spec-url from lms.yml

Signed-off-by: Ganyu (Bruce) Xu &lt;g66xu@uwaterloo.ca&gt;

* revised specification URL to be consistent with spec-version

Signed-off-by: Ganyu (Bruce) Xu &lt;g66xu@uwaterloo.ca&gt;

* Revised FrodoKEM standardization status to reflect ISO consideration

Signed-off-by: Ganyu (Bruce) Xu &lt;g66xu@uwaterloo.ca&gt;

---------

Signed-off-by: Ganyu (Bruce) Xu &lt;g66xu@uwaterloo.ca&gt;
diff --git a/README.md b/README.md
diff --git a/docs/algorithms/kem/bike.yml b/docs/algorithms/kem/bike.yml
@@ -21,6 +21,7 @@ principal-submitters:
 crypto-assumption: QC-MDPC (Quasi-Cyclic Moderate Density Parity-Check)
 website: http://bikesuite.org/
 nist-round: 4
+standardization-status: Not selected by [NIST](https://bikesuite.org/files/v5.1/BIKE_Spec.2022.10.10.1.pdf)
 spec-version: 5.1
 primary-upstream:
   source: https://github.com/awslabs/bike-kem
diff --git a/docs/algorithms/kem/classic_mceliece.yml b/docs/algorithms/kem/classic_mceliece.yml
@@ -18,6 +18,7 @@ crypto-assumption: Niederreiter's dual version of McEliece's public key encrypti
 website: https://classic.mceliece.org
 nist-round: 3
 spec-version: SUPERCOP-20221025
+standardization-status: Under [ISO](https://classic.mceliece.org/iso.html) consideration
 upstream-ancestors:
 - SUPERCOP-20221025 "clean" and "avx2" implementations
 advisories:
diff --git a/docs/algorithms/kem/frodokem.yml b/docs/algorithms/kem/frodokem.yml
@@ -17,6 +17,7 @@ crypto-assumption: learning with errors (LWE)
 website: https://frodokem.org/
 nist-round: 3
 spec-version: NIST Round 3 submission
+standardization-status: Under [ISO](https://frodokem.org/) consideration
 primary-upstream:
   source: https://github.com/microsoft/PQCrypto-LWEKE/commit/b6609d30a9982318d7f2937aa3c7b92147b917a2
   spdx-license-identifier: MIT
diff --git a/docs/algorithms/kem/hqc.yml b/docs/algorithms/kem/hqc.yml
@@ -18,6 +18,8 @@ principal-submitters:
 crypto-assumption: Syndrome decoding of structure codes (Hamming Quasi-Cyclic)
 website: https://pqc-hqc.org/
 nist-round: 4
+standardization-status: Selected by [NIST](https://pqc-hqc.org/doc/hqc_specifications_2025_08_22.pdf)
+  for upcoming standardization
 spec-version: 2023-04-30
 upstream-ancestors:
 - https://github.com/SWilson4/package-pqclean/tree/8db1b24b/hqc
diff --git a/docs/algorithms/kem/kyber.yml b/docs/algorithms/kem/kyber.yml
@@ -15,6 +15,8 @@ auxiliary-submitters:
 crypto-assumption: Module LWE+R with base ring Z[x]/(3329, x^256+1)
 website: https://pq-crystals.org/
 nist-round: 3
+standardization-status: Selected by [NIST](https://csrc.nist.gov/CSRC/media/Projects/post-quantum-cryptography/documents/round-3/submissions/Kyber-Round3.zip)
+  as basis for ML-KEM (FIPS 203)
 spec-version: NIST Round 3 submission
 primary-upstream:
   source: https://github.com/pq-crystals/kyber/commit/441c0519a07e8b86c8d079954a6b10bd31d29efc
diff --git a/docs/algorithms/kem/ml_kem.yml b/docs/algorithms/kem/ml_kem.yml
@@ -15,6 +15,7 @@ auxiliary-submitters:
 crypto-assumption: Module LWE+R with base ring Z[x]/(3329, x^256+1)
 website: https://pq-crystals.org/kyber/ and https://csrc.nist.gov/pubs/fips/203
 nist-round: FIPS203
+standardization-status: Standardized by [NIST](https://csrc.nist.gov/pubs/fips/203/final)
 spec-version: ML-KEM
 primary-upstream:
   source: https://github.com/pq-code-package/mlkem-native/commit/048fc2a7a7b4ba0ad4c989c1ac82491aa94d5bfa
diff --git a/docs/algorithms/kem/ntru.yml b/docs/algorithms/kem/ntru.yml
@@ -16,6 +16,7 @@ auxiliary-submitters:
 - Zhenfei Zhang
 crypto-assumption: NTRU in Z[x]/(q, x^n-1) with prime n and power-of-two q
 website: https://ntru.org/
+standardization-status: Not selected by [NIST](https://csrc.nist.gov/CSRC/media/Projects/post-quantum-cryptography/documents/round-3/submissions/NTRU-Round3.zip), under standardization consideration by [NTT](https://info.isl.ntt.co.jp/crypt/ntru/index.html)
 nist-round: 3
 spec-version: NIST Round 3 submission
 upstream-ancestors:
diff --git a/docs/algorithms/kem/ntruprime.yml b/docs/algorithms/kem/ntruprime.yml
@@ -15,6 +15,7 @@ crypto-assumption: NTRU
 website: https://ntruprime.cr.yp.to
 nist-round: 3
 spec-version: supercop-20200826
+standardization-status: Not selected by [NIST](https://csrc.nist.gov/CSRC/media/Projects/post-quantum-cryptography/documents/round-3/submissions/NTRU-Prime-Round3.zip)
 upstream-ancestors:
 - https://github.com/jschanck/package-pqclean/tree/4d9f08c3/ntruprime
 - supercop-20210604
diff --git a/docs/algorithms/sig/cross.yml b/docs/algorithms/sig/cross.yml
@@ -22,6 +22,8 @@ crypto-assumption: hardness of the restricted syndrome decoding problem for rand
   linear codes on a finite field
 website: https://www.cross-crypto.com/
 nist-round: 2
+standardization-status: Under [NIST](https://www.cross-crypto.com/CROSS_Specification_v2.2.pdf)
+  consideration
 spec-version: 2.2 + PQClean and OQS patches
 primary-upstream:
   source: https://github.com/CROSS-signature/CROSS-lib-oqs/commit/c8f7411fed136f0e37600973fa3dbed53465e54f
diff --git a/docs/algorithms/sig/falcon.yml b/docs/algorithms/sig/falcon.yml
@@ -16,6 +16,8 @@ auxiliary-submitters:
 crypto-assumption: hardness of NTRU lattice problems
 website: https://falcon-sign.info
 nist-round: 3
+standardization-status: Selected by [NIST](https://csrc.nist.gov/CSRC/media/Projects/post-quantum-cryptography/documents/round-3/submissions/Falcon-Round3.zip)
+  for upcoming standardization
 spec-version: 20211101
 primary-upstream:
   source: https://github.com/PQClean/PQClean/commit/1eacfdafc15ddc5d5759d0b85b4cef26627df181
diff --git a/docs/algorithms/sig/mayo.yml b/docs/algorithms/sig/mayo.yml
@@ -9,6 +9,8 @@ principal-submitters:
 crypto-assumption: multivariable quadratic equations, oil and vinegar
 website: https://pqmayo.org
 nist-round: 2
+standardization-status: Under [NIST](https://csrc.nist.gov/csrc/media/Projects/pqc-dig-sig/documents/round-2/spec-files/mayo-spec-round2-web.pdf)
+  consideration
 spec-version: NIST Round 2 (February 2025)
 primary-upstream:
   source: https://github.com/PQCMayo/MAYO-C/commit/4b7cd94c96b9522864efe40c6ad1fa269584a807
diff --git a/docs/algorithms/sig/ml_dsa.yml b/docs/algorithms/sig/ml_dsa.yml
@@ -13,6 +13,7 @@ auxiliary-submitters:
 crypto-assumption: hardness of lattice problems over module lattices
 website: https://pq-crystals.org/dilithium/ and https://csrc.nist.gov/pubs/fips/204/final
 nist-round: FIPS204
+standardization-status: Standardized by [NIST](https://csrc.nist.gov/pubs/fips/204/final)
 spec-version: ML-DSA
 primary-upstream:
   source: https://github.com/pq-crystals/dilithium/commit/444cdcc84eb36b66fe27b3a2529ee48f6d8150c2
diff --git a/docs/algorithms/sig/slh_dsa.yml b/docs/algorithms/sig/slh_dsa.yml
@@ -1,3 +1,5 @@
+# Generated from src/sig/slh_dsa/templates/slh_dsa_docs_yml_template.jinja
+# by copy_from_slh_dsa_c.py
 name: SLH-DSA
 type: signature
 principal-submitters:
@@ -23,6 +25,8 @@ auxiliary-submitters:
 crypto-assumption: hash-based signatures
 website: https://csrc.nist.gov/pubs/fips/205/final
 nist-round: FIPS205
+standardization-status: Standardized by NIST
+spec-url: https://csrc.nist.gov/pubs/fips/205/final
 spec-version: SLH-DSA
 spdx-license-identifier: MIT or ISC or Apache 2.0
 primary-upstream:
diff --git a/docs/algorithms/sig/snova.yml b/docs/algorithms/sig/snova.yml
@@ -13,6 +13,8 @@ principal-submitters:
 crypto-assumption: multivariable quadratic equations, oil and vinegar
 website: https://snova.pqclab.org/
 nist-round: 2
+standardization-status: Under [NIST](https://csrc.nist.gov/csrc/media/Projects/pqc-dig-sig/documents/round-2/spec-files/snova-spec-round2-web.pdf)
+  consideration
 spec-version: Round 2
 primary-upstream:
   source: https://github.com/vacuas/SNOVA/commit/1c3ca6f4f7286c0bde98d7d6f222cf63b9d52bff
diff --git a/docs/algorithms/sig/sphincs.yml b/docs/algorithms/sig/sphincs.yml
@@ -23,6 +23,8 @@ auxiliary-submitters:
 crypto-assumption: hash-based signatures
 website: https://sphincs.org/
 nist-round: 3
+standardization-status: Selected by [NIST](https://sphincs.org/data/sphincs+-r3.1-specification.pdf)
+  as basis for SLH-DSA (FIPS 205)
 spec-version: NIST Round 3 submission, v3.1 (June 10, 2022)
 spdx-license-identifier: CC0-1.0
 primary-upstream:
diff --git a/docs/algorithms/sig/uov.yml b/docs/algorithms/sig/uov.yml
@@ -14,6 +14,8 @@ principal-submitters:
 - Bo-Yin Yang
 crypto-assumption: multivariable quadratic equations, oil and vinegar
 website: https://www.uovsig.org/
+standardization-status: Under [NIST](https://csrc.nist.gov/csrc/media/Projects/pqc-dig-sig/documents/round-2/spec-files/uov-spec-round2-web.pdf)
+  consideration
 nist-round: 2
 spec-version: NIST Round 2 (February 2025)
 primary-upstream:
diff --git a/docs/algorithms/sig_stfl/lms.yml b/docs/algorithms/sig_stfl/lms.yml
@@ -9,6 +9,7 @@ auxiliary-submitters:
 crypto-assumption: hash-based signatures
 website: https://www.rfc-editor.org/info/rfc8554
 nist-round: 
+standardization-status: Standardized by [IRTF](https://www.rfc-editor.org/info/rfc8554), approved by [NIST](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-208.pdf)
 spec-version: 
 spdx-license-identifier: 
 primary-upstream:
diff --git a/docs/algorithms/sig_stfl/xmss.yml b/docs/algorithms/sig_stfl/xmss.yml
@@ -9,6 +9,7 @@ auxiliary-submitters:
 
 crypto-assumption: hash-based signatures
 website: https://www.rfc-editor.org/info/rfc8391
+standardization-status: Standardized by [IRTF](https://www.rfc-editor.org/info/rfc8391), approved by [NIST](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-208.pdf)
 nist-round:
 spec-version:
 spdx-license-identifier: (Apache-2.0 OR MIT) AND CC0-1.0
diff --git a/scripts/update_alg_support_table.py b/scripts/update_alg_support_table.py
@@ -0,0 +1,130 @@
+#!/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
+import yaml
+
+YAML_EXTS = [".yaml", ".yml"]
+ALG_SUPPORT_HEADER = [
+    "Algorithm family",
+    "Standardization status",
+    "Primary implementation",
+]
+COMMIT_HASH_LEN = 7
+
+
+def format_upstream_source(source: str) -> str:
+    """For each YAML data sheet, the primary-upstream.source field contains some
+    URL to the implementation. At this moment all URLs are links to GitHub, so
+    we can format them as follows:
+
+    <handle>/<repository>@<commit> if commit is available
+    <handle>/<repository> otherwise
+    with a link to the repository
+    """
+    # 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}")
+    url_start = source.find(prefix)
+    # NOTE: split with no argument will split with all whitespaces
+    url = source[url_start:].split()[0]
+    # example: ["PQClean", "PQClean", "commit", "1eacfdaf..."]
+    tokens = url[len(prefix) :].split("/")
+    handle, repo = tokens[0], tokens[1]
+    output = f"{handle}/{repo}"
+    if "commit/" in url:
+        commit = tokens[3][:COMMIT_HASH_LEN]
+        output += f"@{commit}"
+    return f"[`{output}`]({url})"
+
+
+def render_alg_support_tbl(doc_dir: str, anchor_alg_name: bool = False) -> str:
+    """Render a markdown table summarizing the algorithms described by YAML data
+    sheets stored in the specified doc directory
+
+    :param anchor_alg_name: if set to True, then "algorithm family" will link to
+    the corresponding markdown document under docs/algorithms/<kem|sig|sig_stfl>
+    otherwise "algorithm family" will be plain text with no link.
+    """
+    # TODO: anchor_alg_name is turned off because Doxygen cannot handle links
+    # to markdown files under docs/algorithms/xxx
+    yaml_paths = [
+        os.path.abspath(os.path.join(doc_dir, filepath))
+        for filepath in os.listdir(doc_dir)
+        if os.path.splitext(filepath)[1].lower() in YAML_EXTS
+    ]
+    yaml_paths.sort()
+    rows = [ALG_SUPPORT_HEADER]
+    for yaml_path in yaml_paths:
+        with open(yaml_path) as f:
+            algdata = yaml.safe_load(f)
+        alg_name = algdata["name"]
+        dirname = "kem"
+        if "sig/" in yaml_path:
+            dirname = "sig"
+        elif "sig_stfl/" in yaml_path:
+            dirname = "sig_stfl"
+        md_basename = os.path.splitext(os.path.split(yaml_path)[1])[0]
+        md_url = f"docs/algorithms/{dirname}/{md_basename}.md"
+        std_status = algdata["standardization-status"]
+        spec_url = algdata.get("spec-url", None)
+        primary_impl = format_upstream_source(algdata["primary-upstream"]["source"])
+        rows.append(
+            [
+                f"[{alg_name}]({md_url})" if anchor_alg_name else f"{alg_name}",
+                f"[{std_status}]({spec_url})" if spec_url else std_status,
+                primary_impl,
+            ]
+        )
+    tbl = tabulate.tabulate(rows, tablefmt="pipe", headers="firstrow")
+    return tbl
+
+
+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
+    integrated into liboqs. The primary source of information are the various
+    YAML files under docs/algorithms/<kem|sig|sig_stfl> directory. The table
+    summarizes the following attributes:
+    - Algorithm family (e.g. Kyber, ML-KEM)
+    - Standardization status, with link to specification
+    - Primary source of implementation
+    - (WIP) Maintenance status
+    """
+    kem_doc_dir = os.path.join(liboqs_dir, "docs", "algorithms", "kem")
+    kem_tbl = render_alg_support_tbl(kem_doc_dir)
+    sig_doc_dir = os.path.join(liboqs_dir, "docs", "algorithms", "sig")
+    sig_tbl = render_alg_support_tbl(sig_doc_dir)
+    sig_stfl_doc_dir = os.path.join(liboqs_dir, "docs", "algorithms", "sig_stfl")
+    sig_stfl_tbl = render_alg_support_tbl(sig_stfl_doc_dir)
+    md_str = f"""#### Key encapsulation mechanisms
+{kem_tbl}
+
+#### Signature schemes
+{sig_tbl}
+
+#### Stateful signature schemes
+{sig_stfl_tbl}
+"""
+    readme_path = os.path.join(liboqs_dir, "README.md")
+    fragment_start = "<!-- OQS_TEMPLATE_FRAGMENT_ALG_SUPPORT_START -->\n"
+    fragment_end = "<!-- OQS_TEMPLATE_FRAGMENT_ALG_SUPPORT_END -->"
+    with open(readme_path, "r") as f:
+        readme = f.read()
+        fragment_start_loc = readme.find(fragment_start) + len(fragment_start)
+        fragment_end_loc = readme.find(fragment_end)
+    with open(readme_path, "w") as f:
+        f.write(readme[:fragment_start_loc])
+        f.write(md_str)
+        f.write(readme[fragment_end_loc:])
diff --git a/scripts/update_docs_from_yaml.py b/scripts/update_docs_from_yaml.py
diff --git a/src/sig/slh_dsa/templates/slh_dsa_docs_yml_template.jinja b/src/sig/slh_dsa/templates/slh_dsa_docs_yml_template.jinja
