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