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 to 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. Moreover, be advised that the templating code sequentially assigns child OIDs, starting at 1, to an algorithm family by first numbering the quantum-safe variant, followed by the variant's hybrid pairings before moving on to the next variant quantum-safe variant. For example: dilithium2, is given the OID 1.3.9999.2.1, p256-dilithium2 the OID 1.3.9999.2.2, rsa3072-dilithium2 the OID 1.3.9999.2.3, followed finally by the assignment of the OID 1.3.9999.2.4 to dilithium4. Note the order of the hybrid algorithms here: if rsa3072 were specified before p256 in oqs-template/generate.yml, rsa3072-dilithium2 would be assigned the OID 1.3.9999.2.2

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.