Merge branch 'master' into more-frodo

This commit is contained in:
Douglas Stebila 2019-04-06 08:51:03 -04:00
commit a296085e57
24 changed files with 366 additions and 17 deletions

View File

@ -4,6 +4,11 @@ version: 2
machine: true
steps:
- checkout
- run:
name: Pull submodules
command: |
git submodule init
git submodule update
- run:
name: Install the emulation handlers
command: docker run --rm --privileged multiarch/qemu-user-static:register --reset
@ -13,6 +18,7 @@ version: 2
docker run -e CI=true --rm -v `pwd`:`pwd` -w `pwd` "pqclean/ci-container:$ARCH" /bin/bash -c "
uname -a &&
export CC=${CC} &&
pip3 install -r requirements.txt &&
cd test && python3 -m nose --rednose --verbose"
.native_job: &nativejob
@ -20,10 +26,16 @@ version: 2
- image: pqclean/ci-container:$ARCH
steps:
- checkout
- run:
name: Pull submodules
command: |
git submodule init
git submodule update
- run:
name: Run tests
command: |
export CC=${CC}
pip3 install -r requirements.txt &&
cd test && python3 -m nose --rednose --verbose

View File

@ -1,5 +1,5 @@
---
Checks: '*,-llvm-header-guard,-hicpp-*,-readability-function-size,-google-readability-todo-,-readability-magic-numbers,-cppcoreguidelines-avoid-magic-numbers,-readability-isolate-declaration'
Checks: '*,-llvm-header-guard,-hicpp-*,-readability-function-size,-google-readability-todo,-readability-magic-numbers,-cppcoreguidelines-avoid-magic-numbers,-readability-isolate-declaration'
WarningsAsErrors: '*'
HeaderFilterRegex: '.*'
AnalyzeTemporaryDtors: false

18
.github/pull_request_template.md vendored Normal file
View File

@ -0,0 +1,18 @@
<!-- This template will help you get your code into PQClean. -->
<!-- Type some lines about your submission -->
#### Manually checked properties
<!-- These checkboxes serve for the maintainers of PQClean to verify your submission. Please do not check them yourself. -->
* [ ] `#ifdef`s only for header encapsulation
* [ ] `api.h` does not include other files
* [ ] No stringification macros
* [ ] Output-parameter pointers in functions are on the left
* [ ] Negative return values on failure of API functions (within restrictions of FO transform).
* [ ] `const` arguments are labeled as `const`
* [ ] variable declarations at the beginning (except in `for (size_t i=...`)
* Optional:
* [ ] All integer types are of fixed size, using `stdint.h` types (including `uint8_t` instead of `unsigned char`)
* [ ] Integers used for indexing are of size `size_t`

3
.gitmodules vendored Normal file
View File

@ -0,0 +1,3 @@
[submodule "test/pycparser"]
path = test/pycparser
url = https://github.com/eliben/pycparser.git

View File

@ -23,6 +23,9 @@ matrix:
- gcc@8
before_install:
- pip3 install -r requirements.txt
- brew link gcc
- export PATH="/usr/local/bin:$PATH"
- ln -s /usr/local/bin/gcc-8 /usr/local/bin/gcc
- gcc --version
script:
- "cd test && python3 -m nose --rednose --verbose"

137
CONTRIBUTING.md Normal file
View File

@ -0,0 +1,137 @@
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, 32-bit PowerPC, 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 **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.
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.
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|sign)/yourschemename` following this template:
```yaml
name: Name
type: <kem|signature>
claimed-nist-level: <N>
length-public-key: <N> # KEM and signature
length-secret-key: <N> # KEM and signature
length-ciphertext: <N> # KEM only
length-shared-secret: <N> # KEM only
length-signature: <N> # Signature only
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'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). 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.
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
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);
```
`#define` macros:
* `CRYPTO_SECRETKEYBYTES`
* `CRYPTO_PUBLICKEYBYTES`
* `CRYPTO_CIPHERTEXTBYTES`
* `CRYPTO_BYTES`
* `CRYPTO_ALGNAME`
### Signature schemes
Functions:
```c
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:
* `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.
### 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.

View File

@ -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
@ -63,15 +64,15 @@ _The checking of items on this list is still being developed. Checked items shou
## Requirements on C implementations that are manually checked
* Makefiles without explicit rules (rely on implicit, built-in rules)
* Minimalist Makefiles
* `#ifdef`s only for header encapsulation
* No stringification macros
* Output-parameter pointers in functions are on the left
* `const` arguments are labeled as `const`
* All exported symbols are namespaced in place
* All integer types are of fixed size, using `stdint.h` types (including `uint8_t` instead of `unsigned char`)
* Integers used for indexing are of size `size_t`
* variable declarations at the beginning (except in `for (size_t i=...`)
* Integer types are of fixed size where relevant, using `stdint.h` types
* Integers used for indexing memory are of size `size_t`
* Variable declarations at the beginning (except in `for (size_t i=...`)
## Clean C implementations currently in PQClean
@ -139,10 +140,16 @@ To do this, make sure the following is installed:
* Python 3.5+
* `nosetests` or `nose2` (either for Python 3)
You will also need to make sure the submodules are initialized by running:
```
git submodule update --init
```
Run the Python-based tests by going into the `test` directory and running `nosetests -v` or `nose2 -B -v`, depending on what you installed.
If you have the `rednose` plugin for `nosetests` installed, run `nosetests --rednose` to get colored output.
You may also run `python <testmodule>` where `<testmodule>` is any of the files starting with `test_` in the `test/` folder.
You may also run `python3 <testmodule>` where `<testmodule>` is any of the files starting with `test_` in the `test/` folder.
[circleci-pqc]: https://circleci.com/gh/PQClean/PQClean/
[travis-pqc]: https://travis-ci.com/PQClean/PQClean/

View File

@ -2,8 +2,10 @@ name: FrodoKEM-640-SHAKE
type: kem
claimed-nist-level: 1
length-public-key: 9616
length-secret-key: 19888
length-ciphertext: 9720
testvectors-sha256: 521ff891de20efe74e6584d09612dae989427ac76261a41630c4e4d6a4fc78a4
length-shared-secret: 16
testvectors-sha256: 8f922de02d41005fcc3c4164b2ab74c4c7b588ed69e34e22607d1ae4ab13d2c5
principal-submitter: Douglas Stebila, University of Waterloo
auxiliary-submitters:
- Erdem Alkim

View File

@ -2,8 +2,10 @@ name: Kyber768
type: kem
claimed-nist-level: 3
length-public-key: 1088
length-secret-key: 2400
length-ciphertext: 1152
testvectors-sha256: 0e002ee528febdab1709f100df79ceb00b31a809e03a4fb84e3a72c39235d372
length-shared-secret: 32
testvectors-sha256: 2f5cf9937959eb4a3bc910f71e830e9e0de029b28093c6192d2c3e915913016f
principal-submitter: Peter Schwabe
auxiliary-submitters:
- Roberto Avanzi

View File

@ -2,8 +2,9 @@ name: Dilithium-III
type: signature
claimed-nist-level: 3
length-public-key: 1472
length-secret-key: 3504
length-signature: 2701
testvectors-sha256: e1852a975842c44a683c914ed131d95bee9b786c36c41e47bb77d7dd3c0c07be
testvectors-sha256: 0d9d7a41b24ab8b250c352fdb50318193f2f66c6c582d7721b785b1a4618b493
principal-submitter: Vadim Lyubashevsky
auxiliary-submitters:
- Léo Ducas

View File

@ -1,3 +1,4 @@
PyYAML
nose
rednose
pycparser

View File

@ -17,7 +17,9 @@ DEST_DIR=../bin
# This -Wall was supported by the European Commission through the ERC Starting Grant 805031 (EPOQUE)
CFLAGS=-Wall -Wextra -Wpedantic -Werror -Wundef -std=c99 -I$(COMMON_DIR) $(EXTRAFLAGS)
all: $(DEST_DIR)/functest_$(SCHEME)_$(IMPLEMENTATION) $(DEST_DIR)/testvectors_$(SCHEME)_$(IMPLEMENTATION)
all: $(DEST_DIR)/functest_$(SCHEME)_$(IMPLEMENTATION) \
$(DEST_DIR)/testvectors_$(SCHEME)_$(IMPLEMENTATION) \
$(DEST_DIR)/printparams_$(SCHEME)_$(IMPLEMENTATION)
.PHONY: build-scheme
build-scheme:
@ -33,6 +35,9 @@ functest: $(DEST_DIR)/functest_$(SCHEME)_$(IMPLEMENTATION)
.PHONY: testvectors
testvectors: $(DEST_DIR)/testvectors_$(SCHEME)_$(IMPLEMENTATION)
.PHONY: printparams
printparams: $(DEST_DIR)/printparams_$(SCHEME)_$(IMPLEMENTATION)
$(DEST_DIR)/test_fips202: common/fips202.c $(COMMON_FILES)
mkdir -p $(DEST_DIR)
$(CC) $(CFLAGS) $< $(COMMON_FILES) -o $@
@ -49,6 +54,10 @@ $(DEST_DIR)/testvectors_$(SCHEME)_$(IMPLEMENTATION): build-scheme crypto_$(TYPE)
mkdir -p $(DEST_DIR)
$(CC) $(CFLAGS) -DPQCLEAN_NAMESPACE=PQCLEAN_$(SCHEME_UPPERCASE)_$(IMPLEMENTATION_UPPERCASE) -I$(SCHEME_DIR) crypto_$(TYPE)/testvectors.c $(COMMON_FILES) $(COMMON_DIR)/notrandombytes.c -o $@ -L$(SCHEME_DIR) -l$(SCHEME)_$(IMPLEMENTATION)
$(DEST_DIR)/printparams_$(SCHEME)_$(IMPLEMENTATION): build-scheme crypto_$(TYPE)/printparams.c
mkdir -p $(DEST_DIR)
$(CC) $(CFLAGS) -DPQCLEAN_NAMESPACE=PQCLEAN_$(SCHEME_UPPERCASE)_$(IMPLEMENTATION_UPPERCASE) -I$(SCHEME_DIR) crypto_$(TYPE)/printparams.c -o $@
.PHONY: clean
clean:
$(RM) $(DEST_DIR)/functest_$(SCHEME)_$(IMPLEMENTATION)

View File

@ -35,6 +35,8 @@ functest: $(DEST_DIR)\functest_$(SCHEME)_$(IMPLEMENTATION).exe
testvectors: $(DEST_DIR)\testvectors_$(SCHEME)_$(IMPLEMENTATION).exe
printparams: $(DEST_DIR)\printparams_$(SCHEME)_$(IMPLEMENTATION).exe
$(DEST_DIR)\functest_$(SCHEME)_$(IMPLEMENTATION).exe: build-scheme $(COMMON_OBJECTS) $(COMMON_DIR)\randombytes.obj
-MKDIR $(DEST_DIR)
-DEL functest.obj
@ -47,7 +49,13 @@ $(DEST_DIR)\testvectors_$(SCHEME)_$(IMPLEMENTATION).exe: build-scheme $(COMMON_O
$(CC) /c crypto_$(TYPE)\testvectors.c $(CFLAGS) /I $(SCHEME_DIR) /DPQCLEAN_NAMESPACE=PQCLEAN_$(SCHEME_UPPERCASE)_$(IMPLEMENTATION_UPPERCASE)
LINK.EXE /STACK:8192000 /OUT:$@ testvectors.obj $(COMMON_OBJECTS_NOPATH) notrandombytes.obj $(SCHEME_DIR)\lib$(SCHEME)_$(IMPLEMENTATION).lib
$(DEST_DIR)\printparams_$(SCHEME)_$(IMPLEMENTATION).exe: crypto_$(TYPE)\printparams.c $(SCHEME_DIR)\api.h
-MKDIR $(DEST_DIR)
-DEL printparams.obj
$(CC) /c crypto_$(TYPE)\printparams.c $(CFLAGS) /I $(SCHEME_DIR) /DPQCLEAN_NAMESPACE=PQCLEAN_$(SCHEME_UPPERCASE)_$(IMPLEMENTATION_UPPERCASE)
LINK.EXE /OUT:$@ printparams.obj
clean:
-DEL functest.obj testvectors.obj
-DEL functest.obj testvectors.obj printparams.obj
-DEL $(COMMON_OBJECTS_NOPATH) randombytes.obj notrandombytes.obj
-DEL $(DEST_DIR)\functest_$(SCHEME)_$(IMPLEMENTATION).exe

View File

@ -5,7 +5,7 @@
#include "api.h"
#include "randombytes.h"
#define NTESTS 10
#define NTESTS 5
const uint8_t canary[8] = {
0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF

View File

@ -0,0 +1,14 @@
#include <stdio.h>
#include "api.h"
#define PASTER(x, y) x##_##y
#define EVALUATOR(x, y) PASTER(x, y)
#define NAMESPACE(fun) EVALUATOR(PQCLEAN_NAMESPACE, fun)
int main() {
printf("{\n");
printf("\t\"CRYPTO_SECRETKEYBYTES\": %u,\n", NAMESPACE(CRYPTO_SECRETKEYBYTES));
printf("\t\"CRYPTO_PUBLICKEYBYTES\": %u,\n", NAMESPACE(CRYPTO_PUBLICKEYBYTES));
printf("\t\"CRYPTO_CIPHERTEXTBYTES\": %u,\n", NAMESPACE(CRYPTO_CIPHERTEXTBYTES));
printf("\t\"CRYPTO_BYTES\": %u\n}\n", NAMESPACE(CRYPTO_BYTES));
}

View File

@ -6,7 +6,7 @@
#include "api.h"
#include "randombytes.h"
#define NTESTS 100
#define NTESTS 5
static void printbytes(const uint8_t *x, size_t xlen) {
size_t i;

View File

@ -6,7 +6,7 @@
#include "api.h"
#include "randombytes.h"
#define NTESTS 15
#define NTESTS 5
#define MLEN 32
const uint8_t canary[8] = {

View File

@ -0,0 +1,13 @@
#include <stdio.h>
#include "api.h"
#define PASTER(x, y) x##_##y
#define EVALUATOR(x, y) PASTER(x, y)
#define NAMESPACE(fun) EVALUATOR(PQCLEAN_NAMESPACE, fun)
int main() {
printf("{\n");
printf("\t\"CRYPTO_SECRETKEYBYTES\": %u,\n", NAMESPACE(CRYPTO_SECRETKEYBYTES));
printf("\t\"CRYPTO_PUBLICKEYBYTES\": %u,\n", NAMESPACE(CRYPTO_PUBLICKEYBYTES));
printf("\t\"CRYPTO_BYTES\": %u\n}\n", NAMESPACE(CRYPTO_BYTES));
}

View File

@ -6,7 +6,6 @@
#include "api.h"
#include "randombytes.h"
#define NTESTS 100
#define MAXMLEN 2048
static void printbytes(const uint8_t *x, size_t xlen) {
@ -43,7 +42,8 @@ int main(void) {
int r;
size_t i, k;
for (i = 0; i < MAXMLEN; i = (i == 0) ? i + 1 : i << 1) {
/* i = 0, 1, 4, 16, 64, 256, 1024 */
for (i = 0; i < MAXMLEN; i = (i == 0) ? i + 1 : i << 2) {
randombytes(mi, i);
crypto_sign_keypair(pk, sk);

View File

@ -86,7 +86,6 @@ def ensure_available(executable):
"""
path = shutil.which(executable)
if path:
print("Found", path)
return path
# Installing clang-tidy on LLVM will be too much of a mess.

1
test/pycparser Submodule

@ -0,0 +1 @@
Subproject commit e1a1d737be66308b633215fa26ac5ed30e890103

67
test/test_char.py Normal file
View File

@ -0,0 +1,67 @@
"""
Checks that the implementation does not make use of the `char` type.
This is ambiguous; compilers can freely choose `signed` or `unsigned` char.
"""
import pqclean
import pycparser
import os
import helpers
def test_char():
for scheme in pqclean.Scheme.all_schemes():
for implementation in scheme.implementations:
yield check_char, implementation
def walk_tree(ast):
if type(ast) is pycparser.c_ast.IdentifierType:
if ast.names == ['char']:
yield ast
for (_, child) in ast.children():
yield from walk_tree(child) # recursively yield prohibited nodes
@helpers.skip_windows()
def check_char(implementation):
errors = []
for fname in os.listdir(implementation.path()):
if not fname.endswith(".c"):
continue
tdir, _ = os.path.split(os.path.realpath(__file__))
ast = pycparser.parse_file(
os.path.join(implementation.path(), fname),
use_cpp=True,
cpp_path='cc', # not all platforms link cpp correctly; cc -E works
cpp_args=[
'-E',
'-std=c99',
'-nostdinc', # pycparser cannot deal with e.g. __attribute__
'-I{}'.format(os.path.join(tdir, "../common")),
# necessary to mock e.g. <stdint.h>
'-I{}'.format(
os.path.join(tdir, 'pycparser/utils/fake_libc_include')),
]
)
for node in walk_tree(ast):
# flatten nodes to a string to easily enforce uniqueness
err = "\n at {c.file}:{c.line}:{c.column}".format(c=node.coord)
if err not in errors:
errors.append(err)
if errors:
raise AssertionError(
"Prohibited use of char without explicit signed/unsigned" +
"".join(errors)
)
if __name__ == '__main__':
try:
import nose2
nose2.main()
except ImportError:
import nose
nose.runmodule()

View File

@ -42,6 +42,7 @@ EXPECTED_FIELDS = {
'type': {'type': str},
'claimed-nist-level': {'type': int, 'min': 1, 'max': 5},
'length-public-key': {'type': int, 'min': 1},
'length-secret-key': {'type': int, 'min': 1},
'testvectors-sha256': {'type': str, 'length': 64},
'principal-submitter': {'type': str},
'auxiliary-submitters': {'type': list, 'elements': {'type': str}},
@ -77,6 +78,7 @@ EXPECTED_FIELDS = {
KEM_FIELDS = {
'length-ciphertext': {'type': int, 'min': 1},
'length-shared-secret': {'type': int, 'min': 1},
}
SIGNATURE_FIELDS = {

View File

@ -0,0 +1,50 @@
import json
import os
import pqclean
import helpers
def test_metadata_sizes():
for scheme in pqclean.Scheme.all_schemes():
for implementation in scheme.implementations:
yield check_metadata_sizes, implementation
def check_metadata_sizes(implementation):
metadata = implementation.scheme.metadata()
helpers.make('printparams',
TYPE=implementation.scheme.type,
SCHEME=implementation.scheme.name,
IMPLEMENTATION=implementation.name,
working_dir=os.path.join('..', 'test'))
out = helpers.run_subprocess(
[os.path.join('..', 'bin', 'printparams_{}_{}{}'.format(
implementation.scheme.name,
implementation.name,
'.exe' if os.name == 'nt' else ''
))],
os.path.join('..', 'bin'),
).replace('\r', '')
parsed = json.loads(out)
assert parsed['CRYPTO_SECRETKEYBYTES'] == metadata['length-secret-key']
assert parsed['CRYPTO_PUBLICKEYBYTES'] == metadata['length-public-key']
if implementation.scheme.type == 'kem':
assert (
parsed['CRYPTO_CIPHERTEXTBYTES'] == metadata['length-ciphertext'])
assert parsed['CRYPTO_BYTES'] == metadata['length-shared-secret']
else:
assert parsed['CRYPTO_BYTES'] == metadata['length-signature']
if __name__ == '__main__':
try:
import nose2
nose2.main()
except ImportError:
import nose
nose.runmodule()