From 41d8eabb331b20a01cafa89664f3c5868668acaa Mon Sep 17 00:00:00 2001 From: Anthony Hu Date: Tue, 4 Feb 2025 13:28:05 -0500 Subject: [PATCH] Update INSTALL file regarding PQ --- INSTALL | 95 +++++++++++++++++++++++---------------------------------- 1 file changed, 38 insertions(+), 57 deletions(-) diff --git a/INSTALL b/INSTALL index 6ac6330043..4176fb063a 100644 --- a/INSTALL +++ b/INSTALL @@ -193,35 +193,14 @@ Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat 3) Follow steps in "Unix-based Platforms" above. -15. Building with liboqs for TLS 1.3 [EXPERIMENTAL] - In order be able to use liboqs, you must have it built and installed on your - system. We support liboqs at a specific git commit. - - NOTE: Even if you have already installed liboqs, you need to follow these - steps to install liboqs again as we support sphincs variants that are - disabled by default in OQS's fork of OpenSSL. - - Here are instructions for obtaining and building liboqs: - - $ mkdir ~/oqs - $ cd ~/oqs - $ git clone --single-branch https://github.com/open-quantum-safe/liboqs.git - $ cd liboqs/ - $ git checkout 0.8.0 - $ mkdir build - $ cd build - $ cmake -DOQS_USE_OPENSSL=0 .. - $ make all - $ sudo make install - - And then for building wolfssl, the following is sufficient: +15. Building Post-Quantum Support for TLS 1.3 $ cd wolfssl - $ ./autogen.sh (Might not be necessary) - $ ./configure --with-liboqs + $ ./autogen.sh (Only necessary if downloaded from github) + $ ./configure --enable-kyber --enable-dilithium $ make all - Execute the following to see the liboqs-related options for KEM groups near + Execute the following to see the options for KEM groups near the end of the output of these commands: $ ./examples/server/server -? @@ -229,52 +208,53 @@ For a quick start, you can run the client and server like this: - $ ./examples/server/server -v 4 --pqc P521_KYBER_LEVEL5 - $ ./examples/client/client -v 4 --pqc P521_KYBER_LEVEL5 + $ ./examples/server/server -v 4 --pqc P521_ML_KEM_1024 + $ ./examples/client/client -v 4 --pqc P521_ML_KEM_1024 Look for the following line in the output of the server and client: ``` - Using Post-Quantum KEM: P521_KYBER_LEVEL5 + Using Post-Quantum KEM: P521_ML_KEM_1024 ``` - For authentication, you can generate a certificate chain using a patch on - top of the Open Quantum Safe project's fork of OpenSSL. We support - certificates and keys generated by the patched version which is maintained - in our OSP repo. - - Instructions for obtaining and building our patched version of OQS's fork of - OpenSSL can be found at: + For authentication, you can generate a certificate chain using the Open + Quantum Safe project's OQS Provider with your system's OpenSSL application. + Instructions are maintained in our OSP repo here: https://github.com/wolfSSL/osp/tree/master/oqs/README.md - There are scripts for generating FALCON, Dilithium and SPHINCS+ certificate - chains which can be found in the same directory as the `README.md` file in - the `osp` github repo. Please find instructions on how to generate the keys - and certificates in the `README.md` file. + For your convenience, there are also pre-generated ML-DSA certificates and + keys. - Once the certificates and keys are generated, copy them from the - to the certs directory of wolfssl. Now you can run the server and client - like this: + Please find instructions on how to generate the keys and certificates + in the `README.md` file. + + Copy the certificates and keys into the certs directory of wolfssl. Now you + can run the server and client like this: $ examples/server/server -v 4 -l TLS_AES_256_GCM_SHA384 \ - -A certs/falcon_level5_root_cert.pem \ - -c certs/falcon_level1_entity_cert.pem \ - -k certs/falcon_level1_entity_key.pem \ - --pqc P521_KYBER_LEVEL5 + -A certs/mldsa87_root_cert.pem \ + -c certs/mldsa44_entity_cert.pem \ + -k certs/mldsa44_entity_key.pem \ + --pqc P521_ML_KEM_1024 $ examples/client/client -v 4 -l TLS_AES_256_GCM_SHA384 \ - -A certs/falcon_level1_root_cert.pem \ - -c certs/falcon_level5_entity_cert.pem \ - -k certs/falcon_level5_entity_key.pem \ - --pqc P521_KYBER_LEVEL5 + -A certs/mldsa44_root_cert.pem \ + -c certs/mldsa87_entity_cert.pem \ + -k certs/mldsa87_entity_key.pem \ + --pqc P521_ML_KEM_1024 Congratulations! You have just achieved a fully quantum-safe TLS 1.3 connection! The following NIST Competition winning algorithms are supported: - - CRYSTALS-KYBER (KEM) - - Dilithium (signature scheme) + - ML-KEM (CRYSTALS-KYBER) (key encapsulation mechanism) + - ML-DSA (CRYSTALS-Dilithium) (signature scheme) + + The following NIST Competition winning algorithms were supported by our + liboqs integration. Support for their standardized specifications will + return when we write our own implementations. + - FALCON (signature scheme) - SPHINCS+ (signature scheme) @@ -287,11 +267,12 @@ https://csrc.nist.gov/projects/post-quantum-cryptography/round-3-submissions - NOTE: The quantum-safe algorithms provided by liboqs are unstandardized and - experimental. It is highly advised that they NOT be used in production - environments. All OIDs and codepoints are temporary and expected to - change in the future. You should have no expectation of backwards - compatibility. + NOTE: The quantum-safe algorithms that we have implemented are standardized + by NIST and our implementations follow these standards. At the + protocol layer, OIDs and codepoints have been proposed in various + standards organizations but are not yet ratified. OIDs and codepoints + are temporary and expected to change in the future. You should have no + expectation of backwards compatibility at the protocol layer. 16. Building with vcpkg