sharpetronics/liboqs
1
0
Fork 0
mirror of https://github.com/open-quantum-safe/liboqs.git synced 2025-10-04 00:02:01 -04:00
Code Issues Projects Releases Wiki Activity

first draft of alg support table

Browse Source 
Signed-off-by: Ganyu (Bruce) Xu <g66xu@uwaterloo.ca>
This commit is contained in:
Ganyu (Bruce) Xu 2025-09-24 17:35:36 -04:00
parent 44002abae2
commit c52e0f42c3
21 changed files with 164 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
README.md
View File

@ -55,13 +55,34 @@ All names other than `ML-KEM` and `ML-DSA` are subject to change. `liboqs` makes
<!-- OQS_TEMPLATE_FRAGMENT_ALG_SUPPORT_START -->
### KEMs
content
| Algorithm family | Standardization status | Primary implementation |
|:--------------------------------------------------------------|:-----------------------------|:----------------------------------------------------------------------------------------------------------------------------------------|
| [NTRU-Prime](./docs/algorithms/kem/ntruprime.md) | Not selected | [PQClean/PQClean@4c9e5a3](https://github.com/PQClean/PQClean/commit/4c9e5a3aa715cc8d1d0e377e4e6e682ebd7602d6) |
| [HQC](./docs/algorithms/kem/hqc.md) | Selected for standardization | [PQClean/PQClean@1eacfda](https://github.com/PQClean/PQClean/commit/1eacfdafc15ddc5d5759d0b85b4cef26627df181) |
| [FrodoKEM](./docs/algorithms/kem/frodokem.md) | Not selected | [microsoft/PQCrypto-LWEKE@b6609d3](https://github.com/microsoft/PQCrypto-LWEKE/commit/b6609d30a9982318d7f2937aa3c7b92147b917a2) |
| [BIKE](./docs/algorithms/kem/bike.md) | Not selected | [awslabs/bike-kem](https://github.com/awslabs/bike-kem) |
| [NTRU](./docs/algorithms/kem/ntru.md) | Not selected | [PQClean/PQClean@4c9e5a3](https://github.com/PQClean/PQClean/commit/4c9e5a3aa715cc8d1d0e377e4e6e682ebd7602d6) |
| [ML-KEM](./docs/algorithms/kem/ml_kem.md) | Standardized | [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 consideration | [PQClean/PQClean@1eacfda](https://github.com/PQClean/PQClean/commit/1eacfdafc15ddc5d5759d0b85b4cef26627df181) |
| [Kyber](./docs/algorithms/kem/kyber.md) | Selected for standardization | [pq-crystals/kyber@441c051](https://github.com/pq-crystals/kyber/commit/441c0519a07e8b86c8d079954a6b10bd31d29efc) |
### Digital signatures
content
| Algorithm family | Standardization status | Primary implementation |
|:---------------------------------------------|:-----------------------------|:------------------------------------------------------------------------------------------------------------------------------------------|
| [Falcon](./docs/algorithms/sig/falcon.md) | Selected for standardization | [PQClean/PQClean@1eacfda](https://github.com/PQClean/PQClean/commit/1eacfdafc15ddc5d5759d0b85b4cef26627df181) |
| [SLH-DSA](./docs/algorithms/sig/slh_dsa.md) | Standardized | [pq-code-package/slhdsa-c@a0fc1ff](https://github.com/pq-code-package/slhdsa-c/commit/a0fc1ff253930060d0246aebca06c2538eb92b88) |
| [UOV](./docs/algorithms/sig/uov.md) | Under consideration | [pqov/pqov@7e0832b](https://github.com/pqov/pqov/commit/7e0832b6732a476119742c4acabd11b7c767aefb) |
| [MAYO](./docs/algorithms/sig/mayo.md) | Under consideration | [PQCMayo/MAYO-C@4b7cd94](https://github.com/PQCMayo/MAYO-C/commit/4b7cd94c96b9522864efe40c6ad1fa269584a807) |
| [CROSS](./docs/algorithms/sig/cross.md) | Under consideration | [CROSS-signature/CROSS-lib-oqs@c8f7411](https://github.com/CROSS-signature/CROSS-lib-oqs/commit/c8f7411fed136f0e37600973fa3dbed53465e54f) |
| [SNOVA](./docs/algorithms/sig/snova.md) | Under consideration | [vacuas/SNOVA@1c3ca6f](https://github.com/vacuas/SNOVA/commit/1c3ca6f4f7286c0bde98d7d6f222cf63b9d52bff) |
| [ML-DSA](./docs/algorithms/sig/ml_dsa.md) | Standardized | [pq-crystals/dilithium@444cdcc](https://github.com/pq-crystals/dilithium/commit/444cdcc84eb36b66fe27b3a2529ee48f6d8150c2) |
| [SPHINCS+](./docs/algorithms/sig/sphincs.md) | Selected for standardization | [PQClean/PQClean@1eacfda](https://github.com/PQClean/PQClean/commit/1eacfdafc15ddc5d5759d0b85b4cef26627df181) |
### Stateful digital signatures
content
| Algorithm family | Standardization status | Primary implementation |
|:-------------------------------------------|:-------------------------|:--------------------------------------------------------------|
| [XMSS](./docs/algorithms/sig_stfl/xmss.md) | Standardized | [XMSS/xmss-reference](https://github.com/XMSS/xmss-reference) |
| [LMS](./docs/algorithms/sig_stfl/lms.md) | Standardized | [cisco/hash-sigs](https://github.com/cisco/hash-sigs) |
<!-- OQS_TEMPLATE_FRAGMENT_ALG_SUPPORT_END -->
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.

1
docs/algorithms/kem/bike.yml
View File

@ -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
spec-version: 5.1
primary-upstream:
source: https://github.com/awslabs/bike-kem

1
docs/algorithms/kem/classic_mceliece.yml
View File

@ -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 consideration
upstream-ancestors:
- SUPERCOP-20221025 "clean" and "avx2" implementations
advisories:

1
docs/algorithms/kem/frodokem.yml
View File

@ -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: Not selected
primary-upstream:
source: https://github.com/microsoft/PQCrypto-LWEKE/commit/b6609d30a9982318d7f2937aa3c7b92147b917a2
spdx-license-identifier: MIT

1
docs/algorithms/kem/hqc.yml
View File

@ -18,6 +18,7 @@ principal-submitters:
crypto-assumption: Syndrome decoding of structure codes (Hamming Quasi-Cyclic)
website: https://pqc-hqc.org/
nist-round: 4
standardization-status: Selected for standardization
spec-version: 2023-04-30
upstream-ancestors:
- https://github.com/SWilson4/package-pqclean/tree/8db1b24b/hqc

1
docs/algorithms/kem/kyber.yml
View File

@ -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/
nist-round: 3
standardization-status: Selected for standardization
spec-version: NIST Round 3 submission
primary-upstream:
source: https://github.com/pq-crystals/kyber/commit/441c0519a07e8b86c8d079954a6b10bd31d29efc

2
docs/algorithms/kem/ml_kem.yml
View File

@ -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/kyber/ and https://csrc.nist.gov/pubs/fips/203
nist-round: FIPS203
standardization-status: Standardized
spec-url: 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

1
docs/algorithms/kem/ntru.yml
View File

@ -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
nist-round: 3
spec-version: NIST Round 3 submission
upstream-ancestors:

1
docs/algorithms/kem/ntruprime.yml
View File

@ -15,6 +15,7 @@ crypto-assumption: NTRU
website: https://ntruprime.cr.yp.to
nist-round: 3
spec-version: supercop-20200826
standardization-status: Not selected
upstream-ancestors:
- https://github.com/jschanck/package-pqclean/tree/4d9f08c3/ntruprime
- supercop-20210604

1
docs/algorithms/sig/cross.yml
View File

@ -22,6 +22,7 @@ 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 consideration
spec-version: 2.2 + PQClean and OQS patches
primary-upstream:
source: https://github.com/CROSS-signature/CROSS-lib-oqs/commit/c8f7411fed136f0e37600973fa3dbed53465e54f

1
docs/algorithms/sig/falcon.yml
View File

@ -16,6 +16,7 @@ auxiliary-submitters:
crypto-assumption: hardness of NTRU lattice problems
website: https://falcon-sign.info
nist-round: 3
standardization-status: Selected for standardization
spec-version: 20211101
primary-upstream:
source: https://github.com/PQClean/PQClean/commit/1eacfdafc15ddc5d5759d0b85b4cef26627df181

1
docs/algorithms/sig/mayo.yml
View File

@ -9,6 +9,7 @@ principal-submitters:
crypto-assumption: multivariable quadratic equations, oil and vinegar
website: https://pqmayo.org
nist-round: 2
standardization-status: Under consideration
spec-version: NIST Round 2 (February 2025)
primary-upstream:
source: https://github.com/PQCMayo/MAYO-C/commit/4b7cd94c96b9522864efe40c6ad1fa269584a807

2
docs/algorithms/sig/ml_dsa.yml
View File

@ -13,6 +13,8 @@ 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
spec-url: https://csrc.nist.gov/pubs/fips/204/final
spec-version: ML-DSA
primary-upstream:
source: https://github.com/pq-crystals/dilithium/commit/444cdcc84eb36b66fe27b3a2529ee48f6d8150c2

4
docs/algorithms/sig/slh_dsa.yml
View File

@ -23,6 +23,8 @@ auxiliary-submitters:
crypto-assumption: hash-based signatures
website: https://csrc.nist.gov/pubs/fips/205/final
nist-round: FIPS205
standardization-status: Standardized
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:
@ -2373,4 +2375,4 @@ parameter-sets:
large-stack-usage: true

1
docs/algorithms/sig/snova.yml
View File

@ -13,6 +13,7 @@ principal-submitters:
crypto-assumption: multivariable quadratic equations, oil and vinegar
website: https://snova.pqclab.org/
nist-round: 2
standardization-status: Under consideration
spec-version: Round 2
primary-upstream:
source: https://github.com/vacuas/SNOVA/commit/1c3ca6f4f7286c0bde98d7d6f222cf63b9d52bff

1
docs/algorithms/sig/sphincs.yml
View File

@ -23,6 +23,7 @@ auxiliary-submitters:
crypto-assumption: hash-based signatures
website: https://sphincs.org/
nist-round: 3
standardization-status: Selected for standardization
spec-version: NIST Round 3 submission, v3.1 (June 10, 2022)
spdx-license-identifier: CC0-1.0
primary-upstream:

1
docs/algorithms/sig/uov.yml
View File

@ -14,6 +14,7 @@ principal-submitters:
- Bo-Yin Yang
crypto-assumption: multivariable quadratic equations, oil and vinegar
website: https://www.uovsig.org/
standardization-status: Under consideration
nist-round: 2
spec-version: NIST Round 2 (February 2025)
primary-upstream:

2
docs/algorithms/sig_stfl/lms.yml
View File

@ -9,6 +9,8 @@ auxiliary-submitters:
crypto-assumption: hash-based signatures
website: https://www.rfc-editor.org/info/rfc8554
nist-round:
standardization-status: Standardized
spec-url: https://www.rfc-editor.org/info/rfc8554
spec-version:
spdx-license-identifier:
primary-upstream:

2
docs/algorithms/sig_stfl/xmss.yml
View File

@ -9,6 +9,8 @@ auxiliary-submitters:
crypto-assumption: hash-based signatures
website: https://www.rfc-editor.org/info/rfc8391
standardization-status: Standardized
spec-url: https://www.rfc-editor.org/info/rfc8391
nist-round:
spec-version:
spdx-license-identifier: (Apache-2.0 OR MIT) AND CC0-1.0

113
scripts/update_alg_support_table.py Normal file
View File

@ -0,0 +1,113 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
from collections import namedtuple
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
"""
prefix = "https://github.com/"
if not prefix in source:
raise ValueError(f"Non-GitHub source {source}")
url_start = source.find(prefix)
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) -> str:
"""Render a markdown table summarizing the algorithms described by YAML data
sheets stored in the specified doc directory
"""
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
]
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"]
# TODO: unsure what to do with spec-url for now
primary_impl = format_upstream_source(algdata["primary-upstream"]["source"])
rows.append([
f"[{alg_name}]({md_url})",
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"""### KEMs
{kem_tbl}
### Digital signatures
{sig_tbl}
### Stateful digital signatures
{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:])

36
scripts/update_docs_from_yaml.py
View File

@ -8,6 +8,8 @@ import os
import tabulate
import yaml
from update_alg_support_table import update_readme
def load_yaml(filename, encoding='utf-8'):
with open(filename, mode='r', encoding=encoding) as fh:
return yaml.safe_load(fh.read())
@ -16,38 +18,6 @@ def file_get_contents(filename, encoding=None):
with open(filename, mode='r', encoding=encoding) as fh:
return fh.read()
def update_readme(
kem_yamls: list[dict],
sig_yamls: list[dict],
sig_stfl_yamls: list[dict],
liboqs_dir: str,
):
"""Per liboqs/issues/2045, update README.md with an algorithm support table
"""
# TODO: construct KEM table
# TODO: construct SIG table
# TODO: construct SIG_STFL table
md_str = f"""### KEMs
content
### Digital signatures
content
### Stateful digital signatures
content
"""
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:])
########################################
# Update the KEM markdown documentation.
########################################
@ -374,7 +344,7 @@ def do_it(liboqs_root):
# TODO:construct the algorithm support table, replace the appropriate
# section in README.md (OQS_TEMPLATE_FRAGMENT_ALG_SUPPORT_START)
update_readme(kem_yamls, sig_yamls, sig_stfl_yamls, liboqs_root)
update_readme(liboqs_root)
if __name__ == "__main__":