Update INSTALL file regarding PQ

pull/8421/head
Anthony Hu 2025-02-04 13:28:05 -05:00
parent 275becab6f
commit 41d8eabb33
1 changed files with 38 additions and 57 deletions

95
INSTALL
View File

@ -193,35 +193,14 @@
Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat
3) Follow steps in "Unix-based Platforms" above. 3) Follow steps in "Unix-based Platforms" above.
15. Building with liboqs for TLS 1.3 [EXPERIMENTAL] 15. Building Post-Quantum Support for TLS 1.3
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:
$ cd wolfssl $ cd wolfssl
$ ./autogen.sh (Might not be necessary) $ ./autogen.sh (Only necessary if downloaded from github)
$ ./configure --with-liboqs $ ./configure --enable-kyber --enable-dilithium
$ make all $ 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: the end of the output of these commands:
$ ./examples/server/server -? $ ./examples/server/server -?
@ -229,52 +208,53 @@
For a quick start, you can run the client and server like this: For a quick start, you can run the client and server like this:
$ ./examples/server/server -v 4 --pqc P521_KYBER_LEVEL5 $ ./examples/server/server -v 4 --pqc P521_ML_KEM_1024
$ ./examples/client/client -v 4 --pqc P521_KYBER_LEVEL5 $ ./examples/client/client -v 4 --pqc P521_ML_KEM_1024
Look for the following line in the output of the server and client: 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 For authentication, you can generate a certificate chain using the Open
top of the Open Quantum Safe project's fork of OpenSSL. We support Quantum Safe project's OQS Provider with your system's OpenSSL application.
certificates and keys generated by the patched version which is maintained Instructions are maintained in our OSP repo here:
in our OSP repo.
Instructions for obtaining and building our patched version of OQS's fork of
OpenSSL can be found at:
https://github.com/wolfSSL/osp/tree/master/oqs/README.md https://github.com/wolfSSL/osp/tree/master/oqs/README.md
There are scripts for generating FALCON, Dilithium and SPHINCS+ certificate For your convenience, there are also pre-generated ML-DSA certificates and
chains which can be found in the same directory as the `README.md` file in keys.
the `osp` github repo. Please find instructions on how to generate the keys
and certificates in the `README.md` file.
Once the certificates and keys are generated, copy them from the Please find instructions on how to generate the keys and certificates
to the certs directory of wolfssl. Now you can run the server and client in the `README.md` file.
like this:
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 \ $ examples/server/server -v 4 -l TLS_AES_256_GCM_SHA384 \
-A certs/falcon_level5_root_cert.pem \ -A certs/mldsa87_root_cert.pem \
-c certs/falcon_level1_entity_cert.pem \ -c certs/mldsa44_entity_cert.pem \
-k certs/falcon_level1_entity_key.pem \ -k certs/mldsa44_entity_key.pem \
--pqc P521_KYBER_LEVEL5 --pqc P521_ML_KEM_1024
$ examples/client/client -v 4 -l TLS_AES_256_GCM_SHA384 \ $ examples/client/client -v 4 -l TLS_AES_256_GCM_SHA384 \
-A certs/falcon_level1_root_cert.pem \ -A certs/mldsa44_root_cert.pem \
-c certs/falcon_level5_entity_cert.pem \ -c certs/mldsa87_entity_cert.pem \
-k certs/falcon_level5_entity_key.pem \ -k certs/mldsa87_entity_key.pem \
--pqc P521_KYBER_LEVEL5 --pqc P521_ML_KEM_1024
Congratulations! You have just achieved a fully quantum-safe TLS 1.3 Congratulations! You have just achieved a fully quantum-safe TLS 1.3
connection! connection!
The following NIST Competition winning algorithms are supported: The following NIST Competition winning algorithms are supported:
- CRYSTALS-KYBER (KEM) - ML-KEM (CRYSTALS-KYBER) (key encapsulation mechanism)
- Dilithium (signature scheme) - 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) - FALCON (signature scheme)
- SPHINCS+ (signature scheme) - SPHINCS+ (signature scheme)
@ -287,11 +267,12 @@
https://csrc.nist.gov/projects/post-quantum-cryptography/round-3-submissions https://csrc.nist.gov/projects/post-quantum-cryptography/round-3-submissions
NOTE: The quantum-safe algorithms provided by liboqs are unstandardized and NOTE: The quantum-safe algorithms that we have implemented are standardized
experimental. It is highly advised that they NOT be used in production by NIST and our implementations follow these standards. At the
environments. All OIDs and codepoints are temporary and expected to protocol layer, OIDs and codepoints have been proposed in various
change in the future. You should have no expectation of backwards standards organizations but are not yet ratified. OIDs and codepoints
compatibility. 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 16. Building with vcpkg