From 928b92364e02ac4dd33bc8e91aa35075c8a2ca44 Mon Sep 17 00:00:00 2001 From: Thom Wiggers Date: Wed, 27 Feb 2019 14:15:29 +0100 Subject: [PATCH 1/8] First draft of CONTRIBUTING --- CONTRIBUTING.md | 88 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 1 + 2 files changed, 89 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..5978ae0d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,88 @@ +# Contributing new schemes to PQClean + +## Why contribute to PQClean + +PQClean hopes to provide your scheme to people who want to integrate post-quantum cryptography into their own libraries and applications. +But our extensive testing framework might also help you catch bugs in your implementation, that might have otherwise gone unnoticed. +We run our builds on (emulated) ARMv7, ARMv8, x86 and amd64. +Also, we apply static and dynamic analysis tools. + +## Adding your scheme + +For this text, we will assume that you want to contribute a **kem** to PQClean. +For a signature scheme, these steps are equivalent, but the API is slightly different. +See the section [API][#API] below. + +1. Fork our repository. You will be creating a pull request soon. +**Tip:** Do not wait until you think you have gotten everything perfect, before you open the pull request. +We set up things so Github and the CI environment will give you + +2. Create the following folder structure: `crypto_kem/yourschemename/clean`. +We follow the SUPERCOP layout, so please create a separate folder for each parameter set. +For now, we only accept **pure, portable C code** + +3. Create a ``META.yml`` file in ``crypto_kem/yourschemename/`` following this template: +```yaml +name: Name +type: +claimed-nist-level: +length-public-key: +length-ciphertext: +testvectors-sha256: sha256sum of output of testvectors +principal-submitter: Eve +auxiliary-submitters: + - Alice + - Bob + - ... +implementations: + - name: clean + version: +``` +This file needs to be valid [YAML](https://yaml.org/). + +4. Put your scheme into ``crypto_kem/yourschemename/clean``. + 1. Make sure all symbols are prefixed with ``PQCLEAN_YOURSCHEME_CLEAN_`` + 2. Include ``api.h`` into your scheme with the symbols specified in the section [API][#API]: +5. Create ``Makefile`` and ``Makefile.Microsoft_nmake`` files to compile your scheme as static library. + * We suggest you take these from ``crypto_kem/kyber768/clean`` and modify them to suit your scheme. +6. Add a ``LICENSE`` file to your implementation folder. +7. Commit everything and push it to your fork +8. Open a pull request on our repository and process the feedback given to you by the CI environment. + The pull request will also set up a checklist for you and us to follow. + +## API + +These items should be available in your ``api.h`` file. +Please make sure your ``api.h`` file does not include any other files. + +### KEMs +* ``int PQCLEAN_YOURSCHEME_CLEAN_crypto_kem_keypair(unsigned char *pk, unsigned char *sk);`` +* ``int PQCLEAN_YOURSCHEME_CLEAN_crypto_kem_enc(unsigned char *ct, unsigned char *ss, const unsigned char *pk);`` +* ``int PQCLEAN_YOURSCHEME_CLEAN_crypto_kem_dec(unsigned char *ss, const unsigned char *ct, const unsigned char *sk);`` +* ``define`` macros + * ``CRYPTO_SECRETKEYBYTES`` + * ``CRYPTO_PUBLICKEYBYTES`` + * ``CRYPTO_CIPHERTEXTBYTES`` + * ``CRYPTO_BYTES`` + * ``CRYPTO_ALGNAME`` + +### Signature schemes +* ``int PQCLEAN_YOURSCHEME_CLEAN_crypto_sign_keypair(unsigned char *pk, unsigned char *sk);`` +* ``int PQCLEAN_YOURSCHEME_CLEAN_crypto_sign(unsigned char *sm, unsigned long long *smlen, const unsigned char *msg, unsigned long long len, const unsigned char *sk);`` +* ``int PQCLEAN_YOURSCHEME_CLEAN_crypto_sign_open(unsigned char *m, unsigned long long *mlen, const unsigned char *sm, unsigned long long smlen, const unsigned char *pk);`` +* ``define`` macros + * ``CRYPTO_SECRETKEYBYTES`` + * ``CRYPTO_PUBLICKEYBYTES`` + * ``CRYPTO_BYTES`` + * ``CRYPTO_ALGNAME`` + +#### Return codes +Your schemes should return 0 on success, or a negative value on failure. +Notably, ``crypto_sign_open`` should return ``-1`` if signature verification failed. + +# Contributing to the framework of PQClean + +We also welcome contributions to the testing framework. +Open an issue or pull request on Github and we will review your suggestion. +In general, we are always looking to improve the experience of submitters of schemes and of people consuming the implementations collected by this project. +Please do bear in mind the intentions of this project. diff --git a/README.md b/README.md index 93bfb5e2..9ed821b5 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,7 @@ What PQClean is **not** aiming for is As a first main target, we are collecting C implementations that fulfill the requirements listed below. +Please also review our [guidelines for contributors](CONTRIBUTING.md) if you are interested in adding a scheme to PQClean. ## Requirements on C implementations that are automatically checked From 7d8b12d6bd095102eb53ea867d13c24025f391ad Mon Sep 17 00:00:00 2001 From: Thom Wiggers Date: Wed, 27 Feb 2019 14:19:51 +0100 Subject: [PATCH 2/8] Syntax typos --- CONTRIBUTING.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5978ae0d..af5c426a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,7 +11,7 @@ Also, we apply static and dynamic analysis tools. For this text, we will assume that you want to contribute a **kem** to PQClean. For a signature scheme, these steps are equivalent, but the API is slightly different. -See the section [API][#API] below. +See the section [API](#API) below. 1. Fork our repository. You will be creating a pull request soon. **Tip:** Do not wait until you think you have gotten everything perfect, before you open the pull request. @@ -41,12 +41,16 @@ implementations: This file needs to be valid [YAML](https://yaml.org/). 4. Put your scheme into ``crypto_kem/yourschemename/clean``. - 1. Make sure all symbols are prefixed with ``PQCLEAN_YOURSCHEME_CLEAN_`` - 2. Include ``api.h`` into your scheme with the symbols specified in the section [API][#API]: + 1. Make sure all symbols are prefixed with ``PQCLEAN_YOURSCHEME_CLEAN_`` + 2. Include ``api.h`` into your scheme with the symbols specified in the section [API](#API): + 5. Create ``Makefile`` and ``Makefile.Microsoft_nmake`` files to compile your scheme as static library. - * We suggest you take these from ``crypto_kem/kyber768/clean`` and modify them to suit your scheme. + * We suggest you take these from ``crypto_kem/kyber768/clean`` and modify them to suit your scheme. + 6. Add a ``LICENSE`` file to your implementation folder. + 7. Commit everything and push it to your fork + 8. Open a pull request on our repository and process the feedback given to you by the CI environment. The pull request will also set up a checklist for you and us to follow. From 658b4f044791e84b7b66ce5e6d7555f4ef428508 Mon Sep 17 00:00:00 2001 From: Thom Wiggers Date: Wed, 27 Feb 2019 14:21:08 +0100 Subject: [PATCH 3/8] Fix unfinished sentence [ci skip] --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index af5c426a..0e20f019 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,8 +14,8 @@ For a signature scheme, these steps are equivalent, but the API is slightly diff See the section [API](#API) below. 1. Fork our repository. You will be creating a pull request soon. -**Tip:** Do not wait until you think you have gotten everything perfect, before you open the pull request. -We set up things so Github and the CI environment will give you + * **Tip:** Do not wait until you think you have gotten everything perfect, before you open the pull request. + We set up things so Github and the CI environment will give you feedback and guidance on the steps to follow. 2. Create the following folder structure: `crypto_kem/yourschemename/clean`. We follow the SUPERCOP layout, so please create a separate folder for each parameter set. From cb4eb97bc466393714c5b029326696e9d2baeeaf Mon Sep 17 00:00:00 2001 From: Douglas Stebila Date: Wed, 27 Feb 2019 22:03:41 -0500 Subject: [PATCH 4/8] Markdown formatting changes --- CONTRIBUTING.md | 151 ++++++++++++++++++++++++++---------------------- 1 file changed, 83 insertions(+), 68 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0e20f019..f07658a5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,92 +1,107 @@ -# Contributing new schemes to PQClean +Contributing new schemes to PQClean +=================================== -## Why contribute to PQClean +Why contribute to PQClean +------------------------- -PQClean hopes to provide your scheme to people who want to integrate post-quantum cryptography into their own libraries and applications. -But our extensive testing framework might also help you catch bugs in your implementation, that might have otherwise gone unnoticed. -We run our builds on (emulated) ARMv7, ARMv8, x86 and amd64. -Also, we apply static and dynamic analysis tools. +PQClean hopes to provide your scheme to people who want to integrate post-quantum cryptography into their own libraries and applications. But our extensive testing framework might also help you catch bugs in your implementation, that might have otherwise gone unnoticed. We run our builds on (emulated) ARMv7, ARMv8, x86 and amd64. Also, we apply static and dynamic analysis tools. -## Adding your scheme +Adding your scheme +------------------ -For this text, we will assume that you want to contribute a **kem** to PQClean. -For a signature scheme, these steps are equivalent, but the API is slightly different. +For this text, we will assume that you want to contribute a **key encapsulation mechanism (KEM)** to PQClean. For a signature scheme, these steps are equivalent, but the API is slightly different. See the section [API](#API) below. 1. Fork our repository. You will be creating a pull request soon. - * **Tip:** Do not wait until you think you have gotten everything perfect, before you open the pull request. - We set up things so Github and the CI environment will give you feedback and guidance on the steps to follow. + * **Tip:** Do not wait until you think you have gotten everything perfect, before you open the pull request. We set up things so Github and the CI environment will give you feedback and guidance on the steps to follow. -2. Create the following folder structure: `crypto_kem/yourschemename/clean`. -We follow the SUPERCOP layout, so please create a separate folder for each parameter set. -For now, we only accept **pure, portable C code** +2. Create the following folder structure: `crypto_kem/yourschemename/clean`. We follow the SUPERCOP layout, so please create a separate folder under `crypto_kem` for each parameter set. -3. Create a ``META.yml`` file in ``crypto_kem/yourschemename/`` following this template: -```yaml -name: Name -type: -claimed-nist-level: -length-public-key: -length-ciphertext: -testvectors-sha256: sha256sum of output of testvectors -principal-submitter: Eve -auxiliary-submitters: - - Alice - - Bob - - ... -implementations: - - name: clean - version: -``` -This file needs to be valid [YAML](https://yaml.org/). + For now, we only accept **pure, portable C code**. Our coding conventions impose certain constraints on the C code -- C99 code, fixed sized integer types (e.g., `uint64_t` rather than `unsigned long long`), and more. See README.md for more information. -4. Put your scheme into ``crypto_kem/yourschemename/clean``. - 1. Make sure all symbols are prefixed with ``PQCLEAN_YOURSCHEME_CLEAN_`` - 2. Include ``api.h`` into your scheme with the symbols specified in the section [API](#API): +3. Create a `META.yml` file in `crypto_kem/yourschemename` following this template: -5. Create ``Makefile`` and ``Makefile.Microsoft_nmake`` files to compile your scheme as static library. - * We suggest you take these from ``crypto_kem/kyber768/clean`` and modify them to suit your scheme. + ```yaml + name: Name + type: + claimed-nist-level: + length-public-key: + length-ciphertext: + testvectors-sha256: sha256sum of output of testvectors + principal-submitter: Eve + auxiliary-submitters: + - Alice + - Bob + - ... + implementations: + - name: clean + version: + ``` -6. Add a ``LICENSE`` file to your implementation folder. + This file needs to be valid [YAML](https://yaml.org/). -7. Commit everything and push it to your fork +4. Put your scheme's C source code into `crypto_kem/yourschemename/clean`. -8. Open a pull request on our repository and process the feedback given to you by the CI environment. - The pull request will also set up a checklist for you and us to follow. + 1. Make sure all symbols are prefixed with `PQCLEAN_YOURSCHEME_CLEAN_`. + 2. Include `api.h` into your scheme with the symbols specified in the section [API](#API). -## API +5. Create `Makefile` and `Makefile.Microsoft_nmake` files to compile your scheme as static library. + * We suggest you copy these from `crypto_kem/kyber768/clean` and modify them to suit your scheme. -These items should be available in your ``api.h`` file. -Please make sure your ``api.h`` file does not include any other files. +6. Add a `LICENSE` file to your implementation folder. + +7. Commit everything and push it to your fork. + +8. Open a pull request on our Github repository and process the feedback given to you by the CI environment. The pull request will also set up a checklist for you and us to follow. Feel free to ask us questions via the pull request. + +API +--- + +These items should be available in your `api.h` file. ### KEMs -* ``int PQCLEAN_YOURSCHEME_CLEAN_crypto_kem_keypair(unsigned char *pk, unsigned char *sk);`` -* ``int PQCLEAN_YOURSCHEME_CLEAN_crypto_kem_enc(unsigned char *ct, unsigned char *ss, const unsigned char *pk);`` -* ``int PQCLEAN_YOURSCHEME_CLEAN_crypto_kem_dec(unsigned char *ss, const unsigned char *ct, const unsigned char *sk);`` -* ``define`` macros - * ``CRYPTO_SECRETKEYBYTES`` - * ``CRYPTO_PUBLICKEYBYTES`` - * ``CRYPTO_CIPHERTEXTBYTES`` - * ``CRYPTO_BYTES`` - * ``CRYPTO_ALGNAME`` + +Functions: + +```c +int PQCLEAN_YOURSCHEME_CLEAN_crypto_kem_keypair(unsigned char *pk, unsigned char *sk); +int PQCLEAN_YOURSCHEME_CLEAN_crypto_kem_enc(unsigned char *ct, unsigned char *ss, const unsigned char *pk); +int PQCLEAN_YOURSCHEME_CLEAN_crypto_kem_dec(unsigned char *ss, const unsigned char *ct, const unsigned char *sk); +``` + +`#define` macros: + +* `CRYPTO_SECRETKEYBYTES` +* `CRYPTO_PUBLICKEYBYTES` +* `CRYPTO_CIPHERTEXTBYTES` +* `CRYPTO_BYTES` +* `CRYPTO_ALGNAME` ### Signature schemes -* ``int PQCLEAN_YOURSCHEME_CLEAN_crypto_sign_keypair(unsigned char *pk, unsigned char *sk);`` -* ``int PQCLEAN_YOURSCHEME_CLEAN_crypto_sign(unsigned char *sm, unsigned long long *smlen, const unsigned char *msg, unsigned long long len, const unsigned char *sk);`` -* ``int PQCLEAN_YOURSCHEME_CLEAN_crypto_sign_open(unsigned char *m, unsigned long long *mlen, const unsigned char *sm, unsigned long long smlen, const unsigned char *pk);`` -* ``define`` macros - * ``CRYPTO_SECRETKEYBYTES`` - * ``CRYPTO_PUBLICKEYBYTES`` - * ``CRYPTO_BYTES`` - * ``CRYPTO_ALGNAME`` -#### Return codes +Functions: + +```c +int PQCLEAN_YOURSCHEME_CLEAN_crypto_sign_keypair(unsigned char *pk, unsigned char *sk); +int PQCLEAN_YOURSCHEME_CLEAN_crypto_sign(unsigned char *sm, unsigned long long *smlen, const unsigned char *msg, unsigned long long len, const unsigned char *sk); +int PQCLEAN_YOURSCHEME_CLEAN_crypto_sign_open(unsigned char *m, unsigned long long *mlen, const unsigned char *sm, unsigned long long smlen, const unsigned char *pk); +``` + +`#define` macros: + +* `CRYPTO_SECRETKEYBYTES` +* `CRYPTO_PUBLICKEYBYTES` +* `CRYPTO_BYTES` +* `CRYPTO_ALGNAME` + +Please make sure your `api.h` file does not include any other files. + +### Return codes + Your schemes should return 0 on success, or a negative value on failure. -Notably, ``crypto_sign_open`` should return ``-1`` if signature verification failed. +Notably, `crypto_sign_open` should return `-1` if signature verification failed. -# Contributing to the framework of PQClean +Contributing to the framework of PQClean +======================================== -We also welcome contributions to the testing framework. -Open an issue or pull request on Github and we will review your suggestion. -In general, we are always looking to improve the experience of submitters of schemes and of people consuming the implementations collected by this project. -Please do bear in mind the intentions of this project. +We also welcome contributions to the testing framework. Open an issue or pull request on Github and we will review your suggestion. In general, we are always looking to improve the experience of submitters of schemes and of people consuming the implementations collected by this project. Please do bear in mind the intentions of this project. From e39dec091932b023877d0005dd61dc2665600756 Mon Sep 17 00:00:00 2001 From: Thom Wiggers Date: Thu, 28 Feb 2019 15:13:13 +0100 Subject: [PATCH 5/8] Add powerpc mention and remove intentions statement --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f07658a5..2cf23fb3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,7 @@ Contributing new schemes to PQClean Why contribute to PQClean ------------------------- -PQClean hopes to provide your scheme to people who want to integrate post-quantum cryptography into their own libraries and applications. But our extensive testing framework might also help you catch bugs in your implementation, that might have otherwise gone unnoticed. We run our builds on (emulated) ARMv7, ARMv8, x86 and amd64. Also, we apply static and dynamic analysis tools. +PQClean hopes to provide your scheme to people who want to integrate post-quantum cryptography into their own libraries and applications. But our extensive testing framework might also help you catch bugs in your implementation, that might have otherwise gone unnoticed. We run our builds on (emulated) ARMv7, ARMv8, 32-bit PowerPC, x86 and amd64. Also, we apply static and dynamic analysis tools. Adding your scheme ------------------ @@ -104,4 +104,4 @@ Notably, `crypto_sign_open` should return `-1` if signature verification failed. Contributing to the framework of PQClean ======================================== -We also welcome contributions to the testing framework. Open an issue or pull request on Github and we will review your suggestion. In general, we are always looking to improve the experience of submitters of schemes and of people consuming the implementations collected by this project. Please do bear in mind the intentions of this project. +We also welcome contributions to the testing framework. Open an issue or pull request on Github and we will review your suggestion. In general, we are always looking to improve the experience of submitters of schemes and of people consuming the implementations collected by this project. From 98a6f2cf3803fba2af8068140640378896129d1f Mon Sep 17 00:00:00 2001 From: Thom Wiggers Date: Thu, 28 Feb 2019 17:00:57 +0100 Subject: [PATCH 6/8] Add remark about running astyle to contributing See #60 --- CONTRIBUTING.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2cf23fb3..265c3ef4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -44,6 +44,10 @@ See the section [API](#API) below. 1. Make sure all symbols are prefixed with `PQCLEAN_YOURSCHEME_CLEAN_`. 2. Include `api.h` into your scheme with the symbols specified in the section [API](#API). + 3. We use `astyle` to format code. You may consider running the following command on your submission: + ``` + astyle --project crypto_kem/yourschemename/clean/*.[ch] + ``` 5. Create `Makefile` and `Makefile.Microsoft_nmake` files to compile your scheme as static library. * We suggest you copy these from `crypto_kem/kyber768/clean` and modify them to suit your scheme. From c765e5c3504021ea4096fc3e70fae603f8808f00 Mon Sep 17 00:00:00 2001 From: Thom Wiggers Date: Tue, 5 Mar 2019 13:59:36 +0100 Subject: [PATCH 7/8] Specify crypto API as specified in README This means using uint8_t and adding the detached-signature api functions --- CONTRIBUTING.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 265c3ef4..b8534b3e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -68,9 +68,9 @@ These items should be available in your `api.h` file. Functions: ```c -int PQCLEAN_YOURSCHEME_CLEAN_crypto_kem_keypair(unsigned char *pk, unsigned char *sk); -int PQCLEAN_YOURSCHEME_CLEAN_crypto_kem_enc(unsigned char *ct, unsigned char *ss, const unsigned char *pk); -int PQCLEAN_YOURSCHEME_CLEAN_crypto_kem_dec(unsigned char *ss, const unsigned char *ct, const unsigned char *sk); +int PQCLEAN_YOURSCHEME_CLEAN_crypto_kem_keypair(uint8_t *pk, uint8_t *sk); +int PQCLEAN_YOURSCHEME_CLEAN_crypto_kem_enc(uint8_t *ct, uint8_t *ss, const uint8_t *pk); +int PQCLEAN_YOURSCHEME_CLEAN_crypto_kem_dec(uint8_t *ss, const uint8_t *ct, const uint8_t *sk); ``` `#define` macros: @@ -86,9 +86,11 @@ int PQCLEAN_YOURSCHEME_CLEAN_crypto_kem_dec(unsigned char *ss, const unsigned ch Functions: ```c -int PQCLEAN_YOURSCHEME_CLEAN_crypto_sign_keypair(unsigned char *pk, unsigned char *sk); -int PQCLEAN_YOURSCHEME_CLEAN_crypto_sign(unsigned char *sm, unsigned long long *smlen, const unsigned char *msg, unsigned long long len, const unsigned char *sk); -int PQCLEAN_YOURSCHEME_CLEAN_crypto_sign_open(unsigned char *m, unsigned long long *mlen, const unsigned char *sm, unsigned long long smlen, const unsigned char *pk); +int PQCLEAN_YOURSCHEME_CLEAN_crypto_sign_keypair(uint8_t *pk, uint8_t *sk); +int PQCLEAN_YOURSCHEME_CLEAN_crypto_sign(uint8_t *sm, unsigned long long *smlen, const uint8_t *msg, unsigned long long len, const uint8_t *sk); +int PQCLEAN_YOURSCHEME_CLEAN_crypto_sign_open(uint8_t *m, unsigned long long *mlen, const uint8_t *sm, unsigned long long smlen, const uint8_t *pk); +int PQCLEAN_YOURSCHEME_CLEAN_crypto_sign_signature(uint8_t *sig, size_t *siglen, const uint8_t *m, size_t mlen, const uint8_t *sk); +int PQCLEAN_YOURSCHEME_CLEAN_crypto_sign_verify(const uint8_t *sig, size_t siglen, const uint8_t *m, size_t mlen, const uint8_t *pk); ``` `#define` macros: From 004c82c42ef254f389c6140413de1829be240f0b Mon Sep 17 00:00:00 2001 From: Thom Wiggers Date: Fri, 5 Apr 2019 16:29:21 +0200 Subject: [PATCH 8/8] Namespace constants, clean up C API listings --- CONTRIBUTING.md | 56 +++++++++++++++++++++++++++++++++++-------------- 1 file changed, 40 insertions(+), 16 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b8534b3e..5126659d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,14 +19,17 @@ See the section [API](#API) below. For now, we only accept **pure, portable C code**. Our coding conventions impose certain constraints on the C code -- C99 code, fixed sized integer types (e.g., `uint64_t` rather than `unsigned long long`), and more. See README.md for more information. -3. Create a `META.yml` file in `crypto_kem/yourschemename` following this template: +3. Create a `META.yml` file in `crypto_(kem|sign)/yourschemename` following this template: ```yaml name: Name type: claimed-nist-level: - length-public-key: - length-ciphertext: + length-public-key: # KEM and signature + length-secret-key: # KEM and signature + length-ciphertext: # KEM only + length-sharedsecret: # KEM only + length-signature: # Signature only testvectors-sha256: sha256sum of output of testvectors principal-submitter: Eve auxiliary-submitters: @@ -43,11 +46,12 @@ See the section [API](#API) below. 4. Put your scheme's C source code into `crypto_kem/yourschemename/clean`. 1. Make sure all symbols are prefixed with `PQCLEAN_YOURSCHEME_CLEAN_`. - 2. Include `api.h` into your scheme with the symbols specified in the section [API](#API). + 2. Include `api.h` into your scheme with the symbols specified in the section [API](#API). Make sure it does not include other files. 3. We use `astyle` to format code. You may consider running the following command on your submission: ``` astyle --project crypto_kem/yourschemename/clean/*.[ch] ``` + 4. You may run the tests in the `tests/` folder. See the `README` for how to run the test suite. 5. Create `Makefile` and `Makefile.Microsoft_nmake` files to compile your scheme as static library. * We suggest you copy these from `crypto_kem/kyber768/clean` and modify them to suit your scheme. @@ -68,9 +72,12 @@ These items should be available in your `api.h` file. Functions: ```c -int PQCLEAN_YOURSCHEME_CLEAN_crypto_kem_keypair(uint8_t *pk, uint8_t *sk); -int PQCLEAN_YOURSCHEME_CLEAN_crypto_kem_enc(uint8_t *ct, uint8_t *ss, const uint8_t *pk); -int PQCLEAN_YOURSCHEME_CLEAN_crypto_kem_dec(uint8_t *ss, const uint8_t *ct, const uint8_t *sk); +int PQCLEAN_YOURSCHEME_CLEAN_crypto_kem_keypair( + uint8_t *pk, uint8_t *sk); +int PQCLEAN_YOURSCHEME_CLEAN_crypto_kem_enc( + uint8_t *ct, uint8_t *ss, const uint8_t *pk); +int PQCLEAN_YOURSCHEME_CLEAN_crypto_kem_dec( + uint8_t *ss, const uint8_t *ct, const uint8_t *sk); ``` `#define` macros: @@ -86,19 +93,36 @@ int PQCLEAN_YOURSCHEME_CLEAN_crypto_kem_dec(uint8_t *ss, const uint8_t *ct, cons Functions: ```c -int PQCLEAN_YOURSCHEME_CLEAN_crypto_sign_keypair(uint8_t *pk, uint8_t *sk); -int PQCLEAN_YOURSCHEME_CLEAN_crypto_sign(uint8_t *sm, unsigned long long *smlen, const uint8_t *msg, unsigned long long len, const uint8_t *sk); -int PQCLEAN_YOURSCHEME_CLEAN_crypto_sign_open(uint8_t *m, unsigned long long *mlen, const uint8_t *sm, unsigned long long smlen, const uint8_t *pk); -int PQCLEAN_YOURSCHEME_CLEAN_crypto_sign_signature(uint8_t *sig, size_t *siglen, const uint8_t *m, size_t mlen, const uint8_t *sk); -int PQCLEAN_YOURSCHEME_CLEAN_crypto_sign_verify(const uint8_t *sig, size_t siglen, const uint8_t *m, size_t mlen, const uint8_t *pk); +int PQCLEAN_YOURSCHEME_CLEAN_crypto_sign_keypair( + uint8_t *pk, uint8_t *sk); +int PQCLEAN_YOURSCHEME_CLEAN_crypto_sign( + uint8_t *sm, size_t *smlen, + const uint8_t *msg, size_t len, + const uint8_t *sk); +int PQCLEAN_YOURSCHEME_CLEAN_crypto_sign_open( + uint8_t *m, size_t *mlen, + const uint8_t *sm, size_t smlen, + const uint8_t *pk); +int PQCLEAN_YOURSCHEME_CLEAN_crypto_sign_signature( + uint8_t *sig, size_t *siglen, + const uint8_t *m, size_t mlen, + const uint8_t *sk); +int PQCLEAN_YOURSCHEME_CLEAN_crypto_sign_verify( + const uint8_t *sig, size_t siglen, + const uint8_t *m, size_t mlen, + const uint8_t *pk); ``` `#define` macros: -* `CRYPTO_SECRETKEYBYTES` -* `CRYPTO_PUBLICKEYBYTES` -* `CRYPTO_BYTES` -* `CRYPTO_ALGNAME` +* `PQCLEAN_YOURSCHEME_CLEAN_CRYPTO_SECRETKEYBYTES` +* `PQCLEAN_YOURSCHEME_CLEAN_CRYPTO_PUBLICKEYBYTES` +* `PQCLEAN_YOURSCHEME_CLEAN_CRYPTO_ALGNAME` +* `PQCLEAN_YOURSCHEME_CLEAN_CRYPTO_BYTES` + +for KEMs, additionally define: + +* `PQCLEAN_YOURSCHEME_CLEAN_CRYPTO_CIPHERTEXTBYTES` Please make sure your `api.h` file does not include any other files.