Set version in configure, library, and algorithms (#411)

* Set version of liboqs master and add draft release notes

* Add alg_version field for KEMs and signature schemes

* Prettyprint

* Added alg_version for qtesla and picnic.

* Update versioning proposal
This commit is contained in:
Douglas Stebila 2018-10-12 19:20:58 -04:00 committed by GitHub
parent bc4ebbaf2f
commit 67a2411ba4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
18 changed files with 120 additions and 18 deletions

View File

@ -72,13 +72,19 @@ Contributions that meet the acceptance criteria above are gratefully welcomed.
Lifecycle for master branch
---------------------------
**Release cycle:** We aim to make releases of liboqs master branch every 2 to 3 months. Plans for each individual release can be found on our [Github projects board](https://github.com/open-quantum-safe/liboqs/projects/). We will use semantic versioning ($X.Y.Z$) as described below.
**Release cycle:** We aim to make releases of liboqs master branch every 2 to 3 months. Plans for each individual release can be found on our [Github projects board](https://github.com/open-quantum-safe/liboqs/projects/).
**Algorithm deprecation:** If an algorithm in master branch is found to be insecure or does not advance to the next round of the NIST competition, but is included in version $X.Y.Z$, it will be marked as deprecated using a compile time warning in version $X.(Y+1).Z$ and removed in version $X.(Y+2).Z$.
**Versioning:** For approximately the period 2018-2019, we plan to label our releases with a variant of semantic versioning, using the notation *0.Y.Z*. Semantic versioning allows that anything may change between *0.whatever* versions. We intend to use *X.Y.Z* labelling as follows, for *X=0*.
**Algorithm compatibility:** Unlike existing standardization cryptographic algorithms (SHA-2, SHA-3, PKCS\#1v1.5, nistp256, ...), post-quantum algorithms are under active development, and the mathematical algorithm of a cryptographic scheme may change: a particular name (e.g., "FrodoKEM-AES-640") may refer to different mathematical algorithms over time. liboqs may update implementations as algorithms evolve. Using our semantic versioning, versions with the same first two components ($X.Y.*$) will be interoperable. But version $X.Y.Z$ and version $X.(Y+1).Z'$ may not be interoperable. liboqs-reliant applications can check the `alg_version` member of the `OQS_KEM` data structure for each algorithm to obtain an identifier of the algorithm version used in a particular implementation; implementations returning the same `alg_version` for an algorithm will be interoperable.
- *X=0* will be used for approximately the period 2018-2019. Later in 2019, we will revisit whether we are ready to make a *1.0.0* release, and specify a new verisoning method at that time.
- *Y* will be incremented when backwards incompatible changes are introduced that either change the public API or change the input/output behaviour of a cryptographic algorithm. See explanation below.
- *Z* will be incremented when backwards compatible bug fixes are introduced.
**API stability:** The public API of liboqs master branch is currently considered to be the functions and macros in `oqs/common.h`, `oqs/config.h`, `oqs/kem.h`, `oqs/rand.h`, `oqs/sig.h`, and includes all functions marked with `OQS_API`. Incompatible changes to the public API will lead to incrementing $X$ in version $X.Y.Z$. (`oqs/sig.h` will eventually be part of the public API, but is currently under development, and no promises are made about its API stability at present.)
**Algorithm deprecation:** If an algorithm in master branch is found to be insecure or does not advance to the next round of the NIST competition, but is included in version $0.Y.Z$, it will be marked as deprecated using a compile time warning in version $0.(Y+1).Z'$ and removed in version $0.(Y+2).Z''$.
**Algorithm compatibility:** Unlike existing standardization cryptographic algorithms (SHA-2, SHA-3, PKCS\#1v1.5, nistp256, ...), post-quantum algorithms are under active development, and the mathematical algorithm of a cryptographic scheme may change: a particular name (e.g., "FrodoKEM-AES-640") may refer to different mathematical algorithms over time. liboqs may update implementations as algorithms evolve. During the $0.Y.Z$ phase of liboqs, versions $0.Y.Z$ and version $0.(Y+1).Z'$ may not be interoperable. liboqs-reliant applications can check the `alg_version` member of the `OQS_KEM` data structure for each algorithm to obtain an identifier of the algorithm version used in a particular implementation; implementations returning the same `alg_version` for an algorithm will be interoperable.
**API stability:** The public API of liboqs master branch is currently considered to be the functions and macros in `oqs/common.h`, `oqs/config.h`, `oqs/kem.h`, `oqs/rand.h`, `oqs/sig.h`, and includes all functions marked with `OQS_API`. During the $0.Y.Z$ phase of liboqs, incompatible changes to the public API will lead to incrementing $Y$.
Building and running liboqs master branch
-----------------------------------------

49
RELEASE.md Normal file
View File

@ -0,0 +1,49 @@
liboqs master branch version 0.1.0-rc1
======================================
About
-----
The **Open Quantum Safe (OQS) project** has the goal of developing and prototyping quantum-resistant cryptography. More information on OQS can be found on our website: https://openquantumsafe.org/ and on Github at https://github.com/open-quantum-safe/.
**liboqs** is an open source C library for quantum-resistant cryptographic algorithms.
This branch of liboqs (**master branch**) aims to selectively incorporate allegedly quantum-resistant key encapsulation mechanisms and signature schemes, for the purposes of integration into a common API for liboqs-reliant applications. Details about liboqs master branch can be found in [README.md](https://github.com/open-quantum-safe/liboqs/blob/master/README.md). See in particular limitations on intended use and acceptance criteria.
This branch of liboqs can be used with the following Open Quantum Safe application integrations:
- OpenSSL 1.1.1: A prototype integration of liboqs-based key exchange and authentication into TLS 1.3 in our fork of OpenSSL 1.1.1; see the [OQS-OpenSSL-1\_1\_1-stable](https://github.com/open-quantum-safe/openssl/tree/OQS-OpenSSL_1_1_1-stable) branch of our OpenSSL fork's repository.
- OpenSSH 7.7 portable 1: A prototype integration of liboqs-based key exchange into SSH in our fork of OpenSSH 7.7; see the [OQS-master](https://github.com/open-quantum-safe/openssh-portable/tree/OQS-master) branch of our OpenSSH fork's repository.
Release notes
=============
**This is a release candidate for liboqs master, not a final release.**. This release of liboqs master branch was released on TODO. Its release page on GitHub is TODO.
What's New
----------
This is the first release of liboqs master branch.
This branch of liboqs aims to selectively incorporate allegedly quantum-resistant key encapsulation mechanisms and signature schemes, for the purposes of integration into a common API for liboqs-reliant applications. Implementations on this branch must meet certain acceptance criteria as indicated in README.md.
### Key encapsulation mechanisms
The following KEMs are present in this liboqs master release:
- **BIKE**, based on quasi-cyclic syndrome decoding; 9 parameterizations: `BIKE1-L1`, `BIKE1-L3`, `BIKE1-L5`, `BIKE2-L1`, `BIKE2-L3`, `BIKE2-L5`, `BIKE3-L1`, `BIKE3-L3`, `BIKE3-L5`
- **FrodoKEM**, based on learning with errors; 4 parameterizations: `FrodoKEM-640-AES`, `FrodoKEM-640-cSHAKE`, `FrodoKEM-976-AES`, `FrodoKEM-976-cSHAKE`
- **NewHopeNIST**, based on ring learning with errors; 2 parameterizations: `NewHope-512-CCA-KEM`, `NewHope-1024-CCA-KEM`
- **SIKE** and **SIDH**, based on the supersingular isogeny walk problem; 4 parameterizations: `Sike-p503`, `Sike-p751`, `Sidh-p503`, `Sidh-p751`
### Digital signature schemes
The following signature schemes are present in this liboqs master release:
- **Picnic**: based on hash function and key recovery security of lowMC block cipher; 6 parameterizations: `picnic_L1_FS`, `picnic_L1_UR`, `picnic_L3_FS`, `picnic_L3_UR`, `picnic_L5_FS`, `picnic_L5_UR`
- **qTESLA**, based on ring learning with errors; 3 parameterizations: `qTESLA_I`, `qTESLA_III_size`, `qTESLA_III_speed`
Future work
-----------
Releases of liboqs master branch will be made every 2 to 3 months. Details about the algorithm lifecycle of master branch can be found in README.md. Plans for the next release can be found online at https://github.com/open-quantum-safe/liboqs/projects/12.

View File

@ -2,7 +2,7 @@
# Process this file with autoconf to produce a configure script.
# Init
AC_INIT([liboqs], [1.0.0], [])
AC_INIT([liboqs], [0.1.0-rc1], [https://github.com/open-quantum-safe/liboqs/issues], [liboqs-master], [https://openquantumsafe.org/])
AM_INIT_AUTOMAKE([subdir-objects no-dependencies])
AM_PROG_LIBTOOL

View File

@ -6,7 +6,7 @@ Summary
- **Name**: BIKE
- **Algorithm type**: Key Encapsulation Mechanism
- **Main cryptographic assumption**: Quasi Cyclic Syndrom Decoding (QCSD)
- **Main cryptographic assumption**: Quasi-cyclic syndrome decoding (QCSD)
- **NIST submission URL**: https://csrc.nist.gov/CSRC/media/Projects/Post-Quantum-Cryptography/documents/round-1/submissions/BIKE.zip
- **Submitters (to NIST competition)**: Nicolas Aragon, Paulo Barreto, Slim Bettaieb, Loic Bidoux, Olivier Blazy, Jean-Christophe Deneuville, Phillipe Gaborit, Shay Gueron, Tim Guneysu, Carlos Aguilar Melchor, Rafael Misoczki, Edoardo Persichetti, Nicolas Sendrier, Jean-Pierre Tillich, Gilles Zemor
- **Submitters' website**: http://bikesuite.org/
@ -30,17 +30,15 @@ Parameter sets
Implementation
--------------
- **Source of implementation:** This is a reference code (for functionality testing) that is based on the reference code of the Nist submission. This code was modified to use OpenSSL instead of NTL.
- **Source of implementation:** http://bikesuite.org/#implementation
- **Implementation version:** 1.0.0
- **License:** MIT License
- **Language:** C
**Constant-time:** No
**Architectures supported in liboqs nist-branch**: x86, x64
- **Constant-time:** No
- **Architectures supported in liboqs nist-branch**: x86, x64
Additional comments
-------------------
- The original BIKE implementation includes additional optimizations that are not currently being built in liboqs:
- CLMUL
- AES-NI
- AVX2
- AVX512
- LibOQS includes both the reference implementation and the additional implementation of BIKE from http://bikesuite.org/#implementation. The additional implementation is automatically being chosen once compiling LibOQS on a x64 Linux OS with AVX2/512 support.
- The reference code has been modified to use OpenSSL instead of NTL.
- The secret key size might vary between the two implementations.

View File

@ -25,6 +25,7 @@ Implementation
--------------
- **Source of implementation:** https://github.com/Microsoft/PQCrypto-LWEKE
- **Implementation version:** https://github.com/Microsoft/PQCrypto-LWEKE/commit/47da00a91270b6f103232314eef0b891b83bfd3b
- **License:** MIT License
- **Language:** C
- **Constant-time:** Yes

View File

@ -23,6 +23,7 @@ Implementation
--------------
- **Source of implementation:** https://newhopecrypto.org/data/NewHope_2017_12_21.zip
- **Implementation version:** https://newhopecrypto.org/data/NewHope_2017_12_21.zip
- **License:**
- **Language:** C
- **Constant-time:** Yes

View File

@ -22,7 +22,8 @@ Parameter sets
Implementation
--------------
- **Source of implementation:** https://github.com/Microsoft/PQCrypto-SIDH (v3.0)
- **Source of implementation:** https://github.com/Microsoft/PQCrypto-SIDH
- **Implementation version:** v3.0 (https://github.com/Microsoft/PQCrypto-SIDH/tree/77044b76181eb61c744ac8eb7ddc7a8fe72f6919)
- **License:** MIT License
- **Language:** C
- **Constant-time:** Yes

View File

@ -24,6 +24,7 @@ Implementation
--------------
- **Source of implementation:** https://github.com/Microsoft/PQCrypto-SIDH
- **Implmentation version:** v3.0 (https://github.com/Microsoft/PQCrypto-SIDH/tree/77044b76181eb61c744ac8eb7ddc7a8fe72f6919)
- **License:** MIT License
- **Language:** C
- **Constant-time:** Yes

View File

@ -28,6 +28,7 @@ Implementation
--------------
- **Source of implementation:** https://github.com/IAIK/Picnic
- **Implementation version:** https://github.com/IAIK/Picnic/commit/423b5da7036ac3b090d50bdff1e9a8ea34e37d11
- **License:** MIT License
- **Language:** C
- **Constant-time:** Yes

View File

@ -20,14 +20,14 @@ Parameter sets
| qTESLA_I | EUF-CMA | 1 | 1504 | 2112 | 1376 |
| qTESLA_III_size | EUF-CMA | 3 | 2976 | 4160 | 2720 |
| qTESLA_III_speed | EUF-CMA | 3 | 3104 | 4160 | 2848 |
| qTESLA_p_I | EUF-CMA | 1 | 14880 | 5184 | 2848 |
| qTESLA_p_III | EUF-CMA | 3 | 39712 | 12352 | 6176 |
Implementation
--------------
- **Source of implementation:** https://github.com/qtesla/qTesla
- **Implementation version:** https://github.com/qtesla/qTesla/commit/5e921da989b9b44aba95f63d9c28927d518f630c
- **Implmentation version:** TODO
- **License:** public domain
- **Language:** C
- **Constant-time:** Yes

View File

@ -11,6 +11,7 @@ OQS_KEM *OQS_KEM_bike1_l1_new() {
return NULL;
}
kem->method_name = OQS_KEM_alg_bike1_l1;
kem->alg_version = "TODO";
kem->claimed_nist_level = 1;
kem->ind_cca = false;
@ -38,6 +39,7 @@ OQS_KEM *OQS_KEM_bike1_l3_new() {
return NULL;
}
kem->method_name = OQS_KEM_alg_bike1_l3;
kem->alg_version = "TODO";
kem->claimed_nist_level = 3;
kem->ind_cca = false;
@ -65,6 +67,7 @@ OQS_KEM *OQS_KEM_bike1_l5_new() {
return NULL;
}
kem->method_name = OQS_KEM_alg_bike1_l5;
kem->alg_version = "TODO";
kem->claimed_nist_level = 5;
kem->ind_cca = false;
@ -92,6 +95,7 @@ OQS_KEM *OQS_KEM_bike2_l1_new() {
return NULL;
}
kem->method_name = OQS_KEM_alg_bike2_l1;
kem->alg_version = "TODO";
kem->claimed_nist_level = 1;
kem->ind_cca = false;
@ -119,6 +123,7 @@ OQS_KEM *OQS_KEM_bike2_l3_new() {
return NULL;
}
kem->method_name = OQS_KEM_alg_bike2_l3;
kem->alg_version = "TODO";
kem->claimed_nist_level = 3;
kem->ind_cca = false;
@ -146,6 +151,7 @@ OQS_KEM *OQS_KEM_bike2_l5_new() {
return NULL;
}
kem->method_name = OQS_KEM_alg_bike2_l5;
kem->alg_version = "TODO";
kem->claimed_nist_level = 5;
kem->ind_cca = false;
@ -173,6 +179,7 @@ OQS_KEM *OQS_KEM_bike3_l1_new() {
return NULL;
}
kem->method_name = OQS_KEM_alg_bike3_l1;
kem->alg_version = "TODO";
kem->claimed_nist_level = 1;
kem->ind_cca = false;
@ -200,6 +207,7 @@ OQS_KEM *OQS_KEM_bike3_l3_new() {
return NULL;
}
kem->method_name = OQS_KEM_alg_bike3_l3;
kem->alg_version = "TODO";
kem->claimed_nist_level = 3;
kem->ind_cca = false;
@ -227,6 +235,7 @@ OQS_KEM *OQS_KEM_bike3_l5_new() {
return NULL;
}
kem->method_name = OQS_KEM_alg_bike3_l5;
kem->alg_version = "TODO";
kem->claimed_nist_level = 5;
kem->ind_cca = false;

View File

@ -11,6 +11,7 @@ OQS_KEM *OQS_KEM_frodokem_640_aes_new() {
return NULL;
}
kem->method_name = OQS_KEM_alg_frodokem_640_aes;
kem->alg_version = "https://github.com/Microsoft/PQCrypto-LWEKE/commit/47da00a91270b6f103232314eef0b891b83bfd3b";
kem->claimed_nist_level = 1;
kem->ind_cca = true;
@ -38,6 +39,7 @@ OQS_KEM *OQS_KEM_frodokem_976_aes_new() {
return NULL;
}
kem->method_name = OQS_KEM_alg_frodokem_976_aes;
kem->alg_version = "https://github.com/Microsoft/PQCrypto-LWEKE/commit/47da00a91270b6f103232314eef0b891b83bfd3b";
kem->claimed_nist_level = 3;
kem->ind_cca = true;
@ -65,6 +67,7 @@ OQS_KEM *OQS_KEM_frodokem_640_cshake_new() {
return NULL;
}
kem->method_name = OQS_KEM_alg_frodokem_640_cshake;
kem->alg_version = "https://github.com/Microsoft/PQCrypto-LWEKE/commit/47da00a91270b6f103232314eef0b891b83bfd3b";
kem->claimed_nist_level = 1;
kem->ind_cca = true;
@ -92,6 +95,7 @@ OQS_KEM *OQS_KEM_frodokem_976_cshake_new() {
return NULL;
}
kem->method_name = OQS_KEM_alg_frodokem_976_cshake;
kem->alg_version = "https://github.com/Microsoft/PQCrypto-LWEKE/commit/47da00a91270b6f103232314eef0b891b83bfd3b";
kem->claimed_nist_level = 3;
kem->ind_cca = true;

View File

@ -90,6 +90,14 @@ typedef struct OQS_KEM {
/** Printable string representing the name of the key encapsulation mechanism. */
const char *method_name;
/**
* Printable string representing the version of the cryptographic algorithm.
*
* Implementations with the same method_name and same alg_version will be interoperable.
* See README.md for information about algorithm compatibility.
*/
const char *alg_version;
/** The NIST security level (1, 2, 3, 4, 5) claimed in this algorithm's original NIST submission. */
uint8_t claimed_nist_level;

View File

@ -11,6 +11,7 @@ OQS_KEM *OQS_KEM_newhope_512_cca_kem_new() {
return NULL;
}
kem->method_name = OQS_KEM_alg_newhope_512_cca_kem;
kem->alg_version = "https://newhopecrypto.org/data/NewHope_2017_12_21.zip";
kem->claimed_nist_level = 1;
kem->ind_cca = true;
@ -38,6 +39,7 @@ OQS_KEM *OQS_KEM_newhope_1024_cca_kem_new() {
return NULL;
}
kem->method_name = OQS_KEM_alg_newhope_1024_cca_kem;
kem->alg_version = "https://newhopecrypto.org/data/NewHope_2017_12_21.zip";
kem->claimed_nist_level = 5;
kem->ind_cca = true;

View File

@ -13,6 +13,7 @@ OQS_KEM *OQS_KEM_sike_p503_new() {
return NULL;
}
kem->method_name = OQS_KEM_alg_sike_p503;
kem->alg_version = "https://github.com/Microsoft/PQCrypto-SIDH/tree/77044b76181eb61c744ac8eb7ddc7a8fe72f6919";
kem->claimed_nist_level = 1;
kem->ind_cca = true;
@ -52,6 +53,7 @@ OQS_KEM *OQS_KEM_sike_p751_new() {
return NULL;
}
kem->method_name = OQS_KEM_alg_sike_p751;
kem->alg_version = "https://github.com/Microsoft/PQCrypto-SIDH/tree/77044b76181eb61c744ac8eb7ddc7a8fe72f6919";
kem->claimed_nist_level = 3;
kem->ind_cca = true;
@ -91,6 +93,7 @@ OQS_KEM *OQS_KEM_sidh_p503_new() {
return NULL;
}
kem->method_name = OQS_KEM_alg_sidh_p503;
kem->alg_version = "https://github.com/Microsoft/PQCrypto-SIDH/tree/77044b76181eb61c744ac8eb7ddc7a8fe72f6919";
kem->claimed_nist_level = 1;
kem->ind_cca = false;
@ -168,6 +171,7 @@ OQS_KEM *OQS_KEM_sidh_p751_new() {
return NULL;
}
kem->method_name = OQS_KEM_alg_sidh_p751;
kem->alg_version = "https://github.com/Microsoft/PQCrypto-SIDH/tree/77044b76181eb61c744ac8eb7ddc7a8fe72f6919";
kem->claimed_nist_level = 3;
kem->ind_cca = false;

View File

@ -90,6 +90,7 @@ OQS_SIG *OQS_SIG_picnic_L1_FS_new() {
return NULL;
}
sig->method_name = OQS_SIG_alg_picnic_L1_FS;
sig->alg_version = "https://github.com/IAIK/Picnic/commit/423b5da7036ac3b090d50bdff1e9a8ea34e37d11";
sig->claimed_nist_level = 1;
sig->euf_cma = true;
@ -128,6 +129,7 @@ OQS_SIG *OQS_SIG_picnic_L1_UR_new() {
return NULL;
}
sig->method_name = OQS_SIG_alg_picnic_L1_UR;
sig->alg_version = "https://github.com/IAIK/Picnic/commit/423b5da7036ac3b090d50bdff1e9a8ea34e37d11";
sig->claimed_nist_level = 1;
sig->euf_cma = true;
@ -166,6 +168,7 @@ OQS_SIG *OQS_SIG_picnic_L3_FS_new() {
return NULL;
}
sig->method_name = OQS_SIG_alg_picnic_L3_FS;
sig->alg_version = "https://github.com/IAIK/Picnic/commit/423b5da7036ac3b090d50bdff1e9a8ea34e37d11";
sig->claimed_nist_level = 3;
sig->euf_cma = true;
@ -204,6 +207,7 @@ OQS_SIG *OQS_SIG_picnic_L3_UR_new() {
return NULL;
}
sig->method_name = OQS_SIG_alg_picnic_L3_UR;
sig->alg_version = "https://github.com/IAIK/Picnic/commit/423b5da7036ac3b090d50bdff1e9a8ea34e37d11";
sig->claimed_nist_level = 3;
sig->euf_cma = true;
@ -242,6 +246,7 @@ OQS_SIG *OQS_SIG_picnic_L5_FS_new() {
return NULL;
}
sig->method_name = OQS_SIG_alg_picnic_L5_FS;
sig->alg_version = "https://github.com/IAIK/Picnic/commit/423b5da7036ac3b090d50bdff1e9a8ea34e37d11";
sig->claimed_nist_level = 5;
sig->euf_cma = true;
@ -281,6 +286,7 @@ OQS_SIG *OQS_SIG_picnic_L5_UR_new() {
}
sig->method_name = OQS_SIG_alg_picnic_L5_UR;
sig->alg_version = "https://github.com/IAIK/Picnic/commit/423b5da7036ac3b090d50bdff1e9a8ea34e37d11";
sig->claimed_nist_level = 5;
sig->euf_cma = true;

View File

@ -11,6 +11,7 @@ OQS_API OQS_SIG *OQS_SIG_qTESLA_I_new() {
return NULL;
}
sig->method_name = OQS_SIG_alg_qTESLA_I;
sig->alg_version = "https://github.com/qtesla/qTesla/commit/5e921da989b9b44aba95f63d9c28927d518f630c";
sig->claimed_nist_level = 1;
sig->euf_cma = true;
@ -37,6 +38,7 @@ OQS_API OQS_SIG *OQS_SIG_qTESLA_III_size_new() {
return NULL;
}
sig->method_name = OQS_SIG_alg_qTESLA_III_size;
sig->alg_version = "https://github.com/qtesla/qTesla/commit/5e921da989b9b44aba95f63d9c28927d518f630c";
sig->claimed_nist_level = 3;
sig->euf_cma = true;
@ -63,6 +65,7 @@ OQS_API OQS_SIG *OQS_SIG_qTESLA_III_speed_new() {
return NULL;
}
sig->method_name = OQS_SIG_alg_qTESLA_III_speed;
sig->alg_version = "https://github.com/qtesla/qTesla/commit/5e921da989b9b44aba95f63d9c28927d518f630c";
sig->claimed_nist_level = 3;
sig->euf_cma = true;

View File

@ -74,6 +74,14 @@ typedef struct OQS_SIG {
/** Printable string representing the name of the signature scheme. */
const char *method_name;
/**
* Printable string representing the version of the cryptographic algorithm.
*
* Implementations with the same method_name and same alg_version will be interoperable.
* See README.md for information about algorithm compatibility.
*/
const char *alg_version;
/** The NIST security level (1, 2, 3, 4, 5) claimed in this algorithm's original NIST submission. */
uint8_t claimed_nist_level;