From 4de651c723448d754953fa25d81fb16d0584bbfa Mon Sep 17 00:00:00 2001 From: Goutam Tamvada Date: Fri, 30 Jul 2021 13:26:44 -0400 Subject: [PATCH] Refactoring documentation generation. (#1057) --- README.md | 18 +- docs/algorithms/kem/bike.md | 14 +- docs/algorithms/kem/classic_mceliece.md | 50 +++--- docs/algorithms/kem/classic_mceliece.yml | 41 +++-- docs/algorithms/kem/frodokem.md | 14 +- docs/algorithms/kem/frodokem.yml | 1 - docs/algorithms/kem/hqc.md | 16 +- docs/algorithms/kem/hqc.yml | 2 +- docs/algorithms/kem/kyber.md | 14 +- docs/algorithms/kem/ntru.md | 14 +- docs/algorithms/kem/ntruprime.md | 14 +- docs/algorithms/kem/saber.md | 14 +- docs/algorithms/kem/sike.md | 18 +- docs/algorithms/sig/dilithium.md | 14 +- docs/algorithms/sig/falcon.md | 14 +- docs/algorithms/sig/picnic.md | 16 +- docs/algorithms/sig/rainbow.md | 24 ++- docs/algorithms/sig/rainbow.yml | 12 +- docs/algorithms/sig/sphincs.md | 14 +- .../copy_from_upstream/copy_from_upstream.py | 13 +- .../docs/algorithms/kem/classic_mceliece.md | 26 --- .../docs/algorithms/kem/hqc.md | 26 --- .../docs/algorithms/kem/kyber.md | 26 --- .../docs/algorithms/kem/ntru.md | 26 --- .../docs/algorithms/kem/ntruprime.md | 26 --- .../docs/algorithms/kem/saber.md | 26 --- .../docs/algorithms/sig/dilithium.md | 26 --- .../docs/algorithms/sig/falcon.md | 26 --- .../docs/algorithms/sig/rainbow.md | 30 ---- .../docs/algorithms/sig/sphincs.md | 26 --- scripts/copy_from_upstream/requirements.txt | 2 - ..._from_yaml.py => update_docs_from_yaml.py} | 170 ++++++++++++++---- 32 files changed, 346 insertions(+), 427 deletions(-) delete mode 100644 scripts/copy_from_upstream/docs/algorithms/kem/classic_mceliece.md delete mode 100644 scripts/copy_from_upstream/docs/algorithms/kem/hqc.md delete mode 100644 scripts/copy_from_upstream/docs/algorithms/kem/kyber.md delete mode 100644 scripts/copy_from_upstream/docs/algorithms/kem/ntru.md delete mode 100644 scripts/copy_from_upstream/docs/algorithms/kem/ntruprime.md delete mode 100644 scripts/copy_from_upstream/docs/algorithms/kem/saber.md delete mode 100644 scripts/copy_from_upstream/docs/algorithms/sig/dilithium.md delete mode 100644 scripts/copy_from_upstream/docs/algorithms/sig/falcon.md delete mode 100644 scripts/copy_from_upstream/docs/algorithms/sig/rainbow.md delete mode 100644 scripts/copy_from_upstream/docs/algorithms/sig/sphincs.md rename scripts/{gen_docs_md_from_yaml.py => update_docs_from_yaml.py} (56%) diff --git a/README.md b/README.md index 9578bebf5..f815edbf8 100644 --- a/README.md +++ b/README.md @@ -34,31 +34,35 @@ More information on OQS can be found [here](https://openquantumsafe.org/) and in ### Supported Algorithms -Details on each supported algorithm can be found in the [docs/algorithms folder](https://github.com/open-quantum-safe/liboqs/tree/main/docs/algorithms). +Details on each supported algorithm can be found in the [docs/algorithms](https://github.com/open-quantum-safe/liboqs/tree/main/docs/algorithms) folder. #### Key encapsulation mechanisms + - **BIKE**: BIKE-L1, BIKE-L3 - **Classic McEliece**: Classic-McEliece-348864†, Classic-McEliece-348864f†, Classic-McEliece-460896†, Classic-McEliece-460896f†, Classic-McEliece-6688128†, Classic-McEliece-6688128f†, Classic-McEliece-6960119†, Classic-McEliece-6960119f†, Classic-McEliece-8192128†, Classic-McEliece-8192128f† - **FrodoKEM**: FrodoKEM-640-AES, FrodoKEM-640-SHAKE, FrodoKEM-976-AES, FrodoKEM-976-SHAKE, FrodoKEM-1344-AES, FrodoKEM-1344-SHAKE -- **HQC**: HQC-128-1-CCA2, HQC-192-1-CCA2, HQC-192-2-CCA2, HQC-256-1-CCA2†, HQC-256-2-CCA2†, HQC-256-3-CCA2† -- **Kyber**: Kyber512, Kyber768, Kyber1024, Kyber512-90s, Kyber768-90s, Kyber1024-90s +- **HQC**: HQC-128, HQC-192, HQC-256† +- **Kyber**: Kyber512, Kyber512-90s, Kyber768, Kyber768-90s, Kyber1024, Kyber1024-90s - **NTRU**: NTRU-HPS-2048-509, NTRU-HPS-2048-677, NTRU-HPS-4096-821, NTRU-HRSS-701 - **NTRU-Prime**: ntrulpr653, ntrulpr761, ntrulpr857, sntrup653, sntrup761, sntrup857 - **SABER**: LightSaber-KEM, Saber-KEM, FireSaber-KEM -- **SIKE**: SIDH-p434, SIDH-p503, SIDH-p610, SIDH-p751, SIKE-p434, SIKE-p503, SIKE-p610, SIKE-p751, SIDH-p434-compressed, SIDH-p503-compressed, SIDH-p610-compressed, SIDH-p751-compressed, SIKE-p434-compressed, SIKE-p503-compressed, SIKE-p610-compressed, SIKE-p751-compressed +- **SIKE**: SIDH-p434, SIDH-p434-compressed, SIDH-p503, SIDH-p503-compressed, SIDH-p610, SIDH-p610-compressed, SIDH-p751, SIDH-p751-compressed, SIKE-p434, SIKE-p434-compressed, SIKE-p503, SIKE-p503-compressed, SIKE-p610, SIKE-p610-compressed, SIKE-p751, SIKE-p751-compressed + #### Signature schemes -- **Dilithium**: Dilithium2, Dilithium2-AES, Dilithium3, Dilithium3-AES, Dilithium5, Dilithium5-AES + +- **CRYSTALS-Dilithium**: Dilithium2, Dilithium3, Dilithium5, Dilithium2-AES, Dilithium3-AES, Dilithium5-AES - **Falcon**: Falcon-512, Falcon-1024 -- **Picnic**: Picnic-L1-FS, Picnic-L1-UR, Picnic-L1-full, Picnic-L3-FS, Picnic-L3-UR, Picnic-L3-full, Picnic-L5-FS, Picnic-L5-UR, Picnic-L5-full, Picnic3-L1, Picnic3-L3, Picnic3-L5 +- **Picnic**: picnic\_L1\_FS, picnic\_L1\_UR, picnic\_L1\_full, picnic\_L3\_FS, picnic\_L3\_UR, picnic\_L3\_full, picnic\_L5\_FS, picnic\_L5\_UR, picnic\_L5\_full, picnic3\_L1, picnic3\_L3, picnic3\_L5 - **Rainbow**: Rainbow-I-Classic, Rainbow-I-Circumzenithal, Rainbow-I-Compressed, Rainbow-III-Classic†, Rainbow-III-Circumzenithal†, Rainbow-III-Compressed†, Rainbow-V-Classic†, Rainbow-V-Circumzenithal†, Rainbow-V-Compressed† - **SPHINCS+-Haraka**: SPHINCS+-Haraka-128f-robust, SPHINCS+-Haraka-128f-simple, SPHINCS+-Haraka-128s-robust, SPHINCS+-Haraka-128s-simple, SPHINCS+-Haraka-192f-robust, SPHINCS+-Haraka-192f-simple, SPHINCS+-Haraka-192s-robust, SPHINCS+-Haraka-192s-simple, SPHINCS+-Haraka-256f-robust, SPHINCS+-Haraka-256f-simple, SPHINCS+-Haraka-256s-robust, SPHINCS+-Haraka-256s-simple - **SPHINCS+-SHA256**: SPHINCS+-SHA256-128f-robust, SPHINCS+-SHA256-128f-simple, SPHINCS+-SHA256-128s-robust, SPHINCS+-SHA256-128s-simple, SPHINCS+-SHA256-192f-robust, SPHINCS+-SHA256-192f-simple, SPHINCS+-SHA256-192s-robust, SPHINCS+-SHA256-192s-simple, SPHINCS+-SHA256-256f-robust, SPHINCS+-SHA256-256f-simple, SPHINCS+-SHA256-256s-robust, SPHINCS+-SHA256-256s-simple - **SPHINCS+-SHAKE256**: SPHINCS+-SHAKE256-128f-robust, SPHINCS+-SHAKE256-128f-simple, SPHINCS+-SHAKE256-128s-robust, SPHINCS+-SHAKE256-128s-simple, SPHINCS+-SHAKE256-192f-robust, SPHINCS+-SHAKE256-192f-simple, SPHINCS+-SHAKE256-192s-robust, SPHINCS+-SHAKE256-192s-simple, SPHINCS+-SHAKE256-256f-robust, SPHINCS+-SHAKE256-256f-simple, SPHINCS+-SHAKE256-256s-robust, SPHINCS+-SHAKE256-256s-simple + -Note that algorithms marked with a dagger (†) have large stack usage and may cause failures when run on threads or in constrained environments. +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. ### Limitations and Security diff --git a/docs/algorithms/kem/bike.md b/docs/algorithms/kem/bike.md index bc7323bd8..832225e22 100644 --- a/docs/algorithms/kem/bike.md +++ b/docs/algorithms/kem/bike.md @@ -18,13 +18,15 @@ ## BIKE-L1 implementation characteristics -| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | -|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| master | All | All | None | True | True | False | -| master | x86\_64 | Linux,Darwin | AVX2,AVX512,PCLMUL,SSE2 | True | True | False | +| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage?‡ | +|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:----------------------| +| master | All | All | None | True | True | False | +| master | x86\_64 | Linux,Darwin | AVX2,AVX512,PCLMUL,SSE2 | True | True | False | Are implementations chosen based on runtime CPU feature detection? **Yes**. + ‡For an explanation of what this denotes, consult the [Explanation of Terms](#explanation-of-terms) section at the end of this file. + ## BIKE-L3 implementation characteristics | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | @@ -33,3 +35,7 @@ Are implementations chosen based on runtime CPU feature detection? **Yes**. | master | x86\_64 | Linux,Darwin | AVX2,AVX512,PCLMUL,SSE2 | True | True | False | Are implementations chosen based on runtime CPU feature detection? **Yes**. + +## Explanation of Terms + +- **Large Stack Usage**: Implementations identified as having such may cause failures when running in threads or in constrained environments. \ No newline at end of file diff --git a/docs/algorithms/kem/classic_mceliece.md b/docs/algorithms/kem/classic_mceliece.md index b3ad01823..eda912836 100644 --- a/docs/algorithms/kem/classic_mceliece.md +++ b/docs/algorithms/kem/classic_mceliece.md @@ -26,19 +26,21 @@ ## Classic-McEliece-348864 implementation characteristics -| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | -|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| vec | All | All | None | True | True | False | -| avx | x86\_64 | Linux,Darwin | AVX2,POPCNT | False | True | False | +| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage?‡ | +|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:----------------------| +| vec | All | All | None | True | True | True | +| avx | x86\_64 | Linux,Darwin | AVX2,POPCNT | False | True | True | Are implementations chosen based on runtime CPU feature detection? **Yes**. + ‡For an explanation of what this denotes, consult the [Explanation of Terms](#explanation-of-terms) section at the end of this file. + ## Classic-McEliece-348864f implementation characteristics | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | |:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| vec | All | All | None | True | True | False | -| avx | x86\_64 | Linux,Darwin | AVX2,POPCNT,BMI1 | False | True | False | +| vec | All | All | None | True | True | True | +| avx | x86\_64 | Linux,Darwin | AVX2,POPCNT,BMI1 | False | True | True | Are implementations chosen based on runtime CPU feature detection? **Yes**. @@ -46,8 +48,8 @@ Are implementations chosen based on runtime CPU feature detection? **Yes**. | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | |:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| vec | All | All | None | True | True | False | -| avx | x86\_64 | Linux,Darwin | AVX2,POPCNT | False | True | False | +| vec | All | All | None | True | True | True | +| avx | x86\_64 | Linux,Darwin | AVX2,POPCNT | False | True | True | Are implementations chosen based on runtime CPU feature detection? **Yes**. @@ -55,8 +57,8 @@ Are implementations chosen based on runtime CPU feature detection? **Yes**. | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | |:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| vec | All | All | None | True | True | False | -| avx | x86\_64 | Linux,Darwin | AVX2,BMI1,POPCNT | False | True | False | +| vec | All | All | None | True | True | True | +| avx | x86\_64 | Linux,Darwin | AVX2,BMI1,POPCNT | False | True | True | Are implementations chosen based on runtime CPU feature detection? **Yes**. @@ -64,8 +66,8 @@ Are implementations chosen based on runtime CPU feature detection? **Yes**. | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | |:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| vec | All | All | None | True | True | False | -| avx | x86\_64 | Linux,Darwin | AVX2,POPCNT | False | True | False | +| vec | All | All | None | True | True | True | +| avx | x86\_64 | Linux,Darwin | AVX2,POPCNT | False | True | True | Are implementations chosen based on runtime CPU feature detection? **Yes**. @@ -73,8 +75,8 @@ Are implementations chosen based on runtime CPU feature detection? **Yes**. | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | |:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| vec | All | All | None | True | True | False | -| avx | x86\_64 | Linux,Darwin | AVX2,BMI1,POPCNT | False | True | False | +| vec | All | All | None | True | True | True | +| avx | x86\_64 | Linux,Darwin | AVX2,BMI1,POPCNT | False | True | True | Are implementations chosen based on runtime CPU feature detection? **Yes**. @@ -82,8 +84,8 @@ Are implementations chosen based on runtime CPU feature detection? **Yes**. | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | |:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| vec | All | All | None | True | True | False | -| avx | x86\_64 | Linux,Darwin | AVX2,POPCNT | False | True | False | +| vec | All | All | None | True | True | True | +| avx | x86\_64 | Linux,Darwin | AVX2,POPCNT | False | True | True | Are implementations chosen based on runtime CPU feature detection? **Yes**. @@ -91,8 +93,8 @@ Are implementations chosen based on runtime CPU feature detection? **Yes**. | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | |:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| vec | All | All | None | True | True | False | -| avx | x86\_64 | Linux,Darwin | AVX2,BMI1,POPCNT | False | True | False | +| vec | All | All | None | True | True | True | +| avx | x86\_64 | Linux,Darwin | AVX2,BMI1,POPCNT | False | True | True | Are implementations chosen based on runtime CPU feature detection? **Yes**. @@ -100,8 +102,8 @@ Are implementations chosen based on runtime CPU feature detection? **Yes**. | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | |:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| vec | All | All | None | True | True | False | -| avx | x86\_64 | Linux,Darwin | AVX2,POPCNT | False | True | False | +| vec | All | All | None | True | True | True | +| avx | x86\_64 | Linux,Darwin | AVX2,POPCNT | False | True | True | Are implementations chosen based on runtime CPU feature detection? **Yes**. @@ -109,7 +111,11 @@ Are implementations chosen based on runtime CPU feature detection? **Yes**. | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | |:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| vec | All | All | None | True | True | False | -| avx | x86\_64 | Linux,Darwin | AVX2,POPCNT,BMI1 | False | True | False | +| vec | All | All | None | True | True | True | +| avx | x86\_64 | Linux,Darwin | AVX2,POPCNT,BMI1 | False | True | True | Are implementations chosen based on runtime CPU feature detection? **Yes**. + +## Explanation of Terms + +- **Large Stack Usage**: Implementations identified as having such may cause failures when running in threads or in constrained environments. \ No newline at end of file diff --git a/docs/algorithms/kem/classic_mceliece.yml b/docs/algorithms/kem/classic_mceliece.yml index c3cebd4bb..e03e353d9 100644 --- a/docs/algorithms/kem/classic_mceliece.yml +++ b/docs/algorithms/kem/classic_mceliece.yml @@ -39,7 +39,7 @@ parameter-sets: - SHA3: liboqs no-secret-dependent-branching-claimed: true no-secret-dependent-branching-checked-by-valgrind: true - large-stack-usage: false + large-stack-usage: true - upstream-id: avx supported-platforms: - architecture: x86_64 @@ -54,7 +54,7 @@ parameter-sets: - SHA3: liboqs no-secret-dependent-branching-claimed: false no-secret-dependent-branching-checked-by-valgrind: true - large-stack-usage: false + large-stack-usage: true - name: Classic-McEliece-348864f claimed-nist-level: 1 claimed-security: IND-CCA2 @@ -71,7 +71,7 @@ parameter-sets: - SHA3: liboqs no-secret-dependent-branching-claimed: true no-secret-dependent-branching-checked-by-valgrind: true - large-stack-usage: false + large-stack-usage: true - upstream-id: avx supported-platforms: - architecture: x86_64 @@ -87,7 +87,7 @@ parameter-sets: - SHA3: liboqs no-secret-dependent-branching-claimed: false no-secret-dependent-branching-checked-by-valgrind: true - large-stack-usage: false + large-stack-usage: true - name: Classic-McEliece-460896 claimed-nist-level: 3 claimed-security: IND-CCA2 @@ -104,7 +104,7 @@ parameter-sets: - SHA3: liboqs no-secret-dependent-branching-claimed: true no-secret-dependent-branching-checked-by-valgrind: true - large-stack-usage: false + large-stack-usage: true - upstream-id: avx supported-platforms: - architecture: x86_64 @@ -119,7 +119,7 @@ parameter-sets: - SHA3: liboqs no-secret-dependent-branching-claimed: false no-secret-dependent-branching-checked-by-valgrind: true - large-stack-usage: false + large-stack-usage: true - name: Classic-McEliece-460896f claimed-nist-level: 3 claimed-security: IND-CCA2 @@ -136,7 +136,7 @@ parameter-sets: - SHA3: liboqs no-secret-dependent-branching-claimed: true no-secret-dependent-branching-checked-by-valgrind: true - large-stack-usage: false + large-stack-usage: true - upstream-id: avx supported-platforms: - architecture: x86_64 @@ -152,7 +152,7 @@ parameter-sets: - SHA3: liboqs no-secret-dependent-branching-claimed: false no-secret-dependent-branching-checked-by-valgrind: true - large-stack-usage: false + large-stack-usage: true - name: Classic-McEliece-6688128 claimed-nist-level: 5 claimed-security: IND-CCA2 @@ -169,7 +169,7 @@ parameter-sets: - SHA3: liboqs no-secret-dependent-branching-claimed: true no-secret-dependent-branching-checked-by-valgrind: true - large-stack-usage: false + large-stack-usage: true - upstream-id: avx supported-platforms: - architecture: x86_64 @@ -184,7 +184,7 @@ parameter-sets: - SHA3: liboqs no-secret-dependent-branching-claimed: false no-secret-dependent-branching-checked-by-valgrind: true - large-stack-usage: false + large-stack-usage: true - name: Classic-McEliece-6688128f claimed-nist-level: 5 claimed-security: IND-CCA2 @@ -201,7 +201,7 @@ parameter-sets: - SHA3: liboqs no-secret-dependent-branching-claimed: true no-secret-dependent-branching-checked-by-valgrind: true - large-stack-usage: false + large-stack-usage: true - upstream-id: avx supported-platforms: - architecture: x86_64 @@ -217,7 +217,7 @@ parameter-sets: - SHA3: liboqs no-secret-dependent-branching-claimed: false no-secret-dependent-branching-checked-by-valgrind: true - large-stack-usage: false + large-stack-usage: true - name: Classic-McEliece-6960119 claimed-nist-level: 5 claimed-security: IND-CCA2 @@ -234,7 +234,7 @@ parameter-sets: - SHA3: liboqs no-secret-dependent-branching-claimed: true no-secret-dependent-branching-checked-by-valgrind: true - large-stack-usage: false + large-stack-usage: true - upstream-id: avx supported-platforms: - architecture: x86_64 @@ -249,7 +249,7 @@ parameter-sets: - SHA3: liboqs no-secret-dependent-branching-claimed: false no-secret-dependent-branching-checked-by-valgrind: true - large-stack-usage: false + large-stack-usage: true - name: Classic-McEliece-6960119f claimed-nist-level: 5 claimed-security: IND-CCA2 @@ -266,7 +266,7 @@ parameter-sets: - SHA3: liboqs no-secret-dependent-branching-claimed: true no-secret-dependent-branching-checked-by-valgrind: true - large-stack-usage: false + large-stack-usage: true - upstream-id: avx supported-platforms: - architecture: x86_64 @@ -282,7 +282,7 @@ parameter-sets: - SHA3: liboqs no-secret-dependent-branching-claimed: false no-secret-dependent-branching-checked-by-valgrind: true - large-stack-usage: false + large-stack-usage: true - name: Classic-McEliece-8192128 claimed-nist-level: 5 claimed-security: IND-CCA2 @@ -299,7 +299,7 @@ parameter-sets: - SHA3: liboqs no-secret-dependent-branching-claimed: true no-secret-dependent-branching-checked-by-valgrind: true - large-stack-usage: false + large-stack-usage: true - upstream-id: avx supported-platforms: - architecture: x86_64 @@ -314,7 +314,7 @@ parameter-sets: - SHA3: liboqs no-secret-dependent-branching-claimed: false no-secret-dependent-branching-checked-by-valgrind: true - large-stack-usage: false + large-stack-usage: true - name: Classic-McEliece-8192128f claimed-nist-level: 5 claimed-security: IND-CCA2 @@ -331,7 +331,7 @@ parameter-sets: - SHA3: liboqs no-secret-dependent-branching-claimed: true no-secret-dependent-branching-checked-by-valgrind: true - large-stack-usage: false + large-stack-usage: true - upstream-id: avx supported-platforms: - architecture: x86_64 @@ -347,5 +347,4 @@ parameter-sets: - SHA3: liboqs no-secret-dependent-branching-claimed: false no-secret-dependent-branching-checked-by-valgrind: true - large-stack-usage: false -auxiliary-submitters: [] + large-stack-usage: true diff --git a/docs/algorithms/kem/frodokem.md b/docs/algorithms/kem/frodokem.md index 129b222c3..ca0ea3504 100644 --- a/docs/algorithms/kem/frodokem.md +++ b/docs/algorithms/kem/frodokem.md @@ -21,13 +21,15 @@ ## FrodoKEM-640-AES implementation characteristics -| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | -|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| master | All | All | None | True | True | False | -| master | x86\_64 | Linux,Darwin,Windows | AVX2 | True | True | False | +| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage?‡ | +|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:----------------------| +| master | All | All | None | True | True | False | +| master | x86\_64 | Linux,Darwin,Windows | AVX2 | True | True | False | Are implementations chosen based on runtime CPU feature detection? **Yes**. + ‡For an explanation of what this denotes, consult the [Explanation of Terms](#explanation-of-terms) section at the end of this file. + ## FrodoKEM-640-SHAKE implementation characteristics | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | @@ -72,3 +74,7 @@ Are implementations chosen based on runtime CPU feature detection? **Yes**. | master | x86\_64 | Linux,Darwin,Windows | AVX2 | True | True | False | Are implementations chosen based on runtime CPU feature detection? **Yes**. + +## Explanation of Terms + +- **Large Stack Usage**: Implementations identified as having such may cause failures when running in threads or in constrained environments. \ No newline at end of file diff --git a/docs/algorithms/kem/frodokem.yml b/docs/algorithms/kem/frodokem.yml index 2251c1eeb..21c558f20 100644 --- a/docs/algorithms/kem/frodokem.yml +++ b/docs/algorithms/kem/frodokem.yml @@ -13,7 +13,6 @@ principal-submitters: - Christopher Peikert - Ananth Raghunathan - Douglas Stebila -auxiliary-submitters: [] crypto-assumption: learning with errors (LWE) website: https://frodokem.org/ nist-round: 3 diff --git a/docs/algorithms/kem/hqc.md b/docs/algorithms/kem/hqc.md index 10ee674b6..861ec9dc6 100644 --- a/docs/algorithms/kem/hqc.md +++ b/docs/algorithms/kem/hqc.md @@ -20,13 +20,15 @@ ## HQC-128 implementation characteristics -| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | -|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| clean | All | All | None | True | True | False | -| avx2 | x86\_64 | Linux,Darwin | AVX2,BMI1,PCLMULQDQ | False | True | False | +| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage?‡ | +|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:----------------------| +| clean | All | All | None | True | True | False | +| avx2 | x86\_64 | Linux,Darwin | AVX2,BMI1,PCLMULQDQ | False | True | False | Are implementations chosen based on runtime CPU feature detection? **Yes**. + ‡For an explanation of what this denotes, consult the [Explanation of Terms](#explanation-of-terms) section at the end of this file. + ## HQC-192 implementation characteristics | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | @@ -41,6 +43,10 @@ Are implementations chosen based on runtime CPU feature detection? **Yes**. | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | |:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| | clean | All | All | None | True | True | False | -| avx2 | x86\_64 | Linux,Darwin | AVX2,BMI1,PCLMULQDQ | False | True | False | +| avx2 | x86\_64 | Linux,Darwin | AVX2,BMI1,PCLMULQDQ | False | True | True | Are implementations chosen based on runtime CPU feature detection? **Yes**. + +## Explanation of Terms + +- **Large Stack Usage**: Implementations identified as having such may cause failures when running in threads or in constrained environments. \ No newline at end of file diff --git a/docs/algorithms/kem/hqc.yml b/docs/algorithms/kem/hqc.yml index bd81a73ca..5a78f15d9 100644 --- a/docs/algorithms/kem/hqc.yml +++ b/docs/algorithms/kem/hqc.yml @@ -115,4 +115,4 @@ parameter-sets: - SHA3: liboqs no-secret-dependent-branching-claimed: false no-secret-dependent-branching-checked-by-valgrind: true - large-stack-usage: false + large-stack-usage: true diff --git a/docs/algorithms/kem/kyber.md b/docs/algorithms/kem/kyber.md index c998b6e51..f7aaa61d8 100644 --- a/docs/algorithms/kem/kyber.md +++ b/docs/algorithms/kem/kyber.md @@ -22,13 +22,15 @@ ## Kyber512 implementation characteristics -| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | -|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| ref | All | All | None | True | True | False | -| avx2 | x86\_64 | Linux,Darwin | AVX2,BMI2,POPCNT | True | True | False | +| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage?‡ | +|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:----------------------| +| ref | All | All | None | True | True | False | +| avx2 | x86\_64 | Linux,Darwin | AVX2,BMI2,POPCNT | True | True | False | Are implementations chosen based on runtime CPU feature detection? **Yes**. + ‡For an explanation of what this denotes, consult the [Explanation of Terms](#explanation-of-terms) section at the end of this file. + ## Kyber512-90s implementation characteristics | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | @@ -73,3 +75,7 @@ Are implementations chosen based on runtime CPU feature detection? **Yes**. | avx2 | x86\_64 | Linux,Darwin | AES,AVX2,BMI2,POPCNT | True | True | False | Are implementations chosen based on runtime CPU feature detection? **Yes**. + +## Explanation of Terms + +- **Large Stack Usage**: Implementations identified as having such may cause failures when running in threads or in constrained environments. \ No newline at end of file diff --git a/docs/algorithms/kem/ntru.md b/docs/algorithms/kem/ntru.md index 4c9b79258..a5d7d53dc 100644 --- a/docs/algorithms/kem/ntru.md +++ b/docs/algorithms/kem/ntru.md @@ -21,13 +21,15 @@ ## NTRU-HPS-2048-509 implementation characteristics -| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | -|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| clean | All | All | None | True | True | False | -| avx2 | x86\_64 | Linux,Darwin | AVX2,BMI2 | True | True | False | +| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage?‡ | +|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:----------------------| +| clean | All | All | None | True | True | False | +| avx2 | x86\_64 | Linux,Darwin | AVX2,BMI2 | True | True | False | Are implementations chosen based on runtime CPU feature detection? **Yes**. + ‡For an explanation of what this denotes, consult the [Explanation of Terms](#explanation-of-terms) section at the end of this file. + ## NTRU-HPS-2048-677 implementation characteristics | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | @@ -54,3 +56,7 @@ Are implementations chosen based on runtime CPU feature detection? **Yes**. | avx2 | x86\_64 | Linux,Darwin | AVX2,BMI2 | True | True | False | Are implementations chosen based on runtime CPU feature detection? **Yes**. + +## Explanation of Terms + +- **Large Stack Usage**: Implementations identified as having such may cause failures when running in threads or in constrained environments. \ No newline at end of file diff --git a/docs/algorithms/kem/ntruprime.md b/docs/algorithms/kem/ntruprime.md index 5164d8985..1c1d5aa98 100644 --- a/docs/algorithms/kem/ntruprime.md +++ b/docs/algorithms/kem/ntruprime.md @@ -23,13 +23,15 @@ ## ntrulpr653 implementation characteristics -| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | -|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| clean | All | All | None | True | True | False | -| avx2 | x86\_64 | Linux,Darwin | AVX2 | False | True | False | +| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage?‡ | +|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:----------------------| +| clean | All | All | None | True | True | False | +| avx2 | x86\_64 | Linux,Darwin | AVX2 | False | True | False | Are implementations chosen based on runtime CPU feature detection? **Yes**. + ‡For an explanation of what this denotes, consult the [Explanation of Terms](#explanation-of-terms) section at the end of this file. + ## ntrulpr761 implementation characteristics | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | @@ -74,3 +76,7 @@ Are implementations chosen based on runtime CPU feature detection? **Yes**. | avx2 | x86\_64 | Linux,Darwin | AVX2 | False | True | False | Are implementations chosen based on runtime CPU feature detection? **Yes**. + +## Explanation of Terms + +- **Large Stack Usage**: Implementations identified as having such may cause failures when running in threads or in constrained environments. \ No newline at end of file diff --git a/docs/algorithms/kem/saber.md b/docs/algorithms/kem/saber.md index 988c51860..329178b92 100644 --- a/docs/algorithms/kem/saber.md +++ b/docs/algorithms/kem/saber.md @@ -20,13 +20,15 @@ ## LightSaber-KEM implementation characteristics -| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | -|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| clean | All | All | None | True | True | False | -| avx2 | x86\_64 | Linux,Darwin | AVX2 | False | True | False | +| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage?‡ | +|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:----------------------| +| clean | All | All | None | True | True | False | +| avx2 | x86\_64 | Linux,Darwin | AVX2 | False | True | False | Are implementations chosen based on runtime CPU feature detection? **Yes**. + ‡For an explanation of what this denotes, consult the [Explanation of Terms](#explanation-of-terms) section at the end of this file. + ## Saber-KEM implementation characteristics | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | @@ -44,3 +46,7 @@ Are implementations chosen based on runtime CPU feature detection? **Yes**. | avx2 | x86\_64 | Linux,Darwin | AVX2 | False | True | False | Are implementations chosen based on runtime CPU feature detection? **Yes**. + +## Explanation of Terms + +- **Large Stack Usage**: Implementations identified as having such may cause failures when running in threads or in constrained environments. \ No newline at end of file diff --git a/docs/algorithms/kem/sike.md b/docs/algorithms/kem/sike.md index d6b8ec815..8fc0a5359 100644 --- a/docs/algorithms/kem/sike.md +++ b/docs/algorithms/kem/sike.md @@ -31,15 +31,17 @@ ## SIDH-p434 implementation characteristics -| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | -|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| optimized | All | All | None | True | True | False | -| additional\_amd64\_bmi2 | x86\_64 | Linux,Darwin | BMI2 | True | True | False | -| additional\_amd64\_adx | x86\_64 | Linux,Darwin | BMI2,ADX | True | True | False | -| additional\_arm64 | arm64v8 | Linux,Darwin | None | True | True | False | +| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage?‡ | +|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:----------------------| +| optimized | All | All | None | True | True | False | +| additional\_amd64\_bmi2 | x86\_64 | Linux,Darwin | BMI2 | True | True | False | +| additional\_amd64\_adx | x86\_64 | Linux,Darwin | BMI2,ADX | True | True | False | +| additional\_arm64 | arm64v8 | Linux,Darwin | None | True | True | False | Are implementations chosen based on runtime CPU feature detection? **No**. + ‡For an explanation of what this denotes, consult the [Explanation of Terms](#explanation-of-terms) section at the end of this file. + ## SIDH-p434-compressed implementation characteristics | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | @@ -212,3 +214,7 @@ Are implementations chosen based on runtime CPU feature detection? **No**. | additional\_arm64 | arm64v8 | Linux,Darwin | None | True | True | False | Are implementations chosen based on runtime CPU feature detection? **No**. + +## Explanation of Terms + +- **Large Stack Usage**: Implementations identified as having such may cause failures when running in threads or in constrained environments. \ No newline at end of file diff --git a/docs/algorithms/sig/dilithium.md b/docs/algorithms/sig/dilithium.md index 963a0896a..26ae26d7d 100644 --- a/docs/algorithms/sig/dilithium.md +++ b/docs/algorithms/sig/dilithium.md @@ -22,13 +22,15 @@ ## Dilithium2 implementation characteristics -| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | -|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| ref | All | All | None | True | True | False | -| avx2 | x86\_64 | Linux,Darwin | AVX2,POPCNT,SSE2,SSSE3 | True | True | False | +| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage?‡ | +|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:----------------------| +| ref | All | All | None | True | True | False | +| avx2 | x86\_64 | Linux,Darwin | AVX2,POPCNT,SSE2,SSSE3 | True | True | False | Are implementations chosen based on runtime CPU feature detection? **Yes**. + ‡For an explanation of what this denotes, consult the [Explanation of Terms](#explanation-of-terms) section at the end of this file. + ## Dilithium3 implementation characteristics | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | @@ -73,3 +75,7 @@ Are implementations chosen based on runtime CPU feature detection? **Yes**. | avx2 | x86\_64 | Linux,Darwin | AES,AVX2,POPCNT,SSE2,SSSE3 | True | True | False | Are implementations chosen based on runtime CPU feature detection? **Yes**. + +## Explanation of Terms + +- **Large Stack Usage**: Implementations identified as having such may cause failures when running in threads or in constrained environments. \ No newline at end of file diff --git a/docs/algorithms/sig/falcon.md b/docs/algorithms/sig/falcon.md index 6c99b7105..064beab3e 100644 --- a/docs/algorithms/sig/falcon.md +++ b/docs/algorithms/sig/falcon.md @@ -20,13 +20,15 @@ ## Falcon-512 implementation characteristics -| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | -|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| clean | All | All | None | True | True | False | -| avx2 | x86\_64 | Linux,Darwin | AVX2 | True | True | False | +| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage?‡ | +|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:----------------------| +| clean | All | All | None | True | True | False | +| avx2 | x86\_64 | Linux,Darwin | AVX2 | True | True | False | Are implementations chosen based on runtime CPU feature detection? **Yes**. + ‡For an explanation of what this denotes, consult the [Explanation of Terms](#explanation-of-terms) section at the end of this file. + ## Falcon-1024 implementation characteristics | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | @@ -35,3 +37,7 @@ Are implementations chosen based on runtime CPU feature detection? **Yes**. | avx2 | x86\_64 | Linux,Darwin | AVX2 | True | True | False | Are implementations chosen based on runtime CPU feature detection? **Yes**. + +## Explanation of Terms + +- **Large Stack Usage**: Implementations identified as having such may cause failures when running in threads or in constrained environments. \ No newline at end of file diff --git a/docs/algorithms/sig/picnic.md b/docs/algorithms/sig/picnic.md index dcbb9b478..da457d78f 100644 --- a/docs/algorithms/sig/picnic.md +++ b/docs/algorithms/sig/picnic.md @@ -27,14 +27,16 @@ ## picnic\_L1\_FS implementation characteristics -| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | -|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| master | All | All | None | True | True | False | -| master | x86\_64 | Linux | AVX2,SSE2 | True | True | False | -| master | x86\_64 | Darwin,Windows | SSE2 | True | True | False | +| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage?‡ | +|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:----------------------| +| master | All | All | None | True | True | False | +| master | x86\_64 | Linux | AVX2,SSE2 | True | True | False | +| master | x86\_64 | Darwin,Windows | SSE2 | True | True | False | Are implementations chosen based on runtime CPU feature detection? **No**. + ‡For an explanation of what this denotes, consult the [Explanation of Terms](#explanation-of-terms) section at the end of this file. + ## picnic\_L1\_UR implementation characteristics | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | @@ -144,3 +146,7 @@ Are implementations chosen based on runtime CPU feature detection? **No**. | master | x86\_64 | Darwin,Windows | SSE2 | True | True | False | Are implementations chosen based on runtime CPU feature detection? **No**. + +## Explanation of Terms + +- **Large Stack Usage**: Implementations identified as having such may cause failures when running in threads or in constrained environments. \ No newline at end of file diff --git a/docs/algorithms/sig/rainbow.md b/docs/algorithms/sig/rainbow.md index 0256eaa0a..204ce8d80 100644 --- a/docs/algorithms/sig/rainbow.md +++ b/docs/algorithms/sig/rainbow.md @@ -26,9 +26,11 @@ ## Rainbow-I-Classic implementation characteristics -| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | -|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| clean | All | All | None | True | True | False | +| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage?‡ | +|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:----------------------| +| clean | All | All | None | True | True | False | + + ‡For an explanation of what this denotes, consult the [Explanation of Terms](#explanation-of-terms) section at the end of this file. ## Rainbow-I-Circumzenithal implementation characteristics @@ -46,34 +48,38 @@ | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | |:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| clean | All | All | None | True | True | False | +| clean | All | All | None | True | True | True | ## Rainbow-III-Circumzenithal implementation characteristics | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | |:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| clean | All | All | None | True | True | False | +| clean | All | All | None | True | True | True | ## Rainbow-III-Compressed implementation characteristics | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | |:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| clean | All | All | None | True | True | False | +| clean | All | All | None | True | True | True | ## Rainbow-V-Classic implementation characteristics | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | |:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| clean | All | All | None | True | True | False | +| clean | All | All | None | True | True | True | ## Rainbow-V-Circumzenithal implementation characteristics | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | |:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| clean | All | All | None | True | True | False | +| clean | All | All | None | True | True | True | ## Rainbow-V-Compressed implementation characteristics | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | |:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| clean | All | All | None | True | True | False | +| clean | All | All | None | True | True | True | + +## Explanation of Terms + +- **Large Stack Usage**: Implementations identified as having such may cause failures when running in threads or in constrained environments. \ No newline at end of file diff --git a/docs/algorithms/sig/rainbow.yml b/docs/algorithms/sig/rainbow.yml index cd7e00314..da9ec8dfc 100644 --- a/docs/algorithms/sig/rainbow.yml +++ b/docs/algorithms/sig/rainbow.yml @@ -77,7 +77,7 @@ parameter-sets: - SHA2: liboqs no-secret-dependent-branching-claimed: true no-secret-dependent-branching-checked-by-valgrind: true - large-stack-usage: false + large-stack-usage: true - name: Rainbow-III-Circumzenithal claimed-nist-level: 3 claimed-security: EUF-CMA @@ -92,7 +92,7 @@ parameter-sets: - SHA2: liboqs no-secret-dependent-branching-claimed: true no-secret-dependent-branching-checked-by-valgrind: true - large-stack-usage: false + large-stack-usage: true - name: Rainbow-III-Compressed claimed-nist-level: 3 claimed-security: EUF-CMA @@ -107,7 +107,7 @@ parameter-sets: - SHA2: liboqs no-secret-dependent-branching-claimed: true no-secret-dependent-branching-checked-by-valgrind: true - large-stack-usage: false + large-stack-usage: true - name: Rainbow-V-Classic claimed-nist-level: 5 claimed-security: EUF-CMA @@ -122,7 +122,7 @@ parameter-sets: - SHA2: liboqs no-secret-dependent-branching-claimed: true no-secret-dependent-branching-checked-by-valgrind: true - large-stack-usage: false + large-stack-usage: true - name: Rainbow-V-Circumzenithal claimed-nist-level: 5 claimed-security: EUF-CMA @@ -137,7 +137,7 @@ parameter-sets: - SHA2: liboqs no-secret-dependent-branching-claimed: true no-secret-dependent-branching-checked-by-valgrind: true - large-stack-usage: false + large-stack-usage: true - name: Rainbow-V-Compressed claimed-nist-level: 5 claimed-security: EUF-CMA @@ -152,4 +152,4 @@ parameter-sets: - SHA2: liboqs no-secret-dependent-branching-claimed: true no-secret-dependent-branching-checked-by-valgrind: true - large-stack-usage: false + large-stack-usage: true diff --git a/docs/algorithms/sig/sphincs.md b/docs/algorithms/sig/sphincs.md index 81b4bcd83..3002461c9 100644 --- a/docs/algorithms/sig/sphincs.md +++ b/docs/algorithms/sig/sphincs.md @@ -53,13 +53,15 @@ ## SPHINCS+-Haraka-128f-robust implementation characteristics -| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | -|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:---------------------| -| clean | All | All | None | True | True | False | -| aesni | x86\_64 | All | AES | True | True | False | +| Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage?‡ | +|:------------------------:|:----------------------------|:--------------------------------|:------------------------|:-----------------------------------|:-----------------------------------------------|:----------------------| +| clean | All | All | None | True | True | False | +| aesni | x86\_64 | All | AES | True | True | False | Are implementations chosen based on runtime CPU feature detection? **Yes**. + ‡For an explanation of what this denotes, consult the [Explanation of Terms](#explanation-of-terms) section at the end of this file. + ## SPHINCS+-Haraka-128f-simple implementation characteristics | Identifier in upstream | Supported architecture(s) | Supported operating system(s) | CPU extension(s) used | No branching-on-secrets claimed? | No branching-on-secrets checked by valgrind? | Large stack usage? | @@ -374,3 +376,7 @@ Are implementations chosen based on runtime CPU feature detection? **Yes**. | avx2 | x86\_64 | All | AVX2 | True | True | False | Are implementations chosen based on runtime CPU feature detection? **Yes**. + +## Explanation of Terms + +- **Large Stack Usage**: Implementations identified as having such may cause failures when running in threads or in constrained environments. \ No newline at end of file diff --git a/scripts/copy_from_upstream/copy_from_upstream.py b/scripts/copy_from_upstream/copy_from_upstream.py index 8b89076be..b1c556067 100755 --- a/scripts/copy_from_upstream/copy_from_upstream.py +++ b/scripts/copy_from_upstream/copy_from_upstream.py @@ -13,7 +13,6 @@ import yaml from pathlib import Path import sys import json -import mdformat # kats of all algs kats = {} @@ -471,16 +470,6 @@ def process_families(instructions, basedir, with_kat, with_generator): scheme, ) - generator( - os.path.join(os.environ['LIBOQS_DIR'], 'docs', 'algorithms', family['type'], '{}.md'.format(family['name'])), - os.path.join('docs', 'algorithms', family['type'], '{}.md'.format(family['name'])), - family, - None, - ) - mdformat.file(os.path.join(os.environ['LIBOQS_DIR'], 'docs', 'algorithms', family['type'], '{}.md'.format(family['name'])), - extensions={"tables"}) - - def copy_from_upstream(): for t in ["kem", "sig"]: with open(os.path.join(os.environ['LIBOQS_DIR'], 'tests', 'KATs', t, 'kats.json'), 'r') as fp: @@ -508,7 +497,7 @@ def copy_from_upstream(): if not keepdata: shutil.rmtree('repos') - #print("Remember to update $LIBOQS_DIR/docs/algorithms//.md") + #print("Remember to update the docs by running scripts/copy_from_upstream/update_pqclean_alg_docs.py -> scripts/format_docs_yaml.py -> scripts/update_docs_from_yaml.py") def verify_from_upstream(): diff --git a/scripts/copy_from_upstream/docs/algorithms/kem/classic_mceliece.md b/scripts/copy_from_upstream/docs/algorithms/kem/classic_mceliece.md deleted file mode 100644 index a23bc0f57..000000000 --- a/scripts/copy_from_upstream/docs/algorithms/kem/classic_mceliece.md +++ /dev/null @@ -1,26 +0,0 @@ -Classic McEliece -================ - -- **Algorithm type**: key encapsulation mechanism -- **Main cryptographic assumption**: Niederreiter's dual version of McEliece's public key encryption using binary Goppa codes -- **Scheme authors**: Daniel J. Bernstein, Tung Chou, Tanja Lange, Ingo von Maurich, Rafael Misoczki, Ruben Niederhagen, Edoardo Persichetti, Christiane Peters, Peter Schwabe, Nicolas Sendrier, Jakub Szefer, Wen Wang -- **Authors' website**: https://classic.mceliece.org -- **Version**: SUPERCOP-20191221 - -Implementation --------------- - -- **Source of implementation**: SUPERCOP-20191221, "vec" and "avx" implementations -- **Implementation version**: {{ schemes[0]['git_url'] }}, {{ schemes[0]['git_branch'] }}, {{ schemes[0]['git_commit'] }} -- **License**: Public domain -- **Constant-time**: Yes -- **Optimizations**: Portable C {%- if all_required_flags|length > 0 %} with {% for flag in all_required_flags|sort -%}{{ flag|upper }}{%- if not loop.last %}, {% endif -%}{%- endfor %} instructions (if available at run-time){%- endif %} - -Parameter sets --------------- - -| Parameter set | Security model | Claimed NIST security level | Public key size (bytes) | Secret key size (bytes) | Ciphertext size (bytes) | Shared secret size (bytes) | -|---------------------------|----------------|-----------------------------|-------------------------|-------------------------|-------------------------|----------------------------| -{% for scheme in schemes -%} -| {{ scheme['pretty_name_full'] }} | {{ scheme['metadata']['claimed-security'] }} | {{ scheme['metadata']['claimed-nist-level'] }} | {{ scheme['metadata']['length-public-key'] }} | {{ scheme['metadata']['length-secret-key'] }} | {{ scheme['metadata']['length-ciphertext'] }} | {{ scheme['metadata']['length-shared-secret'] }} | -{% endfor -%} diff --git a/scripts/copy_from_upstream/docs/algorithms/kem/hqc.md b/scripts/copy_from_upstream/docs/algorithms/kem/hqc.md deleted file mode 100644 index 83758f0e6..000000000 --- a/scripts/copy_from_upstream/docs/algorithms/kem/hqc.md +++ /dev/null @@ -1,26 +0,0 @@ -HQC -=== - -- **Algorithm type**: key encapsulation mechanism -- **Main cryptographic assumption**: Syndrome decoding of structure codes (Hamming Quasi-Cyclic) -- **Scheme authors**: Carlos Aguilar Melchor, Nicolas Aragon, Slim Bettaieb, Loïc Bidoux, Olivier Blazy, Jurjen Bos, Jean-Christophe Deneuville, Arnaud Dion, Philippe Gaborit, Jérôme Lacan, Edoardo Persichetti, Jean-Marc Robert, Rascal Véron, Gilles Zémor -- **Authors' website**: http://pqc-hqc.org -- **Version**: 2020/10/01 - -Implementation --------------- - -- **Source of implementation**: hqc-submission_2020-10-01 via https://github.com/jschanck/package-pqclean/tree/c9181076/hqc -- **Implementation version**: {{ schemes[0]['git_url'] }}, {{ schemes[0]['git_branch'] }}, {{ schemes[0]['git_commit'] }} -- **License**: Public domain -- **Constant-time**: Yes -- **Optimizations**: Portable C {%- if all_required_flags|length > 0 %} with {% for flag in all_required_flags|sort -%}{{ flag|upper }}{%- if not loop.last %}, {% endif -%}{%- endfor %} instructions (if available at run-time){%- endif %} - -Parameter sets --------------- - -| Parameter set | Security model | Claimed NIST security level | Public key size (bytes) | Secret key size (bytes) | Ciphertext size (bytes) | Shared secret size (bytes) | -|---------------------------|----------------|-----------------------------|-------------------------|-------------------------|-------------------------|----------------------------| -{% for scheme in schemes -%} -| {{ scheme['pretty_name_full'] }} | {{ scheme['metadata']['claimed-security'] }} | {{ scheme['metadata']['claimed-nist-level'] }} | {{ scheme['metadata']['length-public-key'] }} | {{ scheme['metadata']['length-secret-key'] }} | {{ scheme['metadata']['length-ciphertext'] }} | {{ scheme['metadata']['length-shared-secret'] }} | -{% endfor -%} diff --git a/scripts/copy_from_upstream/docs/algorithms/kem/kyber.md b/scripts/copy_from_upstream/docs/algorithms/kem/kyber.md deleted file mode 100644 index 161d251fc..000000000 --- a/scripts/copy_from_upstream/docs/algorithms/kem/kyber.md +++ /dev/null @@ -1,26 +0,0 @@ -CRYSTALS-Kyber -============== - -- **Algorithm type**: key encapsulation mechanism -- **Main cryptographic assumption**: module learning with errors (MLWE) -- **Scheme authors**: Roberto Avanzi, Joppe Bos, Léo Ducas, Eike Kiltz, Tancrède Lepoint, Vadim Lyubashevsky, John M. Schanck, Peter Schwabe, Gregor Seiler, Damien Stehle -- **Authors' website**: https://pq-crystals.org/kyber -- **Version**: NIST Round 3 submission - -Implementation --------------- - -- **Source of implementation**: https://github.com/pq-crystals/kyber -- **Implementation version**: {{ schemes[0]['git_url'] }}, {{ schemes[0]['git_branch'] }}, {{ schemes[0]['git_commit'] }} -- **License**: Public domain -- **Constant-time**: Yes -- **Optimizations**: Portable C {%- if all_required_flags|length > 0 %} with {% for flag in all_required_flags|sort -%}{{ flag|upper }}{%- if not loop.last %}, {% endif -%}{%- endfor %} instructions (if available at run-time){%- endif %} - -Parameter sets --------------- - -| Parameter set | Security model | Claimed NIST security level | Public key size (bytes) | Secret key size (bytes) | Ciphertext size (bytes) | Shared secret size (bytes) | -|---------------------------|----------------|-----------------------------|-------------------------|-------------------------|-------------------------|----------------------------| -{% for scheme in schemes -%} -| {{ scheme['pretty_name_full'] }} | {{ scheme['metadata']['claimed-security'] }} | {{ scheme['metadata']['claimed-nist-level'] }} | {{ scheme['metadata']['length-public-key'] }} | {{ scheme['metadata']['length-secret-key'] }} | {{ scheme['metadata']['length-ciphertext'] }} | {{ scheme['metadata']['length-shared-secret'] }} | -{% endfor -%} diff --git a/scripts/copy_from_upstream/docs/algorithms/kem/ntru.md b/scripts/copy_from_upstream/docs/algorithms/kem/ntru.md deleted file mode 100644 index 0a0104ab5..000000000 --- a/scripts/copy_from_upstream/docs/algorithms/kem/ntru.md +++ /dev/null @@ -1,26 +0,0 @@ -NTRU -==== - -- **Algorithm type**: key encapsulation mechanism -- **Main cryptographic assumption**: NTRU -- **Scheme authors**: John M. Schanck, Cong Chen, Oussama Danba, Jeffrey Hoffstein, Andreas Hülsing, Joost Rijneveld, Peter Schwabe, William Whyte, Zhenfei Zhang -- **Authors' website**: https://ntru.org -- **Version**: NIST Round 3 submission - -Implementation --------------- - -- **Source of implementation**: https://github.com/jschanck/ntru/tree/a43a4457 -- **Implementation version**: {{ schemes[0]['git_url'] }}, {{ schemes[0]['git_branch'] }}, {{ schemes[0]['git_commit'] }} -- **License**: Public domain -- **Constant-time**: Yes -- **Optimizations**: Portable C {%- if all_required_flags|length > 0 %} with {% for flag in all_required_flags|sort -%}{{ flag|upper }}{%- if not loop.last %}, {% endif -%}{%- endfor %} instructions (if available at run-time){%- endif %} - -Parameter sets --------------- - -| Parameter set | Security model | Claimed NIST security level | Public key size (bytes) | Secret key size (bytes) | Ciphertext size (bytes) | Shared secret size (bytes) | -|---------------------------|----------------|-----------------------------|-------------------------|-------------------------|-------------------------|----------------------------| -{% for scheme in schemes -%} -| {{ scheme['pretty_name_full'] }} | {{ scheme['metadata']['claimed-security'] }} | {{ scheme['metadata']['claimed-nist-level'] }} | {{ scheme['metadata']['length-public-key'] }} | {{ scheme['metadata']['length-secret-key'] }} | {{ scheme['metadata']['length-ciphertext'] }} | {{ scheme['metadata']['length-shared-secret'] }} | -{% endfor -%} diff --git a/scripts/copy_from_upstream/docs/algorithms/kem/ntruprime.md b/scripts/copy_from_upstream/docs/algorithms/kem/ntruprime.md deleted file mode 100644 index fc6853e7b..000000000 --- a/scripts/copy_from_upstream/docs/algorithms/kem/ntruprime.md +++ /dev/null @@ -1,26 +0,0 @@ -NTRU-Prime -========== - -- **Algorithm type**: key encapsulation mechanism -- **Main cryptographic assumption**: NTRU -- **Scheme authors**: Daniel J. Bernstein, Billy Bob Brumley, Ming-Shing Chen, Chitchanok Chuengsatiansup, Tanja Lange, Adrian Marotzke, Bo-Yuan Peng, Nicola Tuveri, Christine van Vredendaal, Bo-Yin Yang -- **Authors' website**: https://ntruprime.cr.yp.to -- **Version**: supercop-20200826 - -Implementation --------------- - -- **Source of implementation**: SUPERCOP-20200826 -- **Implementation version**: {{ schemes[0]['git_url'] }}, {{ schemes[0]['git_branch'] }}, {{ schemes[0]['git_commit'] }} -- **License**: Public domain -- **Constant-time**: Yes -- **Optimizations**: Portable C {%- if all_required_flags|length > 0 %} with {% for flag in all_required_flags|sort -%}{{ flag|upper }}{%- if not loop.last %}, {% endif -%}{%- endfor %} instructions (if available at run-time){%- endif %} - -Parameter sets --------------- - -| Parameter set | Security model | Claimed NIST security level | Public key size (bytes) | Secret key size (bytes) | Ciphertext size (bytes) | Shared secret size (bytes) | -|---------------------------|----------------|-----------------------------|-------------------------|-------------------------|-------------------------|----------------------------| -{% for scheme in schemes -%} -| {{ scheme['pretty_name_full'] }} | {{ scheme['metadata']['claimed-security'] }} | {{ scheme['metadata']['claimed-nist-level'] }} | {{ scheme['metadata']['length-public-key'] }} | {{ scheme['metadata']['length-secret-key'] }} | {{ scheme['metadata']['length-ciphertext'] }} | {{ scheme['metadata']['length-shared-secret'] }} | -{% endfor -%} diff --git a/scripts/copy_from_upstream/docs/algorithms/kem/saber.md b/scripts/copy_from_upstream/docs/algorithms/kem/saber.md deleted file mode 100644 index 79a011569..000000000 --- a/scripts/copy_from_upstream/docs/algorithms/kem/saber.md +++ /dev/null @@ -1,26 +0,0 @@ -SABER -===== - -- **Algorithm type**: key encapsulation mechanism -- **Main cryptographic assumption**: module learning with rounding -- **Scheme authors**: Jan-Pieter D'Anvers, Angshuman Karmakar, Sujoy Sinha Roy, Frederic Vercauteren -- **Authors' website**: https://www.esat.kuleuven.be/cosic/pqcrypto/saber/ -- **Version**: NIST Round 3 submission - -Implementation --------------- - -- **Source of implementation**: https://github.com/KULeuven-COSIC/SABER/tree/509cc5ec3a7e12a751ccdd2ef5bd6e54e00bd350 via https://github.com/jschanck/package-pqclean/tree/1ae84c3c/saber -- **Implementation version**: {{ schemes[0]['git_url'] }}, {{ schemes[0]['git_branch'] }}, {{ schemes[0]['git_commit'] }} -- **License**: Public domain -- **Constant-time**: Yes -- **Optimizations**: Portable C {%- if all_required_flags|length > 0 %} with {% for flag in all_required_flags|sort -%}{{ flag|upper }}{%- if not loop.last %}, {% endif -%}{%- endfor %} instructions (if available at run-time){%- endif %} - -Parameter sets --------------- - -| Parameter set | Security model | Claimed NIST security level | Public key size (bytes) | Secret key size (bytes) | Ciphertext size (bytes) | Shared secret size (bytes) | -|---------------------------|----------------|-----------------------------|-------------------------|-------------------------|-------------------------|----------------------------| -{% for scheme in schemes -%} -| {{ scheme['pretty_name_full'] }} | {{ scheme['metadata']['claimed-security'] }} | {{ scheme['metadata']['claimed-nist-level'] }} | {{ scheme['metadata']['length-public-key'] }} | {{ scheme['metadata']['length-secret-key'] }} | {{ scheme['metadata']['length-ciphertext'] }} | {{ scheme['metadata']['length-shared-secret'] }} | -{% endfor -%} diff --git a/scripts/copy_from_upstream/docs/algorithms/sig/dilithium.md b/scripts/copy_from_upstream/docs/algorithms/sig/dilithium.md deleted file mode 100644 index 94454b90d..000000000 --- a/scripts/copy_from_upstream/docs/algorithms/sig/dilithium.md +++ /dev/null @@ -1,26 +0,0 @@ -CRYSTALS-Dilithium -================== - -- **Algorithm type**: signature -- **Main cryptographic assumption**: hardness of lattice problems over module lattices. -- **Scheme authors**: Vadim Lyubashevsky, Leo Ducas, Eike Kiltz, Tancrede Lepoint, Peter Schwabe, Gregor Seiler, Damien Stehle -- **Authors' website**: https://pq-crystals.org/dilithium/ -- **Version**: 3.1 - -Implementation --------------- - -- **Source of implementation**: https://github.com/pq-crystals/dilithium -- **Implementation version**: {{ schemes[0]['git_url'] }}, {{ schemes[0]['git_branch'] }}, {{ schemes[0]['git_commit'] }} -- **License**: public domain -- **Constant-time**: Yes -- **Optimizations**: Portable C {%- if all_required_flags|length > 0 %} with {% for flag in all_required_flags|sort -%}{{ flag|upper }}{%- if not loop.last %}, {% endif -%}{%- endfor %} instructions (if available at run-time){%- endif %} - -Parameter sets --------------- - -| Parameter set | Security model | Claimed NIST security level | Public key size (bytes) | Secret key size (bytes) | Signature size (bytes) | -|---------------------|----------------|-----------------------------|-------------------------|-------------------------|------------------------| -{% for scheme in schemes -%} -| {{ scheme['pretty_name_full'] }} | EUF-CMA | {{ scheme['metadata']['claimed-nist-level'] }} | {{ scheme['metadata']['length-public-key'] }} | {{ scheme['metadata']['length-secret-key'] }} | {{ scheme['metadata']['length-signature'] }} | -{% endfor -%} diff --git a/scripts/copy_from_upstream/docs/algorithms/sig/falcon.md b/scripts/copy_from_upstream/docs/algorithms/sig/falcon.md deleted file mode 100644 index 5f9132978..000000000 --- a/scripts/copy_from_upstream/docs/algorithms/sig/falcon.md +++ /dev/null @@ -1,26 +0,0 @@ -Falcon -====== - -- **Algorithm type**: signature -- **Main cryptographic assumption**: hardness of NTRU lattice problems -- **Scheme authors**: Thomas Prest, Pierre-Alain Fouque, Jeffrey Hoffstein, Paul Kirchner, Vadim Lyubashevsky, Thomas Pornin, Thomas Ricosset, Gregor Seiler, William Whyte, Zhenfei Zhang -- **Authors' website**: https://falcon-sign.info -- **Version**: 20201018 - -Implementation --------------- - -- **Source of implementation**: supercop-20201018 via https://github.com/jschanck/package-pqclean/tree/cea1fa5a/falcon -- **Implementation version**: {{ schemes[0]['git_url'] }}, {{ schemes[0]['git_branch'] }}, {{ schemes[0]['git_commit'] }} -- **License**: CC0 1.0 Universal -- **Constant-time**: Yes -- **Optimizations**: Portable C {%- if all_required_flags|length > 0 %} with {% for flag in all_required_flags|sort -%}{{ flag|upper }}{%- if not loop.last %}, {% endif -%}{%- endfor %} instructions (if available at run-time){%- endif %} - -Parameter sets --------------- - -| Parameter set | Security model | Claimed NIST security level | Public key size (bytes) | Secret key size (bytes) | Signature size (bytes) | -|---------------------|----------------|-----------------------------|-------------------------|-------------------------|------------------------| -{% for scheme in schemes -%} -| {{ scheme['pretty_name_full'] }} | EUF-CMA | {{ scheme['metadata']['claimed-nist-level'] }} | {{ scheme['metadata']['length-public-key'] }} | {{ scheme['metadata']['length-secret-key'] }} | {{ scheme['metadata']['length-signature'] }} | -{% endfor -%} diff --git a/scripts/copy_from_upstream/docs/algorithms/sig/rainbow.md b/scripts/copy_from_upstream/docs/algorithms/sig/rainbow.md deleted file mode 100644 index fb99c55b4..000000000 --- a/scripts/copy_from_upstream/docs/algorithms/sig/rainbow.md +++ /dev/null @@ -1,30 +0,0 @@ -Rainbow -======= - -- **Algorithm type**: signature -- **Main cryptographic assumption**: multivariable polynomials, unbalanced oil and vinegar -- **Scheme authors**: Jintai Ding, Ming-Shing Chen, Albrecht Petzoldt, Dieter Schmidt, Bo-Yin Yang -- **Version**: NIST Round 3 submission - -Implementation --------------- - -- **Source of implementation**: https://github.com/fast-crypto-lab/rainbow-submission-round2/commit/173ada0e077e1b9dbd8e4a78994f87acc0c92263 -- **Implementation version**: {{ schemes[0]['git_url'] }}, {{ schemes[0]['git_branch'] }}, {{ schemes[0]['git_commit'] }} -- **License**: CC0 1.0 -- **Constant-time**: Yes -- **Optimizations**: Portable C {%- if all_required_flags|length > 0 %} with {% for flag in all_required_flags|sort -%}{{ flag|upper }}{%- if not loop.last %}, {% endif -%}{%- endfor %} instructions (if available at run-time){%- endif %} - -Parameter sets --------------- - -| Parameter set | Security model | Claimed NIST security level | Public key size (bytes) | Secret key size (bytes) | Signature size (bytes) | -|---------------------|----------------|-----------------------------|-------------------------|-------------------------|------------------------| -{% for scheme in schemes -%} -| {{ scheme['pretty_name_full'] }} | EUF-CMA | {{ scheme['metadata']['claimed-nist-level'] }} | {{ scheme['metadata']['length-public-key'] }} | {{ scheme['metadata']['length-secret-key'] }} | {{ scheme['metadata']['length-signature'] }} | -{% endfor -%} - -Security considerations ------------------------ - -In October 2020, Beullens announced [improved cryptanalysis of Rainbow](https://eprint.iacr.org/2020/1343.pdf) that somewhat reduces the security of the Round 2 and Round 3 parameters. [As of October 28, 2020](https://groups.google.com/a/list.nist.gov/g/pqc-forum/c/70We3SNi7Ss), the scheme authors have acknowledged the attack and are preparing a response. diff --git a/scripts/copy_from_upstream/docs/algorithms/sig/sphincs.md b/scripts/copy_from_upstream/docs/algorithms/sig/sphincs.md deleted file mode 100644 index 97938736b..000000000 --- a/scripts/copy_from_upstream/docs/algorithms/sig/sphincs.md +++ /dev/null @@ -1,26 +0,0 @@ -SPHINCS+ -======== - -- **Algorithm type**: signature -- **Main cryptographic assumption**: hash-based signatures -- **Scheme authors**: Andreas Hulsing, Daniel J. Bernstein, Christoph Dobraunig, Maria Eichlseder, Scott Fluhrer, Stefan-Lukas Gazdag, Panos Kampanakis, Stefan Kolbl, Tanja Lange, Martin M Lauridsen, Florian Mendel, Ruben Niederhagen, Christian Rechberger, Joost Rijneveld, Peter Schwabe, Jean-Philippe Aumasson -- **Authors' website**: https://sphincs.org/ -- **Version**: NIST Round 2 submission - -Implementation --------------- - -- **Source of implementation**: https://github.com/sphincs/sphincsplus -- **Implementation version**: {{ schemes[0]['git_url'] }}, {{ schemes[0]['git_branch'] }}, {{ schemes[0]['git_commit'] }} -- **License**: CC0 1.0 Universal -- **Constant-time**: Yes -- **Optimizations**: Portable C {%- if all_required_flags|length > 0 %} with {% for flag in all_required_flags|sort -%}{{ flag|upper }}{%- if not loop.last %}, {% endif -%}{%- endfor %} instructions (if available at run-time){%- endif %} - -Parameter sets --------------- - -| Parameter set | Security model | Claimed NIST security level | Public key size (bytes) | Secret key size (bytes) | Signature size (bytes) | -|---------------------|----------------|-----------------------------|-------------------------|-------------------------|------------------------| -{% for scheme in schemes -%} -| {{ scheme['pretty_name_full'] }} | EUF-CMA | {{ scheme['metadata']['claimed-nist-level'] }} | {{ scheme['metadata']['length-public-key'] }} | {{ scheme['metadata']['length-secret-key'] }} | {{ scheme['metadata']['length-signature'] }} | -{% endfor -%} diff --git a/scripts/copy_from_upstream/requirements.txt b/scripts/copy_from_upstream/requirements.txt index f13e18dfb..06f197627 100644 --- a/scripts/copy_from_upstream/requirements.txt +++ b/scripts/copy_from_upstream/requirements.txt @@ -3,8 +3,6 @@ importlib-metadata==3.7.0 Jinja2==2.11.3 markdown-it-py==0.6.2 MarkupSafe==1.1.1 -mdformat==0.5.7 -mdformat-tables==0.2.1 mdit-py-plugins==0.2.5 PyYAML==5.4.1 typing-extensions==3.7.4.3 diff --git a/scripts/gen_docs_md_from_yaml.py b/scripts/update_docs_from_yaml.py similarity index 56% rename from scripts/gen_docs_md_from_yaml.py rename to scripts/update_docs_from_yaml.py index c4a3fde6c..140876d35 100644 --- a/scripts/gen_docs_md_from_yaml.py +++ b/scripts/update_docs_from_yaml.py @@ -7,12 +7,6 @@ import tabulate import yaml import os -# TODO: Add explanatory notes at the end of each markdown file with -# respect to the following keys: -# - no-secret-dependent-branching-claimed -# - no-secret-dependent-branching-checked-by-valgrind -# - large-stack-usage - parser = argparse.ArgumentParser() parser.add_argument("--liboqs-root", default=".") args = parser.parse_args() @@ -21,11 +15,21 @@ def load_yaml(filename, encoding='utf-8'): with open(filename, mode='r', encoding=encoding) as fh: return yaml.safe_load(fh.read()) -# Generate the KEM markdown documentation. -for kem_yaml_path in glob.glob(os.path.join(args.liboqs_root, 'docs', 'algorithms', 'kem', '*.yml')): +def file_get_contents(filename, encoding=None): + with open(filename, mode='r', encoding=encoding) as fh: + return fh.read() + +kem_yamls = [] +sig_yamls = [] + +######################################## +# Update the KEM markdown documentation. +######################################## +for kem_yaml_path in sorted(glob.glob(os.path.join(args.liboqs_root, 'docs', 'algorithms', 'kem', '*.yml'))): kem_yaml = load_yaml(kem_yaml_path) + kem_yamls.append(kem_yaml) kem_name = os.path.splitext(os.path.basename(kem_yaml_path))[0] - print('Updating {}.md'.format(kem_name)) + print('Updating {}/{}.md'.format(os.path.dirname(kem_yaml_path), kem_name)) with open(os.path.join(args.liboqs_root, 'docs', 'algorithms', 'kem', '{}.md'.format(kem_name)), mode='w', encoding='utf-8') as out_md: out_md.write('# {}\n\n'.format(kem_yaml['name'])) @@ -67,15 +71,20 @@ for kem_yaml_path in glob.glob(os.path.join(args.liboqs_root, 'docs', 'algorithm out_md.write(tabulate.tabulate(table, tablefmt="pipe", headers="firstrow", colalign=("center",))) out_md.write('\n') - for parameter_set in kem_yaml['parameter-sets']: + for index, parameter_set in enumerate(kem_yaml['parameter-sets']): out_md.write('\n## {} implementation characteristics\n\n'.format(parameter_set['name'])) - table = [['Identifier in upstream', - 'Supported architecture(s)', - 'Supported operating system(s)', - 'CPU extension(s) used', - 'No branching-on-secrets claimed?', - 'No branching-on-secrets checked by valgrind?', - 'Large stack usage?']] + table_header = ['Identifier in upstream', + 'Supported architecture(s)', + 'Supported operating system(s)', + 'CPU extension(s) used', + 'No branching-on-secrets claimed?', + 'No branching-on-secrets checked by valgrind?'] + if index == 0: + table_header.append('Large stack usage?‡') + else: + table_header.append('Large stack usage?') + + table = [table_header] for impl in parameter_set['implementations']: if impl['supported-platforms'] == 'all': table.append([impl['upstream-id'].replace('_', '\_'), @@ -100,14 +109,26 @@ for kem_yaml_path in glob.glob(os.path.join(args.liboqs_root, 'docs', 'algorithm impl['no-secret-dependent-branching-claimed'], impl['no-secret-dependent-branching-checked-by-valgrind'], impl['large-stack-usage']]) - out_md.write(tabulate.tabulate(table, tablefmt="pipe", headers="firstrow", colalign=("center",))) - out_md.write('\n\nAre implementations chosen based on runtime CPU feature detection? **{}**.\n'.format('Yes' if parameter_set['implementations-switch-on-runtime-cpu-features'] else 'No')) -# Generate the signature markdown documentation. -for sig_yaml_path in glob.glob(os.path.join(args.liboqs_root, 'docs', 'algorithms', 'sig', '*.yml')): + out_md.write(tabulate.tabulate(table, tablefmt="pipe", headers="firstrow", colalign=("center",))) + out_md.write('\n') + + if 'implementations-switch-on-runtime-cpu-features' in parameter_set: + out_md.write('\nAre implementations chosen based on runtime CPU feature detection? **{}**.\n'.format('Yes' if parameter_set['implementations-switch-on-runtime-cpu-features'] else 'No')) + if index == 0: + out_md.write('\n ‡For an explanation of what this denotes, consult the [Explanation of Terms](#explanation-of-terms) section at the end of this file.\n') + + out_md.write('\n## Explanation of Terms\n\n') + out_md.write('- **Large Stack Usage**: Implementations identified as having such may cause failures when running in threads or in constrained environments.') + +############################################## +# Update the signature markdown documentation. +############################################## +for sig_yaml_path in sorted(glob.glob(os.path.join(args.liboqs_root, 'docs', 'algorithms', 'sig', '*.yml'))): sig_yaml = load_yaml(sig_yaml_path) + sig_yamls.append(sig_yaml) sig_name = os.path.splitext(os.path.basename(sig_yaml_path))[0] - print('Updating {}.md'.format(sig_name)) + print('Updating {}/{}.md'.format(os.path.dirname(sig_yaml_path), sig_name)) with open(os.path.join(args.liboqs_root, 'docs', 'algorithms', 'sig', '{}.md'.format(sig_name)), mode='w', encoding='utf-8') as out_md: out_md.write('# {}\n\n'.format(sig_yaml['name'])) @@ -147,15 +168,20 @@ for sig_yaml_path in glob.glob(os.path.join(args.liboqs_root, 'docs', 'algorithm out_md.write(tabulate.tabulate(table, tablefmt="pipe", headers="firstrow", colalign=("center",))) out_md.write('\n') - for parameter_set in sig_yaml['parameter-sets']: + for index, parameter_set in enumerate(sig_yaml['parameter-sets']): out_md.write('\n## {} implementation characteristics\n\n'.format(parameter_set['name'].replace('_', '\_'))) - table = [['Identifier in upstream', - 'Supported architecture(s)', - 'Supported operating system(s)', - 'CPU extension(s) used', - 'No branching-on-secrets claimed?', - 'No branching-on-secrets checked by valgrind?', - 'Large stack usage?']] + table_header = ['Identifier in upstream', + 'Supported architecture(s)', + 'Supported operating system(s)', + 'CPU extension(s) used', + 'No branching-on-secrets claimed?', + 'No branching-on-secrets checked by valgrind?'] + if index == 0: + table_header.append('Large stack usage?‡') + else: + table_header.append('Large stack usage?') + + table = [table_header] for impl in parameter_set['implementations']: if impl['supported-platforms'] == 'all': table.append([impl['upstream-id'].replace('_', '\_'), @@ -183,7 +209,91 @@ for sig_yaml_path in glob.glob(os.path.join(args.liboqs_root, 'docs', 'algorithm impl['no-secret-dependent-branching-claimed'], impl['no-secret-dependent-branching-checked-by-valgrind'], impl['large-stack-usage']]) + out_md.write(tabulate.tabulate(table, tablefmt="pipe", headers="firstrow", colalign=("center",))) out_md.write('\n') + if 'implementations-switch-on-runtime-cpu-features' in parameter_set: out_md.write('\nAre implementations chosen based on runtime CPU feature detection? **{}**.\n'.format('Yes' if parameter_set['implementations-switch-on-runtime-cpu-features'] else 'No')) + if index == 0: + out_md.write('\n ‡For an explanation of what this denotes, consult the [Explanation of Terms](#explanation-of-terms) section at the end of this file.\n') + + out_md.write('\n## Explanation of Terms\n\n') + out_md.write('- **Large Stack Usage**: Implementations identified as having such may cause failures when running in threads or in constrained environments.') + +#################### +# Update the README. +#################### +print("Updating README.md") + +readme_path = os.path.join(args.liboqs_root, 'README.md') +start_identifier_tmpl = '' +end_identifier_tmpl = '' + +# KEMS +readme_contents = file_get_contents(readme_path) + +identifier_start = start_identifier_tmpl.format('KEXS') +identifier_end = end_identifier_tmpl.format('KEXS') + +preamble = readme_contents[:readme_contents.find(identifier_start)] +postamble = readme_contents[readme_contents.find(identifier_end):] + +with open(readme_path, mode='w', encoding='utf-8') as readme: + readme.write(preamble + identifier_start + '\n') + + for kem_yaml in kem_yamls: + parameter_sets = kem_yaml['parameter-sets'] + if any(impl['large-stack-usage'] for impl in parameter_sets[0]['implementations']): + readme.write('- **{}**: {}†'.format(kem_yaml['name'], parameter_sets[0]['name'])) + else: + readme.write('- **{}**: {}'.format(kem_yaml['name'], parameter_sets[0]['name'])) + for parameter_set in parameter_sets[1:]: + if any(impl['large-stack-usage'] for impl in parameter_set['implementations']): + readme.write(', {}†'.format(parameter_set['name'])) + else: + readme.write(', {}'.format(parameter_set['name'])) + readme.write('\n') + + readme.write(postamble) + +# Signatures +readme_contents = file_get_contents(readme_path) + +identifier_start = start_identifier_tmpl.format('SIGS') +identifier_end = end_identifier_tmpl.format('SIGS') + +preamble = readme_contents[:readme_contents.find(identifier_start)] +postamble = readme_contents[readme_contents.find(identifier_end):] + +with open(readme_path, mode='w', encoding='utf-8') as readme: + readme.write(preamble + identifier_start + '\n') + + for sig_yaml in sig_yamls[:-1]: # SPHINCS is last in this sorted list and requires special handling. + parameter_sets = sig_yaml['parameter-sets'] + if any(impl['large-stack-usage'] for impl in parameter_sets[0]['implementations']): + readme.write('- **{}**: {}†'.format(sig_yaml['name'], parameter_sets[0]['name'].replace('_','\_'))) + else: + readme.write('- **{}**: {}'.format(sig_yaml['name'], parameter_sets[0]['name'].replace('_','\_'))) + for parameter_set in parameter_sets[1:]: + if any(impl['large-stack-usage'] for impl in parameter_set['implementations']): + readme.write(', {}†'.format(parameter_set['name'].replace('_', '\_'))) + else: + readme.write(', {}'.format(parameter_set['name'].replace('_', '\_'))) + readme.write('\n') + + sphincs_yml = sig_yamls[-1] + for hash_func in ['Haraka', 'SHA256', 'SHAKE256']: + parameter_sets = [pset for pset in sphincs_yml['parameter-sets'] if hash_func in pset['name']] + if any(impl['large-stack-usage'] for impl in parameter_sets[0]['implementations']): + readme.write('- **SPHINCS+-{}**: {}†'.format(hash_func, parameter_sets[0]['name'].replace('_','\_'))) + else: + readme.write('- **SPHINCS+-{}**: {}'.format(hash_func, parameter_sets[0]['name'].replace('_','\_'))) + for parameter_set in parameter_sets[1:]: + if any(impl['large-stack-usage'] for impl in parameter_set['implementations']): + readme.write(', {}†'.format(parameter_set['name'].replace('_', '\_'))) + else: + readme.write(', {}'.format(parameter_set['name'].replace('_', '\_'))) + readme.write('\n') + + readme.write(postamble)