From 37c066f08e257f66714e4fd1eabebc2bf611c341 Mon Sep 17 00:00:00 2001 From: Adam Overa Date: Wed, 2 Oct 2024 15:12:31 -0400 Subject: [PATCH 1/6] Host a Website with X25519Kyber768Draft00 Key Exchange Support --- .../index.md | 453 ++++++++++++++++++ 1 file changed, 453 insertions(+) create mode 100644 docs/guides/security/encryption/host-website-with-x25519kyber768draft00-key-exchange-support/index.md diff --git a/docs/guides/security/encryption/host-website-with-x25519kyber768draft00-key-exchange-support/index.md b/docs/guides/security/encryption/host-website-with-x25519kyber768draft00-key-exchange-support/index.md new file mode 100644 index 0000000000..96848f3559 --- /dev/null +++ b/docs/guides/security/encryption/host-website-with-x25519kyber768draft00-key-exchange-support/index.md @@ -0,0 +1,453 @@ +--- +slug: host-website-with-x25519kyber768draft00-key-exchange-support +title: "Host Website With X25519kyber768draft00 Key Exchange Support" +description: "Two to three sentences describing your guide." +og_description: "Optional two to three sentences describing your guide when shared on social media. If omitted, the `description` parameter is used within social links." +authors: ["Linode"] +contributors: ["Linode"] +published: 2024-09-16 +keywords: ['list','of','keywords','and key phrases'] +license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' +external_resources: +- '[Link Title 1](http://www.example.com)' +- '[Link Title 2](http://www.example.net)' +--- + +DRAFT DEBIAN 11 Set up a Web Server and Host a Website on Linode that supports the X25519Kyber768Draft00 Key Exchange in TLS 1.3 (Post-quantum cryptography) + +NIST recently [released](https://www.nist.gov/news-events/news/2024/08/nist-releases-first-3-finalized-post-quantum-encryption-standards) the first finalized Post-Quantum Encryption Standards to withstand the attacks of a quantum computer. This includes the Module-Lattice-Based Key-Encapsulation Mechanism Standard (ML-KEM, defined in [FIPS-203](https://csrc.nist.gov/pubs/fips/203/final), which has already been implemented in the industry using an early [pre-standardization draft](https://datatracker.ietf.org/doc/draft-tls-westerbaan-xyber768d00/) for use with TLS. Deploying this algorithm for use by your web server currently still requires a few additional steps, and may differ depending on which version of OpenSSL the OS comes with. In this document, we show you how to build OpenSSL 3.x and the Open Quantum Safe provider on a Debian 11 system; for instructions on an Ubuntu 24.04 LTS system, please see [this document](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558967). Stay tuned for other post-quantum cryptography updates in the near future! + +Before You Begin, make sure that you are familiar with: +- [Guides - Create a Compute Instance](https://www.linode.com/docs/products/compute/compute-instances/guides/create/) +- [Guides - Setting Up and Securing a Compute Instance](https://www.linode.com/docs/products/compute/compute-instances/guides/set-up-and-secure/?tabs=macos%2Cmost-distributions%2Cubuntu-debian-kali-linux) +- [Understanding TLS Certificates and Connections](https://www.linode.com/docs/guides/what-is-a-tls-certificate/) + +# Step-by-step guide + +- [Create a new Linode](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-CreateanewLinode) +- [Install the necessary components ](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Installthenecessarycomponents) + - [Install dependencies and system packages needed for further installation](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Installdependenciesandsystempackagesneededforfurtherinstallation) + - [Install OpenSSL from sources](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-InstallOpenSSLfromsources) + - [Fetch OpenSSL sources](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-FetchOpenSSLsources) + - [Verify the code signature](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Verifythecodesignature) + - [Build a OpenSSL](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-BuildaOpenSSLtalk-287041talk-287058) + - [Install the oqs-provider](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Installtheoqs-provider) + - [Install dependencies and clone the repository](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Installdependenciesandclonetherepository) + - [Build oqs-provider](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Buildoqs-providertalk-287030talk-287040talk-287049) + - [Open the config file and add the following lines at the end:](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Opentheconfigfileandaddthefollowinglinesattheend:) + - [Checking provider version information](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Checkingproviderversioninformation) + - [Install Nginx from sources](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-InstallNginxfromsources) + - [Fetch Nginx sources](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-FetchNginxsources) + - [Verify the code signature](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Verifythecodesignature.1) + - [Install the required dependencies](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Installtherequireddependencies) + - [Build nginx](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Buildnginx) + - [Configure Nginx](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-ConfigureNginx) + - [Create a configuration file for the server in the /opt/nginx/conf.d/ directory, such as pqc.conf:](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Createaconfigurationfilefortheserverinthe/opt/nginx/conf.d/directory,suchaspqc.conf:talk-287045) + - [Create a system service file for Nginx to automatically manage the server:](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-CreateasystemservicefileforNginxtoautomaticallymanagetheserver:talk-287048talk-287051) + - [Start the service](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Starttheservice) +- [Check if the post quantum algorithms are used by nginx](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Checkifthepostquantumalgorithmsareusedbynginxtalk-287052) +- [Related links](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Relatedlinks) + +## Create a new Linode + +Begin by [creating a new Linode](https://techdocs.akamai.com/cloud-computing/docs/create-a-compute-instance). In this example, we are using an Ubuntu Debian 11 instance. + +## Install the necessary components + +### Install dependencies and system packages needed for further installation + +```command +sudo apt update +``` + +```command +sudo apt install -y make +``` + +```command +sudo apt install -y gcc +``` + +- **make** is a build automation tool used to compile and link programs from source code. It reads instructions from a Makefile, which defines how to compile and build the project. +- **gcc** (GNU Compiler Collection) provides a compiler that converts source code written in languages like C, C++, and others into executable programs. It is essential for building software from source code. + +### Install OpenSSL from sources + +#### Fetch OpenSSL sources + +The default version of OpenSSL shipped with Debian 11 is 1.1.1w. The Open Quantum Safe OpenSSL provider requires OpenSSL >= 3.x, so we will build a newer version from source. First, we'll download the sources and accompanying signature: + +```command +wget https://github.com/openssl/openssl/releases/download/openssl-3.3.2/openssl-3.3.2.tar.gz + +```command +wget https://github.com/openssl/openssl/releases/download/openssl-3.3.2/openssl-3.3.2.tar.gz.asc +``` + +#### Verify the code signature + +Next, we want to verify the signature. For this, we will need to install **gnupg**, import the public OpenSSL signing key, and verify the signature: + +```command +sudo apt -y install gnupg +``` + +```command +gpg --search-keys openssl@openssl.org +``` + +```output +gpg: data source: https://keys.openpgp.org:443 +(1) OpenSSL + 4096 bit RSA key 216094DFD0CB81EF, created: 2024-04-08 +Keys 1-1 of 1 for "openssl@openssl.org". Enter number(s), N)ext, or Q)uit > 1 +gpg: key 216094DFD0CB81EF: public key "OpenSSL " imported +gpg: Total number processed: 1 +gpg: imported: 1 +``` + +```command +gpg --fingerprint openssl@openssl.org +``` + +```output +pub rsa4096 2024-04-08 [SC] [expires: 2026-04-08] + BA54 73A2 B058 7B07 FB27 CF2D 2160 94DF D0CB 81EF +uid [ unknown] OpenSSL +``` + +```command +gpg --verify openssl-3.3.2.tar.gz.asc openssl-3.3.2.tar.gz +``` + +```output +gpg: Signature made Tue Sep 3 08:46:51 2024 EDT +gpg: using RSA key BA5473A2B0587B07FB27CF2D216094DFD0CB81EF +gpg: Good signature from "OpenSSL " [ultimate] +``` + +{{< note >}} +If you do not have a trust path to the OpenSSL key or have not explicitly trusted it, you may also see a warning message. That does not impact the validity of the signature. +{{< /note >}} + +#### Build a OpenSSL + +```command +tar zxf openssl-3.3.2.tar.gz +``` + +```command +cd openssl-3.3.2 +``` + +```command +./Configure --prefix=/opt '-Wl,-rpath,$(LIBRPATH)' +``` + +```command +make +``` + +```command +sudo make install +``` + +To verify that OpenSSL has been correctly installed and is the version you intended to install: + +```command +/opt/bin/openssl version +``` + +At this point, you probably want to add `/opt/bin` to your `PATH` environment variable in your shell startup file (e.g., `~/.bashrc` or system wide in `/etc/profile`). + +### Install the oqs-provider + +#### Install dependencies and clone the repository + +```command +sudo apt install -y git cmake ninja-build +``` + +```command +git clone https://github.com/open-quantum-safe/oqs-provider.git +``` + +```command +cd oqs-provider +``` + +- **cmake**: A cross-platform build system generator that helps automate the compilation and build process for software projects. +- **ninja-build**: A fast and lightweight build system designed to run builds in parallel, speeding up the compilation of large projects. + +#### Build oqs-provider + +```command +env OPENSSL_ROOT=/opt CMAKE_PARAMS="-DOPENSSL_CRYPTO_LIBRARY=/opt/lib64/libcrypto.so" bash scripts/fullbuild.sh +``` + +```command +sudo cmake --install _build +``` + +```command +export PATH=/opt/bin:$PATH +``` + +```command +scripts/runtests.sh +``` + +#### Open the config file and add the following lines at the end: + +```file {title="/opt/ssl/openssl.cnf"} +# PQC via OpenQuantumSafe +[provider_sect] +default = default_sect +oqsprovider = oqsprovider_sect + +[default_sect] +activate = 1 + +[oqsprovider_sect] +activate = 1 +``` + +{{< note >}} +In this case, we are editing the file /opt/ssl/openssl.cnf, not the configuration file for the system OpenSSL! +{{< /note >}} + +#### Checking provider version information + +```command +openssl list -providers +``` + +```output +Providers: + default + name: OpenSSL Default Provider + version: 3.3.2 + status: active + oqsprovider + name: OpenSSL OQS Provider + version: 0.6.2-dev + status: active +``` + +### Install Nginx from sources + +The version of Nginx built for the Debian 11 packages use OpenSSL version 1.1.1w, so wee need to build Nginx with OpenSSL 3.x ourselves. + +#### Fetch Nginx sources + +```command +wget https://nginx.org/download/nginx-1.26.2.tar.gz +``` + +```command +wget https://nginx.org/download/nginx-1.26.2.tar.gz.asc +``` + +#### Verify the code signature + +Nginx signs its releases with an individual developer's key instead of a package signing key. If you encounter issues verifying a release, additional signing keys may be required. You can find these keys at [https://nginx.org/en/pgp_keys.html](https://nginx.org/en/pgp_keys.html). + +```command +wget https://nginx.org/keys/pluknet.key +``` + +```command +gpg --import pluknet.key +``` + +```command +gpg --verify nginx-1.26.2.tar.gz.asc nginx-1.26.2.tar.gz +``` + +```output +gpg: Signature made Tue Aug 13 08:48:05 2024 EDT +gpg: using RSA key D6786CE303D9A9022998DC6CC8464D549AF75C0A +gpg: issuer "s.kandaurov@f5.com" +gpg: Good signature from "Sergey Kandaurov " [unknown] +gpg: aka "Sergey Kandaurov " [unknown] +gpg: WARNING: The key's User ID is not certified with a trusted signature! +gpg: There is no indication that the signature belongs to the owner. +Primary key fingerprint: D678 6CE3 03D9 A902 2998 DC6C C846 4D54 9AF7 5C0A +``` + +#### Install the required dependencies + +```command +sudo apt install -y zlib1g-dev +``` + +```command +sudo apt install -y libpcre3 libpcre3-dev +``` + +- **zlib1g-dev**: Provides the development files for `zlib`, a compression library used by Nginx to handle compressed content (like gzip) and perform efficient data compression and decompression. +- **libpcre3 and libpcre3-dev**: Provide the PCRE (Perl Compatible Regular Expressions) library and its development files, which Nginx uses for regular expression support, such as in location matching and URL rewriting. + +#### Build nginx + +In this example, we're using the same configuration parameters as used by the binary package, except for our destination prefix. This allows us to retain feature parity and integrate the service with our usual system scripts. The last three options passed to the `configure` script shown here are needed to use the OpenSSL version we built above. + +```command +tar zxf nginx-1.26.2.tar.gz +``` + +```command +cd nginx-1.26.2 +``` + +```command +./configure --with-cc-opt='-g -O2 -fstack-protector-strong -Wformat -Werror=format-security -fPIC -Wdate-time -D_FORTIFY_SOURCE=2' \ + --with-ld-opt='-Wl,-z,relro -Wl,-z,now -fPIC' \ + --prefix=/opt \ + --conf-path=/opt/nginx/nginx.conf \ + --http-log-path=/var/log/nginx/access.log \ + --error-log-path=/var/log/nginx/error.log \ + --lock-path=/var/lock/nginx.lock \ + --pid-path=/run/nginx.pid \ + --modules-path=/opt/lib/nginx/modules \ + --http-client-body-temp-path=/var/lib/nginx/body \ + --http-fastcgi-temp-path=/var/lib/nginx/fastcgi \ + --http-proxy-temp-path=/var/lib/nginx/proxy \ + --http-scgi-temp-path=/var/lib/nginx/scgi \ + --http-uwsgi-temp-path=/var/lib/nginx/uwsgi \ + --with-compat \ + --with-debug \ + --with-http_ssl_module \ + --with-http_stub_status_module \ + --with-http_realip_module \ + --with-http_auth_request_module \ + --with-http_v2_module \ + --with-http_dav_module \ + --with-http_slice_module \ + --with-threads \ + --with-http_addition_module \ + --with-http_gunzip_module \ + --with-http_gzip_static_module \ + --with-http_sub_module \ + --with-pcre \ + --with-openssl-opt=enable-tls1_3 \ + --with-ld-opt="-L/opt/lib64 -Wl,-rpath,/opt/lib64" \ + --with-cc-opt="-I/opt/include" +[...] +``` + +```command +make +``` + +```command +sudo make install +``` + +```command +sudo mkdir /var/lib/nginx +``` + +```command +sudo mkdir /opt/nginx/conf.d +``` + +#### Configure Nginx + +After building, add a line to the main Nginx configuration file to include configuration files in the /opt/nginx/nginx.conf directory: + +```file {title="/opt/nginx/nginx.conf"} +user www-data; #add this to the top of the file + +http { + ... + # Include additional configuration files + include /opt/nginx/conf.d/pqc.conf; +} +``` + +#### Create a configuration file for the server in the /opt/nginx/conf.d/ directory, such as pqc.conf: + +```file {title="/opt/nginx/conf.d/pqc.conf"} +server { + listen 443 ssl; + listen [::]:443 ssl; + server_name example.com www.example.com; + + root /var/www/example.com; + index index.html index.php; + + ssl_certificate /opt/certs/example.com.crt; + ssl_certificate_key /opt/certs/example.com.key; + + ssl_protocols TLSv1.3; + ssl_prefer_server_ciphers on; + ssl_ecdh_curve x25519_kyber768:p384_kyber768:x25519:secp384r1:x448:secp256r1:secp521r1; + + location / { + try_files $uri $uri/ =404; + } +} +``` + +{{< note type="warning" >}} +**Remember!** +**Don't forget to add certificates to enable TLS!** Ensure that you include the necessary certificates, even if they are self-signed, to enable proper TLS/SSL functionality. Without certificates, you won’t be able to establish a secure HTTPS connection. + +If you want to use automatic certificate renewal with Let's Encrypt, follow [Use Certbot to Enable HTTPS with NGINX on Ubuntu](https://www.linode.com/docs/guides/enabling-https-using-certbot-with-nginx-on-ubuntu/) to properly configure the Nginx server. If u want to use self-signed certificate, follow this guide: [Enable TLS/SSL for HTTPS](https://www.linode.com/docs/guides/getting-started-with-nginx-part-3-enable-tls-for-https/), or you can easily create certificates using the following command: + +```command +sudo mkdir /opt/certs +``` + +```command +'sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /opt/certs/pqc.com.key -out /opt/certs/pqc.com.crt' +``` + +{{< note >}} +Note: a self-signed certificate is only suitable for testing or debugging purposes! +{{< /note >}} +{{< /note >}} + +#### Create a system service file for Nginx to automatically manage the server: + +```file {title="/etc/systemd/system/nginx.service"} +[Unit] +Description=The NGINX HTTP and reverse proxy server +After=network.target remote-fs.target nss-lookup.target + +[Service] +Type=forking +PIDFile=/run/nginx.pid +ExecStartPre=/opt/sbin/nginx -t +ExecStart=/opt/sbin/nginx +ExecReload=/opt/sbin/nginx -s reload +ExecStop=/opt/sbin/nginx -s stop +PrivateTmp=true + +[Install] +WantedBy=multi-user.target +``` + +#### Start the service + +```command +sudo service nginx start +``` + +## Check if the post quantum algorithms are used by nginx + +The easiest and quickest way to test the algorithms used by nginx in our custom installation here is to run the openssl command shown below: + +```command +openssl s_client -groups x25519_kyber768 -connect localhost:443 +``` + +For additional methods, see our [Ubuntu-PQC guide](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558967). + +## Related links +[DRAFT UBUNTU Set up a Web Server and Host a Website on Linode that supports the X25519Kyber768Draft00 Key Exchange in TLS 1.3 (Post-quantum cryptography)](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558967) +[https://openquantumsafe.org/](https://openquantumsafe.org/liboqs/) +[https://openssl-library.org/](https://openssl-library.org/) +[https://pq.cloudflareresearch.com](https://pq.cloudflareresearch.com/) +[https://github.com/open-quantum-safe/oqs-provider](https://github.com/open-quantum-safe/oqs-provider) \ No newline at end of file From 2d4d2e5c23f2f2ad0b7643a2bb2804cde9085b69 Mon Sep 17 00:00:00 2001 From: Adam Overa Date: Fri, 4 Oct 2024 12:27:45 -0400 Subject: [PATCH 2/6] Tech Edit 1 --- .../index.md | 760 +++++++++++------- 1 file changed, 450 insertions(+), 310 deletions(-) diff --git a/docs/guides/security/encryption/host-website-with-x25519kyber768draft00-key-exchange-support/index.md b/docs/guides/security/encryption/host-website-with-x25519kyber768draft00-key-exchange-support/index.md index 96848f3559..487e3cb298 100644 --- a/docs/guides/security/encryption/host-website-with-x25519kyber768draft00-key-exchange-support/index.md +++ b/docs/guides/security/encryption/host-website-with-x25519kyber768draft00-key-exchange-support/index.md @@ -1,307 +1,416 @@ --- slug: host-website-with-x25519kyber768draft00-key-exchange-support -title: "Host Website With X25519kyber768draft00 Key Exchange Support" -description: "Two to three sentences describing your guide." -og_description: "Optional two to three sentences describing your guide when shared on social media. If omitted, the `description` parameter is used within social links." +title: "Debian 11 Web Hosting with Post-Quantum Cryptography: X25519Kyber768Draft00 and TLS 1.3" +description: "Learn how to set up a Debian 11 Nginx web server with support for the post-quantum cryptography X25519Kyber768Draft00 key exchange in TLS 1.3." authors: ["Linode"] contributors: ["Linode"] published: 2024-09-16 -keywords: ['list','of','keywords','and key phrases'] +keywords: ['X25519Kyber768Draft00','post-quantum cryptography','tls 1.3','cybersecurity','debian 11','key exhange','OpenSSL','encryption','secure website'] license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' external_resources: -- '[Link Title 1](http://www.example.com)' -- '[Link Title 2](http://www.example.net)' +- '[DRAFT UBUNTU Set up a Web Server and Host a Website on Linode that supports the X25519Kyber768Draft00 Key Exchange in TLS 1.3 (Post-quantum cryptography)](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558967)' +- '[Open Quantum Safe](https://openquantumsafe.org/liboqs/)' +- '[OpenSSL Library](https://openssl-library.org/)' +- '[Cloudfare Research: Post-Quantum Key Agreement](https://pq.cloudflareresearch.com/)' +- '[GitHub: Open Quantum Safe oqs-provider](https://github.com/open-quantum-safe/oqs-provider)' --- -DRAFT DEBIAN 11 Set up a Web Server and Host a Website on Linode that supports the X25519Kyber768Draft00 Key Exchange in TLS 1.3 (Post-quantum cryptography) - -NIST recently [released](https://www.nist.gov/news-events/news/2024/08/nist-releases-first-3-finalized-post-quantum-encryption-standards) the first finalized Post-Quantum Encryption Standards to withstand the attacks of a quantum computer. This includes the Module-Lattice-Based Key-Encapsulation Mechanism Standard (ML-KEM, defined in [FIPS-203](https://csrc.nist.gov/pubs/fips/203/final), which has already been implemented in the industry using an early [pre-standardization draft](https://datatracker.ietf.org/doc/draft-tls-westerbaan-xyber768d00/) for use with TLS. Deploying this algorithm for use by your web server currently still requires a few additional steps, and may differ depending on which version of OpenSSL the OS comes with. In this document, we show you how to build OpenSSL 3.x and the Open Quantum Safe provider on a Debian 11 system; for instructions on an Ubuntu 24.04 LTS system, please see [this document](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558967). Stay tuned for other post-quantum cryptography updates in the near future! - -Before You Begin, make sure that you are familiar with: -- [Guides - Create a Compute Instance](https://www.linode.com/docs/products/compute/compute-instances/guides/create/) -- [Guides - Setting Up and Securing a Compute Instance](https://www.linode.com/docs/products/compute/compute-instances/guides/set-up-and-secure/?tabs=macos%2Cmost-distributions%2Cubuntu-debian-kali-linux) -- [Understanding TLS Certificates and Connections](https://www.linode.com/docs/guides/what-is-a-tls-certificate/) - -# Step-by-step guide - -- [Create a new Linode](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-CreateanewLinode) -- [Install the necessary components ](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Installthenecessarycomponents) - - [Install dependencies and system packages needed for further installation](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Installdependenciesandsystempackagesneededforfurtherinstallation) - - [Install OpenSSL from sources](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-InstallOpenSSLfromsources) - - [Fetch OpenSSL sources](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-FetchOpenSSLsources) - - [Verify the code signature](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Verifythecodesignature) - - [Build a OpenSSL](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-BuildaOpenSSLtalk-287041talk-287058) - - [Install the oqs-provider](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Installtheoqs-provider) - - [Install dependencies and clone the repository](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Installdependenciesandclonetherepository) - - [Build oqs-provider](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Buildoqs-providertalk-287030talk-287040talk-287049) - - [Open the config file and add the following lines at the end:](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Opentheconfigfileandaddthefollowinglinesattheend:) - - [Checking provider version information](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Checkingproviderversioninformation) - - [Install Nginx from sources](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-InstallNginxfromsources) - - [Fetch Nginx sources](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-FetchNginxsources) - - [Verify the code signature](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Verifythecodesignature.1) - - [Install the required dependencies](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Installtherequireddependencies) - - [Build nginx](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Buildnginx) - - [Configure Nginx](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-ConfigureNginx) - - [Create a configuration file for the server in the /opt/nginx/conf.d/ directory, such as pqc.conf:](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Createaconfigurationfilefortheserverinthe/opt/nginx/conf.d/directory,suchaspqc.conf:talk-287045) - - [Create a system service file for Nginx to automatically manage the server:](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-CreateasystemservicefileforNginxtoautomaticallymanagetheserver:talk-287048talk-287051) - - [Start the service](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Starttheservice) -- [Check if the post quantum algorithms are used by nginx](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Checkifthepostquantumalgorithmsareusedbynginxtalk-287052) -- [Related links](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558981#DRAFTDEBIAN11SetupaWebServerandHostaWebsiteonLinodethatsupportstheX25519Kyber768Draft00KeyExchangeinTLS1.3(Postquantumcryptography)-Relatedlinks) - -## Create a new Linode - -Begin by [creating a new Linode](https://techdocs.akamai.com/cloud-computing/docs/create-a-compute-instance). In this example, we are using an Ubuntu Debian 11 instance. - -## Install the necessary components - -### Install dependencies and system packages needed for further installation +The National Institute of Standards and Technology (NIST) recently [released](https://www.nist.gov/news-events/news/2024/08/nist-releases-first-3-finalized-post-quantum-encryption-standards) its first finalized Post-Quantum Encryption Standards to protect against quantum computer attacks. This includes the Module-Lattice-based Key-Encapsulation Mechanism standard (ML-KEM, defined in [FIPS-203](https://csrc.nist.gov/pubs/fips/203/final). It is already being implemented in the industry using an early [pre-standardization draft](https://datatracker.ietf.org/doc/draft-tls-westerbaan-xyber768d00/) for use with TLS. -```command -sudo apt update -``` +Deploying this algorithm for your web server currently requires some additional steps. The process may vary depending on your operating system's version of OpenSSL. This guide shows you how to build OpenSSL 3.x and the Open Quantum Safe (OQS) provider on Debian 11. For instructions on Ubuntu 24.04 LTS, please see [this document](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558967). -```command -sudo apt install -y make -``` +## Before You Begin -```command -sudo apt install -y gcc -``` +1. If you do not already have a virtual machine to use, create a Compute Instance with at least 4 GB of memory using Debian 11. See our [Getting Started with Linode](/docs/products/platform/get-started/) and [Creating a Compute Instance](/docs/products/compute/compute-instances/guides/create/) guides. -- **make** is a build automation tool used to compile and link programs from source code. It reads instructions from a Makefile, which defines how to compile and build the project. -- **gcc** (GNU Compiler Collection) provides a compiler that converts source code written in languages like C, C++, and others into executable programs. It is essential for building software from source code. +1. Follow our [Setting Up and Securing a Compute Instance](/docs/products/compute/compute-instances/guides/set-up-and-secure/) guide to update your system. You may also wish to set the timezone, configure your hostname, create a limited user account, and harden SSH access. -### Install OpenSSL from sources +1. Read our [Understanding TLS Certificates and Connections](/docs/guides/what-is-a-tls-certificate/) to ensure that you're familiar with the basics of TLS encryption. -#### Fetch OpenSSL sources +{{< note >}} +This guide is written for a non-root user. Commands that require elevated privileges are prefixed with `sudo`. If you’re not familiar with the `sudo` command, see the [Users and Groups](/docs/guides/linux-users-and-groups/) guide. +{{< /note >}} -The default version of OpenSSL shipped with Debian 11 is 1.1.1w. The Open Quantum Safe OpenSSL provider requires OpenSSL >= 3.x, so we will build a newer version from source. First, we'll download the sources and accompanying signature: +### Install Dependencies -```command -wget https://github.com/openssl/openssl/releases/download/openssl-3.3.2/openssl-3.3.2.tar.gz +Once your Debian 11 compute instance is set up and secured, install the dependencies and system packages needed to build OpenSSL and the OQS provider. -```command -wget https://github.com/openssl/openssl/releases/download/openssl-3.3.2/openssl-3.3.2.tar.gz.asc -``` +1. Update your package list to ensure you download the latest available versions: -#### Verify the code signature + ```command + sudo apt update + ``` -Next, we want to verify the signature. For this, we will need to install **gnupg**, import the public OpenSSL signing key, and verify the signature: +1. Install `make`, a build automation tool used to compile and link programs from source code. It reads instructions from a Makefile, which defines how to compile and build the software: -```command -sudo apt -y install gnupg -``` + ```command + sudo apt install -y make + ``` -```command -gpg --search-keys openssl@openssl.org -``` +1. Install `gcc` (GNU Compiler Collection), which compiles source code written in languages like C and C++ into executable programs. It is essential for building OpenSSL and other software from source code: -```output -gpg: data source: https://keys.openpgp.org:443 -(1) OpenSSL - 4096 bit RSA key 216094DFD0CB81EF, created: 2024-04-08 -Keys 1-1 of 1 for "openssl@openssl.org". Enter number(s), N)ext, or Q)uit > 1 -gpg: key 216094DFD0CB81EF: public key "OpenSSL " imported -gpg: Total number processed: 1 -gpg: imported: 1 -``` + ```command + sudo apt install -y gcc + ``` -```command -gpg --fingerprint openssl@openssl.org -``` +## Install OpenSSL from Source -```output -pub rsa4096 2024-04-08 [SC] [expires: 2026-04-08] - BA54 73A2 B058 7B07 FB27 CF2D 2160 94DF D0CB 81EF -uid [ unknown] OpenSSL -``` +Debian 11 comes with OpenSSL version 1.1.1w by default, but the OQS provider requires OpenSSL 3.x. Therefore, you need to build a newer version from source. -```command -gpg --verify openssl-3.3.2.tar.gz.asc openssl-3.3.2.tar.gz -``` +1. Download the OpenSSL source code: -```output -gpg: Signature made Tue Sep 3 08:46:51 2024 EDT -gpg: using RSA key BA5473A2B0587B07FB27CF2D216094DFD0CB81EF -gpg: Good signature from "OpenSSL " [ultimate] -``` + ```command + wget https://github.com/openssl/openssl/releases/download/openssl-3.3.2/openssl-3.3.2.tar.gz + ``` -{{< note >}} -If you do not have a trust path to the OpenSSL key or have not explicitly trusted it, you may also see a warning message. That does not impact the validity of the signature. -{{< /note >}} +1. Download the corresponding signature file: -#### Build a OpenSSL + ```command + wget https://github.com/openssl/openssl/releases/download/openssl-3.3.2/openssl-3.3.2.tar.gz.asc + ``` -```command -tar zxf openssl-3.3.2.tar.gz -``` +### Verify the OpenSSL Code Signature -```command -cd openssl-3.3.2 -``` +Before proceeding with the installation, verify the integrity and authenticity of the downloaded files using GnuPG (`gnupg`). -```command -./Configure --prefix=/opt '-Wl,-rpath,$(LIBRPATH)' -``` +1. First, install `gnupg`: -```command -make -``` + ```command + sudo apt -y install gnupg + ``` -```command -sudo make install -``` +1. Next, import the public OpenSSL signing key: -To verify that OpenSSL has been correctly installed and is the version you intended to install: + ```command + gpg --search-keys openssl@openssl.org + ``` -```command -/opt/bin/openssl version -``` + When prompted, press the 1 key followed by ENTER to choose the key from `openssl@openssl.org`: -At this point, you probably want to add `/opt/bin` to your `PATH` environment variable in your shell startup file (e.g., `~/.bashrc` or system wide in `/etc/profile`). + ```output + gpg: data source: https://keys.openpgp.org:443 + (1) OpenSSL + 4096 bit RSA key 216094DFD0CB81EF, created: 2024-04-08 + Keys 1-1 of 1 for "openssl@openssl.org". Enter number(s), N)ext, or Q)uit > 1 + ``` -### Install the oqs-provider + Afterward, you should see output similar to the following: -#### Install dependencies and clone the repository + ```output + gpg: key 216094DFD0CB81EF: public key "OpenSSL " imported + gpg: Total number processed: 1 + gpg: imported: 1 + ``` -```command -sudo apt install -y git cmake ninja-build -``` +1. Verify the fingerprint pf the imported key to ensure it matches OpenSSL's official key: -```command -git clone https://github.com/open-quantum-safe/oqs-provider.git -``` + ```command + gpg --fingerprint openssl@openssl.org + ``` -```command -cd oqs-provider -``` + You should see output similar to the following: -- **cmake**: A cross-platform build system generator that helps automate the compilation and build process for software projects. -- **ninja-build**: A fast and lightweight build system designed to run builds in parallel, speeding up the compilation of large projects. + ```output + pub rsa4096 2024-04-08 [SC] [expires: 2026-04-08] + BA54 73A2 B058 7B07 FB27 CF2D 2160 94DF D0CB 81EF + uid [ unknown] OpenSSL + ``` -#### Build oqs-provider +1. Finally, verify the OpenSSL source file against its signature: -```command -env OPENSSL_ROOT=/opt CMAKE_PARAMS="-DOPENSSL_CRYPTO_LIBRARY=/opt/lib64/libcrypto.so" bash scripts/fullbuild.sh -``` + ```command + gpg --verify openssl-3.3.2.tar.gz.asc openssl-3.3.2.tar.gz + ``` -```command -sudo cmake --install _build -``` + You should see a confirmation similar to the output below: -```command -export PATH=/opt/bin:$PATH -``` + ```output + gpg: Signature made Tue Sep 3 08:46:51 2024 EDT + gpg: using RSA key BA5473A2B0587B07FB27CF2D216094DFD0CB81EF + gpg: Good signature from "OpenSSL " [ultimate] + ``` -```command -scripts/runtests.sh -``` + {{< note >}} + If you see a warning message about not having a trusted path to the OpenSSL key, it does not impact the validity of the signature. The warning message appears because the OpenSSL signing key has not yet been marked as "trusted" in your GnuPG keyring. + {{< /note >}} -#### Open the config file and add the following lines at the end: +### Build OpenSSL -```file {title="/opt/ssl/openssl.cnf"} -# PQC via OpenQuantumSafe -[provider_sect] -default = default_sect -oqsprovider = oqsprovider_sect +After verifying the source code, the next step is to build OpenSSL form source. -[default_sect] -activate = 1 +1. Extract the downloaded OpenSSL archive: -[oqsprovider_sect] -activate = 1 -``` + ```command + tar zxf openssl-3.3.2.tar.gz + ``` + +1. Change into the extracted OpenSSL source directory: + + ```command + cd openssl-3.3.2 + ``` + +1. Configure the OpenSSL build, specifying the installation path (`/opt` in this case) and setting the appropriate runtime library search path: + + ```command + ./Configure --prefix=/opt '-Wl,-rpath,$(LIBRPATH)' + ``` + +1. Use `make` to compile the OpenSSL source code: + + ```command + make + ``` + + {{< note >}} + This process may take a few minutes depending on your system. + {{< /note >}} + +1. Install the compiled OpenSSL files to the specified location: + + ```command + sudo make install + ``` + + {{< note >}} + This process may take a few minutes depending on your system. + {{< /note >}} + +1. Verify that OpenSSL is correctly installed and that the correct version is active: + + ```command + /opt/bin/openssl version + ``` + + This should return the version number of the OpenSSL build: + + ```output + OpenSSL 3.3.2 + ``` {{< note >}} -In this case, we are editing the file /opt/ssl/openssl.cnf, not the configuration file for the system OpenSSL! +At this point, you probably want to add `/opt/bin` to your `PATH` environment variable. + +1. Open your `~/.bashrc` file in a command line text editor such as `nano`: + + ```command + nano ~/.bashrc + ``` + + Append the following line to the end of the file: + + ```file {title="~/.bashrc"} + export PATH=/opt/bin:$PATH + ``` + + When done, press CTRL+X, followed by Y then Enter to save the file and exit `nano`. + +1. Apply the changes: + + ```command + source ~/.bashrc + ``` {{< /note >}} -#### Checking provider version information +## Install `oqs-provider` -```command -openssl list -providers -``` +### Install Dependencies and Clone the `oqs-provider` Repository -```output -Providers: - default - name: OpenSSL Default Provider - version: 3.3.2 - status: active - oqsprovider - name: OpenSSL OQS Provider - version: 0.6.2-dev - status: active -``` +A couple of required dependencies must be installed prior to `oqs-provider`: -### Install Nginx from sources +- `cmake`: A cross-platform build system generator that helps automate the compilation and build process for software projects. +- `ninja-build`: A build system designed to run builds in parallel, which reduces the compilation time of large projects. -The version of Nginx built for the Debian 11 packages use OpenSSL version 1.1.1w, so wee need to build Nginx with OpenSSL 3.x ourselves. +1. Install the required dependencies, along with `git`: -#### Fetch Nginx sources + ```command + sudo apt install -y git cmake ninja-build + ``` -```command -wget https://nginx.org/download/nginx-1.26.2.tar.gz -``` +1. Use `git` to clone the `oqs-provider` repository from GitHub: -```command -wget https://nginx.org/download/nginx-1.26.2.tar.gz.asc -``` + ```command + git clone https://github.com/open-quantum-safe/oqs-provider.git + ``` -#### Verify the code signature +1. Change into the `oqs-provider` directory: -Nginx signs its releases with an individual developer's key instead of a package signing key. If you encounter issues verifying a release, additional signing keys may be required. You can find these keys at [https://nginx.org/en/pgp_keys.html](https://nginx.org/en/pgp_keys.html). + ```command + cd oqs-provider + ``` -```command -wget https://nginx.org/keys/pluknet.key -``` +### Build `oqs-provider` -```command -gpg --import pluknet.key -``` +1. Temporarily add `/opt/bin` to your `PATH` environment variable if not already: -```command -gpg --verify nginx-1.26.2.tar.gz.asc nginx-1.26.2.tar.gz -``` + ```command + export PATH=/opt/bin:$PATH + ``` -```output -gpg: Signature made Tue Aug 13 08:48:05 2024 EDT -gpg: using RSA key D6786CE303D9A9022998DC6CC8464D549AF75C0A -gpg: issuer "s.kandaurov@f5.com" -gpg: Good signature from "Sergey Kandaurov " [unknown] -gpg: aka "Sergey Kandaurov " [unknown] -gpg: WARNING: The key's User ID is not certified with a trusted signature! -gpg: There is no indication that the signature belongs to the owner. -Primary key fingerprint: D678 6CE3 03D9 A902 2998 DC6C C846 4D54 9AF7 5C0A -``` +1. Set the OpenSSL root directory and build the `oqs-provider` using the provided script: -#### Install the required dependencies + ```command + env OPENSSL_ROOT=/opt CMAKE_PARAMS="-DOPENSSL_CRYPTO_LIBRARY=/opt/lib64/libcrypto.so" bash scripts/fullbuild.sh + ``` -```command -sudo apt install -y zlib1g-dev -``` + {{< note >}} + This process may take a few minutes depending on your system. + {{< /note >}} -```command -sudo apt install -y libpcre3 libpcre3-dev -``` +1. Use `cmake` to install the compiled `oqs-provider`: -- **zlib1g-dev**: Provides the development files for `zlib`, a compression library used by Nginx to handle compressed content (like gzip) and perform efficient data compression and decompression. -- **libpcre3 and libpcre3-dev**: Provide the PCRE (Perl Compatible Regular Expressions) library and its development files, which Nginx uses for regular expression support, such as in location matching and URL rewriting. + ```command + sudo cmake --install _build + ``` -#### Build nginx +1. Run the test suite to verify the `oqs-provider` build: -In this example, we're using the same configuration parameters as used by the binary package, except for our destination prefix. This allows us to retain feature parity and integrate the service with our usual system scripts. The last three options passed to the `configure` script shown here are needed to use the OpenSSL version we built above. + ```command + scripts/runtests.sh + ``` -```command -tar zxf nginx-1.26.2.tar.gz -``` +### Configure OpenSSL to Use the OQS Provider -```command -cd nginx-1.26.2 -``` +1. Use a command line text editor such as `nano` to edit the OpenSSL configuration file: -```command -./configure --with-cc-opt='-g -O2 -fstack-protector-strong -Wformat -Werror=format-security -fPIC -Wdate-time -D_FORTIFY_SOURCE=2' \ + ```command + sudo nano /opt/ssl/openssl.cnf + ``` + + Add the following lines at the end: + + ```file {title="/opt/ssl/openssl.cnf"} + # PQC via OpenQuantumSafe + [provider_sect] + default = default_sect + oqsprovider = oqsprovider_sect + + [default_sect] + activate = 1 + + [oqsprovider_sect] + activate = 1 + ``` + + {{< note >}} + In this case, you are editing the `/opt/ssl/openssl.cnf file, not the configuration file for the system OpenSSL! + {{< /note >}} + + When done, press CTRL+X, followed by Y then Enter to save the file and exit `nano`. + +### Check Provider Version Information + +1. List the active OpenSSL providers to verify the installation: + + ```command + openssl list -providers + ``` + + You should see output similar to the following: + + ```output + Providers: + default + name: OpenSSL Default Provider + version: 3.3.2 + status: active + oqsprovider + name: OpenSSL OQS Provider + version: 0.6.2-dev + status: active + ``` + +## Install Nginx from Source + +The version of Nginx available for Debian 11 uses OpenSSL version 1.1.1w. In order to use OpenSSL 3.x, you must build Nginx from source. + +### Fetch Nginx Source + +1. Use `wget` to download the Nginx source files: + + ```command + wget https://nginx.org/download/nginx-1.26.2.tar.gz + ``` + +1. Also download the corresponding signature for verification: + + ```command + wget https://nginx.org/download/nginx-1.26.2.tar.gz.asc + ``` + +### Verify the Signature + +1. Download the public key: + + ```command + wget https://nginx.org/keys/pluknet.key + ``` + +1. Import the key: + + ```command + gpg --import pluknet.key + ``` + +1. Verify the signature: + + ```command + gpg --verify nginx-1.26.2.tar.gz.asc nginx-1.26.2.tar.gz + ``` + + You should see output similar to the below if verification succeeds: + + ```output + gpg: Signature made Tue Aug 13 08:48:05 2024 EDT + gpg: using RSA key D6786CE303D9A9022998DC6CC8464D549AF75C0A + gpg: issuer "s.kandaurov@f5.com" + gpg: Good signature from "Sergey Kandaurov " [unknown] + gpg: aka "Sergey Kandaurov " [unknown] + gpg: WARNING: The key's User ID is not certified with a trusted signature! + gpg: There is no indication that the signature belongs to the owner. + Primary key fingerprint: D678 6CE3 03D9 A902 2998 DC6C C846 4D54 9AF7 5C0A + ``` + + {{< note >}} + Nginx uses individual developer keys to sign its releases, so don't be alarmed if you see unfamiliar names during verification. If verification fails, additional signing keys can be found at [https://nginx.org/en/pgp_keys.html](https://nginx.org/en/pgp_keys.html). + {{< /note >}} + +### Install Dependencies + +A couple of libraries are required before building Nginx: + +1. Install `zlib1g-dev`, a compression library for handling compressed content: + + ```command + sudo apt install -y zlib1g-dev + ``` + +1. Install `libcre3` and `libcre3-dev` to support regular expressions, often used for URL matching: + + ```command + sudo apt install -y libpcre3 libpcre3-dev + ``` + +### Build Nginx + +Except for the destination prefix, this example uses the same configuration parameters as the binary package. This is to retain feature parity and integrate with system scripts. The last three options passed to the `configure` script are necessary to use the OpenSSL version built earlier. + +1. Extract the source: + + ```command + tar zxf nginx-1.26.2.tar.gz + ``` + +1. Change into the extracted source directory: + + ```command + cd nginx-1.26.2 + ``` + +1. Configure the build with the necessary flags: + + ```command + ./configure --with-cc-opt='-g -O2 -fstack-protector-strong -Wformat -Werror=format-security -fPIC -Wdate-time -D_FORTIFY_SOURCE=2' \ --with-ld-opt='-Wl,-z,relro -Wl,-z,now -fPIC' \ --prefix=/opt \ --conf-path=/opt/nginx/nginx.conf \ @@ -333,121 +442,152 @@ cd nginx-1.26.2 --with-openssl-opt=enable-tls1_3 \ --with-ld-opt="-L/opt/lib64 -Wl,-rpath,/opt/lib64" \ --with-cc-opt="-I/opt/include" -[...] -``` + ``` -```command -make -``` +1. Compile Nginx: -```command -sudo make install -``` + ```command + make + ``` -```command -sudo mkdir /var/lib/nginx -``` +1. Install Nginx: -```command -sudo mkdir /opt/nginx/conf.d -``` + ```command + sudo make install + ``` -#### Configure Nginx +1. Create the necessary directories for temporary file storage: -After building, add a line to the main Nginx configuration file to include configuration files in the /opt/nginx/nginx.conf directory: + ```command + sudo mkdir /var/lib/nginx + ``` -```file {title="/opt/nginx/nginx.conf"} -user www-data; #add this to the top of the file +1. Create a directory for additional configuration files: -http { - ... - # Include additional configuration files + ```command + sudo mkdir /opt/nginx/conf.d + ``` + +### Configure Nginx + +1. Edit the main Nginx configuration file: + + ```command + sudo nano /opt/nginx/nginx.conf + ``` + + Add the following line to the top of the file to specify the user: + + ```file {title="/opt/nginx/nginx.conf"} + user www-data; #add this to the top of the file + ``` + + Locate the `http` block and add the highlighted lines to include configuration files in the `/opt/nginx/nginx.conf` directory: + + ```file {title="/opt/nginx/nginx.conf" hl_lines="2,3"} + http { + #Include additional configuration files include /opt/nginx/conf.d/pqc.conf; -} -``` + ... + } + ``` -#### Create a configuration file for the server in the /opt/nginx/conf.d/ directory, such as pqc.conf: + When done, press CTRL+X, followed by Y then Enter to save the file and exit `nano`. -```file {title="/opt/nginx/conf.d/pqc.conf"} -server { - listen 443 ssl; - listen [::]:443 ssl; - server_name example.com www.example.com; +1. Create a server configuration file called `pqc.conf` in the `/opt/nginx/conf.d/` directory: - root /var/www/example.com; - index index.html index.php; + ```command + sudo nano /opt/nginx/conf.d/pqc.conf + ``` - ssl_certificate /opt/certs/example.com.crt; - ssl_certificate_key /opt/certs/example.com.key; + Give it the following contents: - ssl_protocols TLSv1.3; - ssl_prefer_server_ciphers on; - ssl_ecdh_curve x25519_kyber768:p384_kyber768:x25519:secp384r1:x448:secp256r1:secp521r1; + ```file {title="/opt/nginx/conf.d/pqc.conf"} + server { + listen 443 ssl; + listen [::]:443 ssl; + server_name {{< placeholder "example.com" >}} {{< placeholder "www.example.com" >}}; - location / { - try_files $uri $uri/ =404; + root {{< placeholder "/var/www/example.com" >}}; + index index.html index.php; + + ssl_certificate /opt/certs/{{< placeholder "example.com" >}}.crt; + ssl_certificate_key /opt/certs/{{< placeholder "example.com" >}}.key; + + ssl_protocols TLSv1.3; + ssl_prefer_server_ciphers on; + ssl_ecdh_curve x25519_kyber768:p384_kyber768:x25519:secp384r1:x448:secp256r1:secp521r1; + + location / { + try_files $uri $uri/ =404; + } } -} -``` + ``` -{{< note type="warning" >}} -**Remember!** -**Don't forget to add certificates to enable TLS!** Ensure that you include the necessary certificates, even if they are self-signed, to enable proper TLS/SSL functionality. Without certificates, you won’t be able to establish a secure HTTPS connection. + When done, press CTRL+X, followed by Y then Enter to save the file and exit `nano`. -If you want to use automatic certificate renewal with Let's Encrypt, follow [Use Certbot to Enable HTTPS with NGINX on Ubuntu](https://www.linode.com/docs/guides/enabling-https-using-certbot-with-nginx-on-ubuntu/) to properly configure the Nginx server. If u want to use self-signed certificate, follow this guide: [Enable TLS/SSL for HTTPS](https://www.linode.com/docs/guides/getting-started-with-nginx-part-3-enable-tls-for-https/), or you can easily create certificates using the following command: + {{< note >}} + Ensure that you include the necessary certificates (whether self-signed or from a trusted Certificate Authority) to enable proper TLS/SSL functionality. Without certificates, you won’t be able to establish a secure HTTPS connection. -```command -sudo mkdir /opt/certs -``` + - **Using Let's Encrpyt (Recommedned for Production)**: To use automatic certificate renewal with Let's Encrypt, follow [Use Certbot to Enable HTTPS with NGINX on Ubuntu](/docs/guides/enabling-https-using-certbot-with-nginx-on-ubuntu/) to properly configure the Nginx server. -```command -'sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /opt/certs/pqc.com.key -out /opt/certs/pqc.com.crt' -``` + - **Using Self-Signed Certificate (Suitable for Testing/Development)**: To use a self-signed certificate, see our [Enable TLS/SSL for HTTPS](/docs/guides/getting-started-with-nginx-part-3-enable-tls-for-https/) guide, or create certificates using the following command: -{{< note >}} -Note: a self-signed certificate is only suitable for testing or debugging purposes! -{{< /note >}} -{{< /note >}} + 1. First create the directory for your certificates: -#### Create a system service file for Nginx to automatically manage the server: + ```command + sudo mkdir /opt/certs + ``` -```file {title="/etc/systemd/system/nginx.service"} -[Unit] -Description=The NGINX HTTP and reverse proxy server -After=network.target remote-fs.target nss-lookup.target + 2. Then generate the self-signed certificate: -[Service] -Type=forking -PIDFile=/run/nginx.pid -ExecStartPre=/opt/sbin/nginx -t -ExecStart=/opt/sbin/nginx -ExecReload=/opt/sbin/nginx -s reload -ExecStop=/opt/sbin/nginx -s stop -PrivateTmp=true + ```command + sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /opt/certs/pqc.com.key -out /opt/certs/pqc.com.crt + ``` + {{< /note >}} -[Install] -WantedBy=multi-user.target -``` +1. Create a `systemd` service file for Nginx: -#### Start the service + ```command + sudo nano /etc/systemd/system/nginx.service + ``` -```command -sudo service nginx start -``` + Give it the following contents: + + ```file {title="/etc/systemd/system/nginx.service"} + [Unit] + Description=The NGINX HTTP and reverse proxy server + After=network.target remote-fs.target nss-lookup.target + + [Service] + Type=forking + PIDFile=/run/nginx.pid + ExecStartPre=/opt/sbin/nginx -t + ExecStart=/opt/sbin/nginx + ExecReload=/opt/sbin/nginx -s reload + ExecStop=/opt/sbin/nginx -s stop + PrivateTmp=true + + [Install] + WantedBy=multi-user.target + ``` -## Check if the post quantum algorithms are used by nginx + When done, press CTRL+X, followed by Y then Enter to save the file and exit `nano`. -The easiest and quickest way to test the algorithms used by nginx in our custom installation here is to run the openssl command shown below: +1. Start the Nginx service: + + ```command + sudo service nginx start + ``` + +Nginx should now be installed, configured, and running with OpenSSL 3.x support. + +## Verify that Nginx Is Using Post-Quantum Algorithms + +The quickest and easiest way to test the algorithms used by Nginx is to run the `openssl` command shown below: ```command openssl s_client -groups x25519_kyber768 -connect localhost:443 ``` -For additional methods, see our [Ubuntu-PQC guide](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558967). - -## Related links -[DRAFT UBUNTU Set up a Web Server and Host a Website on Linode that supports the X25519Kyber768Draft00 Key Exchange in TLS 1.3 (Post-quantum cryptography)](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558967) -[https://openquantumsafe.org/](https://openquantumsafe.org/liboqs/) -[https://openssl-library.org/](https://openssl-library.org/) -[https://pq.cloudflareresearch.com](https://pq.cloudflareresearch.com/) -[https://github.com/open-quantum-safe/oqs-provider](https://github.com/open-quantum-safe/oqs-provider) \ No newline at end of file +This command specifically checks for the `X25519_Kyber768` algorithm during a TLS connection. For additional methods, see our [Ubuntu-PQC guide](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558967). \ No newline at end of file From e1268b3884e2e766a0b1fd7cdb01a0f2be067c39 Mon Sep 17 00:00:00 2001 From: Adam Overa Date: Fri, 4 Oct 2024 15:50:21 -0400 Subject: [PATCH 3/6] Tech Edit 2 --- .../index.md | 140 ++++++++++++------ 1 file changed, 94 insertions(+), 46 deletions(-) diff --git a/docs/guides/security/encryption/host-website-with-x25519kyber768draft00-key-exchange-support/index.md b/docs/guides/security/encryption/host-website-with-x25519kyber768draft00-key-exchange-support/index.md index 487e3cb298..c7db2514d3 100644 --- a/docs/guides/security/encryption/host-website-with-x25519kyber768draft00-key-exchange-support/index.md +++ b/docs/guides/security/encryption/host-website-with-x25519kyber768draft00-key-exchange-support/index.md @@ -55,7 +55,7 @@ Once your Debian 11 compute instance is set up and secured, install the dependen ## Install OpenSSL from Source -Debian 11 comes with OpenSSL version 1.1.1w by default, but the OQS provider requires OpenSSL 3.x. Therefore, you need to build a newer version from source. +Debian 11 comes with OpenSSL version `1.1.1w` by default, but the OQS provider requires OpenSSL 3.x. Therefore, you need to build a newer version from source. 1. Download the OpenSSL source code: @@ -176,20 +176,35 @@ After verifying the source code, the next step is to build OpenSSL form source. This process may take a few minutes depending on your system. {{< /note >}} -1. Verify that OpenSSL is correctly installed and that the correct version is active: +1. Verify that the correct version of OpenSSL is installed: ```command /opt/bin/openssl version ``` - This should return the version number of the OpenSSL build: + This should return the version number of the OpenSSL build you just installed to `/opt/bin`: ```output - OpenSSL 3.3.2 + OpenSSL 3.3.2 3 Sep 2024 (Library: OpenSSL 3.3.2 3 Sep 2024) ``` -{{< note >}} -At this point, you probably want to add `/opt/bin` to your `PATH` environment variable. +1. Now check the active version via the basic `openssl` command: + + ```command + openssl version + ``` + + This should still show `1.1.1w`, the version bundled with Debian 11: + + ```output + OpenSSL 1.1.1w 11 Sep 2023 + ``` + +In order to complete the installation, you need to make sure that the version you installed in `/opt/bin` is used instead. + +### Add `/opt/bin` to Your `PATH` + +Adjust your `PATH` environment variable to prioritize the `/opt/bin` directory. 1. Open your `~/.bashrc` file in a command line text editor such as `nano`: @@ -210,23 +225,53 @@ At this point, you probably want to add `/opt/bin` to your `PATH` environment va ```command source ~/.bashrc ``` -{{< /note >}} + +1. Use the basic `openssl` command to recheck the active version of OpenSSL: + + ```command + openssl version + ``` + + The output should now be version `3.3.2` that you installed in `/opt/bin`: + + ```output + OpenSSL 3.3.2 3 Sep 2024 (Library: OpenSSL 3.3.2 3 Sep 2024) + ``` ## Install `oqs-provider` -### Install Dependencies and Clone the `oqs-provider` Repository +The `oqs-provider` is a library that integrates post-quantum cryptographic algorithms into OpenSSL. This section outlines the steps needed to install it and leverage this advanced cryptography. -A couple of required dependencies must be installed prior to `oqs-provider`: +### Install Dependencies -- `cmake`: A cross-platform build system generator that helps automate the compilation and build process for software projects. -- `ninja-build`: A build system designed to run builds in parallel, which reduces the compilation time of large projects. +A couple of dependencies, and Git, must be installed prior to `oqs-provider`: -1. Install the required dependencies, along with `git`: +1. First, change back into your user's home directory: ```command - sudo apt install -y git cmake ninja-build + cd ~ ``` +1. Install `git`, a distributed version control system that can manage code repositories: + + ```command + sudo apt install -y git + ``` + +1. Now install `cmake`, a cross-platform build system generator that helps automate the compilation and build process for software projects: + + ```command + sudo apt install -y cmake + ``` + +1. Finally, install `ninja-build`, a build system designed to run builds in parallel, which reduces the compilation time of large projects: + + ```command + sudo apt install -y ninja-build + ``` + +### Clone the `oqs-provier` Repository + 1. Use `git` to clone the `oqs-provider` repository from GitHub: ```command @@ -241,12 +286,6 @@ A couple of required dependencies must be installed prior to `oqs-provider`: ### Build `oqs-provider` -1. Temporarily add `/opt/bin` to your `PATH` environment variable if not already: - - ```command - export PATH=/opt/bin:$PATH - ``` - 1. Set the OpenSSL root directory and build the `oqs-provider` using the provided script: ```command @@ -293,7 +332,7 @@ A couple of required dependencies must be installed prior to `oqs-provider`: ``` {{< note >}} - In this case, you are editing the `/opt/ssl/openssl.cnf file, not the configuration file for the system OpenSSL! + In this case, you are editing the `/opt/ssl/openssl.cnf` file, not the configuration file for the system OpenSSL. {{< /note >}} When done, press CTRL+X, followed by Y then Enter to save the file and exit `nano`. @@ -322,10 +361,16 @@ A couple of required dependencies must be installed prior to `oqs-provider`: ## Install Nginx from Source -The version of Nginx available for Debian 11 uses OpenSSL version 1.1.1w. In order to use OpenSSL 3.x, you must build Nginx from source. +The version of Nginx available for Debian 11 uses OpenSSL version `1.1.1w`. In order to use OpenSSL 3.x, you must build Nginx from source. ### Fetch Nginx Source +1. Before continuing, change back into your user's home directory: + + ```command + cd ~ + ``` + 1. Use `wget` to download the Nginx source files: ```command @@ -393,8 +438,6 @@ A couple of libraries are required before building Nginx: ### Build Nginx -Except for the destination prefix, this example uses the same configuration parameters as the binary package. This is to retain feature parity and integrate with system scripts. The last three options passed to the `configure` script are necessary to use the OpenSSL version built earlier. - 1. Extract the source: ```command @@ -444,6 +487,8 @@ Except for the destination prefix, this example uses the same configuration para --with-cc-opt="-I/opt/include" ``` + Except for the destination `prefix`, this example uses the same configuration parameters as the binary package. This is to retain feature parity and integrate with system scripts. The last three options passed to the `configure` script are necessary to use the OpenSSL version built earlier. + 1. Compile Nginx: ```command @@ -484,10 +529,10 @@ Except for the destination prefix, this example uses the same configuration para Locate the `http` block and add the highlighted lines to include configuration files in the `/opt/nginx/nginx.conf` directory: - ```file {title="/opt/nginx/nginx.conf" hl_lines="2,3"} + ```file {title="/opt/nginx/nginx.conf" hl_lines="2,3" linenostart="18"} http { - #Include additional configuration files - include /opt/nginx/conf.d/pqc.conf; + #Include additional configuration files + include /opt/nginx/conf.d/pqc.conf; ... } ``` @@ -506,13 +551,13 @@ Except for the destination prefix, this example uses the same configuration para server { listen 443 ssl; listen [::]:443 ssl; - server_name {{< placeholder "example.com" >}} {{< placeholder "www.example.com" >}}; + server_name example.com www.example.com; - root {{< placeholder "/var/www/example.com" >}}; + root /var/www/example.com; index index.html index.php; - ssl_certificate /opt/certs/{{< placeholder "example.com" >}}.crt; - ssl_certificate_key /opt/certs/{{< placeholder "example.com" >}}.key; + ssl_certificate /opt/certs/pqc.crt; + ssl_certificate_key /opt/certs/pqc.key; ssl_protocols TLSv1.3; ssl_prefer_server_ciphers on; @@ -526,25 +571,27 @@ Except for the destination prefix, this example uses the same configuration para When done, press CTRL+X, followed by Y then Enter to save the file and exit `nano`. - {{< note >}} - Ensure that you include the necessary certificates (whether self-signed or from a trusted Certificate Authority) to enable proper TLS/SSL functionality. Without certificates, you won’t be able to establish a secure HTTPS connection. +### Set up TLS/SSL Certificates - - **Using Let's Encrpyt (Recommedned for Production)**: To use automatic certificate renewal with Let's Encrypt, follow [Use Certbot to Enable HTTPS with NGINX on Ubuntu](/docs/guides/enabling-https-using-certbot-with-nginx-on-ubuntu/) to properly configure the Nginx server. +Ensure that you include the necessary certificates (whether self-signed or from a trusted Certificate Authority) to enable proper TLS/SSL functionality. Without certificates, you won’t be able to establish a secure HTTPS connection. - - **Using Self-Signed Certificate (Suitable for Testing/Development)**: To use a self-signed certificate, see our [Enable TLS/SSL for HTTPS](/docs/guides/getting-started-with-nginx-part-3-enable-tls-for-https/) guide, or create certificates using the following command: +- **Using Let's Encrpyt (Recommedned for Production)**: To use automatic certificate renewal with Let's Encrypt, follow [Use Certbot to Enable HTTPS with NGINX on Ubuntu](/docs/guides/enabling-https-using-certbot-with-nginx-on-ubuntu/) to properly configure the Nginx server. - 1. First create the directory for your certificates: +- **Using Self-Signed Certificate (Suitable for Testing/Development)**: To use a self-signed certificate, see our [Enable TLS/SSL for HTTPS](/docs/guides/getting-started-with-nginx-part-3-enable-tls-for-https/) guide, or create certificates using the following command: - ```command - sudo mkdir /opt/certs - ``` + 1. First create the directory for your certificates: - 2. Then generate the self-signed certificate: + ```command + sudo mkdir /opt/certs + ``` - ```command - sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /opt/certs/pqc.com.key -out /opt/certs/pqc.com.crt - ``` - {{< /note >}} + 2. Then generate the self-signed certificate: + + ```command + sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /opt/certs/pqc.key -out /opt/certs/pqc.crt + ``` + +### Configure `systemd` and Start Nginx 1. Create a `systemd` service file for Nginx: @@ -582,12 +629,13 @@ Except for the destination prefix, this example uses the same configuration para Nginx should now be installed, configured, and running with OpenSSL 3.x support. -## Verify that Nginx Is Using Post-Quantum Algorithms +## Verify Nginx Is Using Post-Quantum Algorithms -The quickest and easiest way to test the algorithms used by Nginx is to run the `openssl` command shown below: +The quickest and easiest way to test the algorithms used by Nginx is to run the `openssl` command with the flags shown below: ```command openssl s_client -groups x25519_kyber768 -connect localhost:443 ``` -This command specifically checks for the `X25519_Kyber768` algorithm during a TLS connection. For additional methods, see our [Ubuntu-PQC guide](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558967). \ No newline at end of file +This command specifically checks for the `X25519_Kyber768` algorithm during a TLS connection. For additional verification methods, see our [Ubuntu-PQC guide](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558967). +{{< /note >}} \ No newline at end of file From 0dc3dee33dc6be034dfb771e5fe88bfa78a9de2f Mon Sep 17 00:00:00 2001 From: Adam Overa Date: Fri, 4 Oct 2024 15:51:23 -0400 Subject: [PATCH 4/6] Hugo Error Fix 1 --- .../index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/guides/security/encryption/host-website-with-x25519kyber768draft00-key-exchange-support/index.md b/docs/guides/security/encryption/host-website-with-x25519kyber768draft00-key-exchange-support/index.md index c7db2514d3..90f762cc34 100644 --- a/docs/guides/security/encryption/host-website-with-x25519kyber768draft00-key-exchange-support/index.md +++ b/docs/guides/security/encryption/host-website-with-x25519kyber768draft00-key-exchange-support/index.md @@ -637,5 +637,4 @@ The quickest and easiest way to test the algorithms used by Nginx is to run the openssl s_client -groups x25519_kyber768 -connect localhost:443 ``` -This command specifically checks for the `X25519_Kyber768` algorithm during a TLS connection. For additional verification methods, see our [Ubuntu-PQC guide](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558967). -{{< /note >}} \ No newline at end of file +This command specifically checks for the `X25519_Kyber768` algorithm during a TLS connection. For additional verification methods, see our [Ubuntu-PQC guide](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558967). \ No newline at end of file From 32563c4cfac0ce7add48d7bc6d44b4a07b4f03ce Mon Sep 17 00:00:00 2001 From: Adam Overa Date: Fri, 4 Oct 2024 16:13:14 -0400 Subject: [PATCH 5/6] Tech Edit 3 --- .../index.md | 71 ++++++++++++------- 1 file changed, 44 insertions(+), 27 deletions(-) diff --git a/docs/guides/security/encryption/host-website-with-x25519kyber768draft00-key-exchange-support/index.md b/docs/guides/security/encryption/host-website-with-x25519kyber768draft00-key-exchange-support/index.md index 90f762cc34..a3eb0981dd 100644 --- a/docs/guides/security/encryption/host-website-with-x25519kyber768draft00-key-exchange-support/index.md +++ b/docs/guides/security/encryption/host-website-with-x25519kyber768draft00-key-exchange-support/index.md @@ -15,7 +15,7 @@ external_resources: - '[GitHub: Open Quantum Safe oqs-provider](https://github.com/open-quantum-safe/oqs-provider)' --- -The National Institute of Standards and Technology (NIST) recently [released](https://www.nist.gov/news-events/news/2024/08/nist-releases-first-3-finalized-post-quantum-encryption-standards) its first finalized Post-Quantum Encryption Standards to protect against quantum computer attacks. This includes the Module-Lattice-based Key-Encapsulation Mechanism standard (ML-KEM, defined in [FIPS-203](https://csrc.nist.gov/pubs/fips/203/final). It is already being implemented in the industry using an early [pre-standardization draft](https://datatracker.ietf.org/doc/draft-tls-westerbaan-xyber768d00/) for use with TLS. +The National Institute of Standards and Technology (NIST) recently [released](https://www.nist.gov/news-events/news/2024/08/nist-releases-first-3-finalized-post-quantum-encryption-standards) its first finalized Post-Quantum Encryption Standards to protect against quantum computer attacks. This includes the Module-Lattice-based Key-Encapsulation Mechanism standard (ML-KEM, defined in [FIPS-203](https://csrc.nist.gov/pubs/fips/203/final)). It is already being implemented in the industry using an early [pre-standardization draft](https://datatracker.ietf.org/doc/draft-tls-westerbaan-xyber768d00/) for use with TLS. Deploying this algorithm for your web server currently requires some additional steps. The process may vary depending on your operating system's version of OpenSSL. This guide shows you how to build OpenSSL 3.x and the Open Quantum Safe (OQS) provider on Debian 11. For instructions on Ubuntu 24.04 LTS, please see [this document](https://collaborate.akamai.com/confluence/pages/viewpage.action?pageId=1012558967). @@ -35,19 +35,19 @@ This guide is written for a non-root user. Commands that require elevated privil Once your Debian 11 compute instance is set up and secured, install the dependencies and system packages needed to build OpenSSL and the OQS provider. -1. Update your package list to ensure you download the latest available versions: +1. First, update your package list to ensure you download the latest available versions: ```command sudo apt update ``` -1. Install `make`, a build automation tool used to compile and link programs from source code. It reads instructions from a Makefile, which defines how to compile and build the software: +1. Next, install `make`, a build automation tool used to compile and link programs from source code. It reads instructions from a Makefile, which defines how to compile and build the software: ```command sudo apt install -y make ``` -1. Install `gcc` (GNU Compiler Collection), which compiles source code written in languages like C and C++ into executable programs. It is essential for building OpenSSL and other software from source code: +1. Now install `gcc` (GNU Compiler Collection), which compiles source code written in languages like C and C++ into executable programs. It is essential for building OpenSSL and other software from source code: ```command sudo apt install -y gcc @@ -57,6 +57,12 @@ Once your Debian 11 compute instance is set up and secured, install the dependen Debian 11 comes with OpenSSL version `1.1.1w` by default, but the OQS provider requires OpenSSL 3.x. Therefore, you need to build a newer version from source. +1. First, change into your user's home directory, if not already: + + ```command + cd ~ + ``` + 1. Download the OpenSSL source code: ```command @@ -88,21 +94,24 @@ Before proceeding with the installation, verify the integrity and authenticity o When prompted, press the 1 key followed by ENTER to choose the key from `openssl@openssl.org`: ```output + gpg: directory '/home/{{< placeholder "USERNAME" >}}/.gnupg' created + gpg: keybox '/home/{{< placeholder "USERNAME" >}}/.gnupg/pubring.kbx' created gpg: data source: https://keys.openpgp.org:443 - (1) OpenSSL - 4096 bit RSA key 216094DFD0CB81EF, created: 2024-04-08 - Keys 1-1 of 1 for "openssl@openssl.org". Enter number(s), N)ext, or Q)uit > 1 + (1) OpenSSL + 4096 bit RSA key 216094DFD0CB81EF, created: 2024-04-08 + Keys 1-1 of 1 for "openssl@openssl.org". Enter number(s), N)ext, or Q)uit > ``` Afterward, you should see output similar to the following: ```output + gpg: /home/{{< placeholder "USERNAME" >}}/.gnupg/trustdb.gpg: trustdb created gpg: key 216094DFD0CB81EF: public key "OpenSSL " imported gpg: Total number processed: 1 - gpg: imported: 1 + gpg: imported: 1 ``` -1. Verify the fingerprint pf the imported key to ensure it matches OpenSSL's official key: +1. Verify the fingerprint of the imported key to ensure it matches OpenSSL's official key: ```command gpg --fingerprint openssl@openssl.org @@ -113,7 +122,7 @@ Before proceeding with the installation, verify the integrity and authenticity o ```output pub rsa4096 2024-04-08 [SC] [expires: 2026-04-08] BA54 73A2 B058 7B07 FB27 CF2D 2160 94DF D0CB 81EF - uid [ unknown] OpenSSL + uid [ unknown] OpenSSL ``` 1. Finally, verify the OpenSSL source file against its signature: @@ -125,18 +134,26 @@ Before proceeding with the installation, verify the integrity and authenticity o You should see a confirmation similar to the output below: ```output - gpg: Signature made Tue Sep 3 08:46:51 2024 EDT - gpg: using RSA key BA5473A2B0587B07FB27CF2D216094DFD0CB81EF - gpg: Good signature from "OpenSSL " [ultimate] + gpg: Signature made Tue 03 Sep 2024 08:46:51 AM EDT + gpg: using RSA key BA5473A2B0587B07FB27CF2D216094DFD0CB81EF + gpg: Good signature from "OpenSSL " [unknown] ``` {{< note >}} - If you see a warning message about not having a trusted path to the OpenSSL key, it does not impact the validity of the signature. The warning message appears because the OpenSSL signing key has not yet been marked as "trusted" in your GnuPG keyring. + If you see a warning message about not having a trusted signature, it does not impact the validity of the signature: + + ```output + gpg: WARNING: This key is not certified with a trusted signature! + gpg: There is no indication that the signature belongs to the owner. + Primary key fingerprint: BA54 73A2 B058 7B07 FB27 CF2D 2160 94DF D0CB 81EF + ``` + + The warning message appears because the OpenSSL signing key has not yet been marked as "trusted" in your GnuPG keyring. {{< /note >}} ### Build OpenSSL -After verifying the source code, the next step is to build OpenSSL form source. +After verifying the source code, the next step is to build OpenSSL from source. 1. Extract the downloaded OpenSSL archive: @@ -150,7 +167,7 @@ After verifying the source code, the next step is to build OpenSSL form source. cd openssl-3.3.2 ``` -1. Configure the OpenSSL build, specifying the installation path (`/opt` in this case) and setting the appropriate runtime library search path: +1. Configure the OpenSSL build, specifying the installation path as `/opt` and setting the appropriate runtime library search path: ```command ./Configure --prefix=/opt '-Wl,-rpath,$(LIBRPATH)' @@ -194,7 +211,7 @@ After verifying the source code, the next step is to build OpenSSL form source. openssl version ``` - This should still show `1.1.1w`, the version bundled with Debian 11: + This should still show `1.1.1w`, the default version bundled with Debian 11: ```output OpenSSL 1.1.1w 11 Sep 2023 @@ -232,7 +249,7 @@ Adjust your `PATH` environment variable to prioritize the `/opt/bin` directory. openssl version ``` - The output should now be version `3.3.2` that you installed in `/opt/bin`: + The output should now show version `3.3.2`, which you installed in `/opt/bin`: ```output OpenSSL 3.3.2 3 Sep 2024 (Library: OpenSSL 3.3.2 3 Sep 2024) @@ -244,7 +261,7 @@ The `oqs-provider` is a library that integrates post-quantum cryptographic algor ### Install Dependencies -A couple of dependencies, and Git, must be installed prior to `oqs-provider`: +A couple of dependencies must be installed prior to `oqs-provider`, along with Git: 1. First, change back into your user's home directory: @@ -310,7 +327,7 @@ A couple of dependencies, and Git, must be installed prior to `oqs-provider`: ### Configure OpenSSL to Use the OQS Provider -1. Use a command line text editor such as `nano` to edit the OpenSSL configuration file: +1. Use `nano` to edit the OpenSSL configuration file: ```command sudo nano /opt/ssl/openssl.cnf @@ -403,16 +420,16 @@ The version of Nginx available for Debian 11 uses OpenSSL version `1.1.1w`. In o gpg --verify nginx-1.26.2.tar.gz.asc nginx-1.26.2.tar.gz ``` - You should see output similar to the below if verification succeeds: + If verification succeeds, you should see output similar to the following: ```output - gpg: Signature made Tue Aug 13 08:48:05 2024 EDT - gpg: using RSA key D6786CE303D9A9022998DC6CC8464D549AF75C0A - gpg: issuer "s.kandaurov@f5.com" + gpg: Signature made Tue 13 Aug 2024 08:48:05 AM EDT + gpg: using RSA key D6786CE303D9A9022998DC6CC8464D549AF75C0A + gpg: issuer "s.kandaurov@f5.com" gpg: Good signature from "Sergey Kandaurov " [unknown] - gpg: aka "Sergey Kandaurov " [unknown] - gpg: WARNING: The key's User ID is not certified with a trusted signature! - gpg: There is no indication that the signature belongs to the owner. + gpg: aka "Sergey Kandaurov " [unknown] + gpg: WARNING: This key is not certified with a trusted signature! + gpg: There is no indication that the signature belongs to the owner. Primary key fingerprint: D678 6CE3 03D9 A902 2998 DC6C C846 4D54 9AF7 5C0A ``` From 995b9e443df14b8190ab427a51a8f50f6a5adc2b Mon Sep 17 00:00:00 2001 From: Adam Overa Date: Fri, 4 Oct 2024 16:17:43 -0400 Subject: [PATCH 6/6] CI Tests Fix 1 --- .../index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/security/encryption/host-website-with-x25519kyber768draft00-key-exchange-support/index.md b/docs/guides/security/encryption/host-website-with-x25519kyber768draft00-key-exchange-support/index.md index a3eb0981dd..ca7fa7f476 100644 --- a/docs/guides/security/encryption/host-website-with-x25519kyber768draft00-key-exchange-support/index.md +++ b/docs/guides/security/encryption/host-website-with-x25519kyber768draft00-key-exchange-support/index.md @@ -98,7 +98,7 @@ Before proceeding with the installation, verify the integrity and authenticity o gpg: keybox '/home/{{< placeholder "USERNAME" >}}/.gnupg/pubring.kbx' created gpg: data source: https://keys.openpgp.org:443 (1) OpenSSL - 4096 bit RSA key 216094DFD0CB81EF, created: 2024-04-08 + 4096 bit RSA key 216094DFD0CB81EF, created: 2024-04-08 Keys 1-1 of 1 for "openssl@openssl.org". Enter number(s), N)ext, or Q)uit > ```