mirror of
https://github.com/henrydcase/pqc.git
synced 2024-11-26 17:31:38 +00:00
93 lines
4.1 KiB
Markdown
93 lines
4.1 KiB
Markdown
# 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 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**
|
|
|
|
3. Create a ``META.yml`` file in ``crypto_kem/yourschemename/`` following this template:
|
|
```yaml
|
|
name: Name
|
|
type: <kem|signature>
|
|
claimed-nist-level: <N>
|
|
length-public-key: <N>
|
|
length-ciphertext: <N>
|
|
testvectors-sha256: sha256sum of output of testvectors
|
|
principal-submitter: Eve
|
|
auxiliary-submitters:
|
|
- Alice
|
|
- Bob
|
|
- ...
|
|
implementations:
|
|
- name: clean
|
|
version: <some version indicator>
|
|
```
|
|
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.
|