kris/pqc
1
1
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Markdown formatting changes

Browse Source
This commit is contained in:
Douglas Stebila 2019-02-27 22:03:41 -05:00 committed by Thom Wiggers
parent 658b4f0447
commit cb4eb97bc4
No known key found for this signature in database
GPG Key ID: 001BB0A7CE26E363
1 changed files with 83 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

141
CONTRIBUTING.md
View File

@ -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. 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.
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 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.
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. 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. * **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.
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`. 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.
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: 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.
```yaml
name: Name 3. Create a `META.yml` file in `crypto_kem/yourschemename` following this template:
type: <kem|signature>
claimed-nist-level: <N> ```yaml
length-public-key: <N> name: Name
length-ciphertext: <N> type: <kem|signature>
testvectors-sha256: sha256sum of output of testvectors claimed-nist-level: <N>
principal-submitter: Eve length-public-key: <N>
auxiliary-submitters: length-ciphertext: <N>
testvectors-sha256: sha256sum of output of testvectors
principal-submitter: Eve
auxiliary-submitters:
- Alice - Alice
- Bob - Bob
- ... - ...
implementations: implementations:
- name: clean - name: clean
version: <some version indicator> version: <some version indicator>
``` ```
This file needs to be valid [YAML](https://yaml.org/).
4. Put your scheme into ``crypto_kem/yourschemename/clean``. This file needs to be valid [YAML](https://yaml.org/).
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. 4. Put your scheme's C source code into `crypto_kem/yourschemename/clean`.
* 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. 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).
7. Commit everything and push it to your fork 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.
8. Open a pull request on our repository and process the feedback given to you by the CI environment. 6. Add a `LICENSE` file to your implementation folder.
The pull request will also set up a checklist for you and us to follow.
## API 7. Commit everything and push it to your fork.
These items should be available in your ``api.h`` file. 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.
Please make sure your ``api.h`` file does not include any other files.
API
---
These items should be available in your `api.h` file.
### KEMs ### 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);`` Functions:
* ``int PQCLEAN_YOURSCHEME_CLEAN_crypto_kem_dec(unsigned char *ss, const unsigned char *ct, const unsigned char *sk);``
* ``define`` macros ```c
* ``CRYPTO_SECRETKEYBYTES`` int PQCLEAN_YOURSCHEME_CLEAN_crypto_kem_keypair(unsigned char *pk, unsigned char *sk);
* ``CRYPTO_PUBLICKEYBYTES`` int PQCLEAN_YOURSCHEME_CLEAN_crypto_kem_enc(unsigned char *ct, unsigned char *ss, const unsigned char *pk);
* ``CRYPTO_CIPHERTEXTBYTES`` int PQCLEAN_YOURSCHEME_CLEAN_crypto_kem_dec(unsigned char *ss, const unsigned char *ct, const unsigned char *sk);
* ``CRYPTO_BYTES`` ```
* ``CRYPTO_ALGNAME``
`#define` macros:
* `CRYPTO_SECRETKEYBYTES`
* `CRYPTO_PUBLICKEYBYTES`
* `CRYPTO_CIPHERTEXTBYTES`
* `CRYPTO_BYTES`
* `CRYPTO_ALGNAME`
### Signature schemes ### 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. 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. 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.
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.