Contributing Guide

Contributing to OQS-OpenSSL-1_1_1

Adding a key exchange algorithm

The TLS 1.3 key exchange integration is done at the TLS layer (start looking in ssl/statem/extensions_(clnt,srvr).c). It would be nice to integrate into the crypto EVP layer, but is not possible given the asymmetric nature of the KEM API (genkey, encrypt, decrypt) and the lack of role context when the Diffie-Hellman EVP functions are invoked.

We use a templating system to generate code to adds support for key exchange algorithms in OpenSSL. Adding a new key exchange algorithm from liboqs means simply adding algorithm metadata to oqs-template/generate.yml (following the conventions established therein), then running python3 oqs-template/generate.py.

Adding an authentication algorithm

We also use the templating system to generate code that adds support for authentication algorithms in OpenSSL. Adding a new authentication algorithm from liboqs is done as follows:

1. Add the algorithm metadata to oqs-template/generate.yml (following the conventions established therein)
2. Run python3 oqs-template/generate.py
3. Run make generate_crypto_objects to re-generate the objects-related files (obj_dat.h, obj_mac.num, obj_mac.h)

Note that with respect to OID assignment, we prefer the use of the 1.3.9999 space.

Lifecycle

Release cycle: We aim to make releases of OQS-OpenSSL_1_1_1 on a bi-monthly basis, either when there has been a new release of OpenSSL 1.1.1 or when we have made changes to our fork.

See the README.md files of liboqs for information about the algorithm lifecycle within liboqs.

TLS compatibility: The ciphersuite numbers and message formats used for post-quantum and hybrid key exchange and authentication are experimental, and may change between releases of OQS-OpenSSL_1_1_1-stable.

Integration tests

Integration tests are available under the oqs_test directory; see the README.md for details on how to run the tests locally.