From 37c066f08e257f66714e4fd1eabebc2bf611c341 Mon Sep 17 00:00:00 2001 From: Adam Overa Date: Wed, 2 Oct 2024 15:12:31 -0400 Subject: [PATCH 01/11] 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 00000000000..96848f3559d --- /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 02/11] 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 96848f3559d..487e3cb298e 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 03/11] 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 487e3cb298e..c7db2514d37 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 04/11] 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 c7db2514d37..90f762cc348 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 05/11] 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 90f762cc348..a3eb0981ddf 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 06/11] 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 a3eb0981ddf..ca7fa7f4762 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 > ``` From 8e87e74eb00eb8384b17ded6279913047b24ca60 Mon Sep 17 00:00:00 2001 From: Nathan Melehan Date: Wed, 30 Oct 2024 02:39:38 -0400 Subject: [PATCH 07/11] Add Ubuntu guide, additional copy edits --- .../index.md | 31 +- .../index.md | 483 ++++++++++++++++++ 2 files changed, 501 insertions(+), 13 deletions(-) rename docs/guides/security/encryption/{host-website-with-x25519kyber768draft00-key-exchange-support => post-quantum-encryption-nginx-debian11}/index.md (89%) create mode 100644 docs/guides/security/encryption/post-quantum-encryption-nginx-ubuntu2404/index.md diff --git a/docs/guides/security/encryption/host-website-with-x25519kyber768draft00-key-exchange-support/index.md b/docs/guides/security/encryption/post-quantum-encryption-nginx-debian11/index.md similarity index 89% rename from docs/guides/security/encryption/host-website-with-x25519kyber768draft00-key-exchange-support/index.md rename to docs/guides/security/encryption/post-quantum-encryption-nginx-debian11/index.md index ca7fa7f4762..c8d0563e23c 100644 --- a/docs/guides/security/encryption/host-website-with-x25519kyber768draft00-key-exchange-support/index.md +++ b/docs/guides/security/encryption/post-quantum-encryption-nginx-debian11/index.md @@ -1,31 +1,36 @@ --- -slug: host-website-with-x25519kyber768draft00-key-exchange-support -title: "Debian 11 Web Hosting with Post-Quantum Cryptography: X25519Kyber768Draft00 and TLS 1.3" +slug: post-quantum-encryption-nginx-debian11 +title: "Post Quantum Encryption with NGINX on Debian 11" 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 +published: 2024-10-30 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: -- '[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)' +relations: + platform: + key: post-quantum-encryption-nginx + keywords: + - distribution: Debian 11 --- 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). +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 how to deploy this algorithm with NGINX on Debian 11. The [Open Quantum Safe (OQS) provider](https://github.com/open-quantum-safe/oqs-provider) for OpenSSL is built to enable the post quantum encryption algorithm. ## Before You Begin -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. +1. To follow along with the steps in the guide, create a Compute Instance running Debian 11. See the [Get started](https://techdocs.akamai.com/cloud-computing/docs/getting-started) and [Create a compute instance](https://techdocs.akamai.com/cloud-computing/docs/create-a-compute-instance) product documentation for instructions. You may also choose to adapt the configuration from this guide to an existing NGINX installation. -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. +1. Follow the [Set up and secure a Compute Instance](https://techdocs.akamai.com/cloud-computing/docs/set-up-and-secure-a-compute-instance) product documentation to appropriately secure your system. -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. +1. To implement the algorithm in NGINX, an SSL certificate is required. Instructions for creating a self-signed certificate in this guide. If you prefer to use a certificate from an authority, a domain name or subdomain must be assigned to your Linode instance. Visit your domain name registrar's website, to assign a new record to your Linode instance's IP address. Your IP address is [displayed in the cloud manager](https://techdocs.akamai.com/cloud-computing/docs/managing-ip-addresses-on-a-compute-instance#viewing-ip-addresses). If you use the Linode DNS Manager, visit the [manage DNS records](https://techdocs.akamai.com/cloud-computing/docs/manage-domains) product documentation to view instructions for assigning a new A/AAAA record to your IP address. + +1. For an overview of how TLS encryption works, review the [Understanding TLS Certificates and Connections](https://www.linode.com/docs/guides/what-is-a-tls-certificate/) guide. {{< 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. @@ -287,7 +292,7 @@ A couple of dependencies must be installed prior to `oqs-provider`, along with G sudo apt install -y ninja-build ``` -### Clone the `oqs-provier` Repository +### Clone the `oqs-provider` Repository 1. Use `git` to clone the `oqs-provider` repository from GitHub: @@ -592,7 +597,7 @@ A couple of libraries are required before building Nginx: 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 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. +- **Using Let's Encrpyt (Recommended 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. - **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: @@ -648,10 +653,10 @@ Nginx should now be installed, configured, and running with OpenSSL 3.x support. ## 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 with the flags shown below: +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 verification 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. \ No newline at end of file diff --git a/docs/guides/security/encryption/post-quantum-encryption-nginx-ubuntu2404/index.md b/docs/guides/security/encryption/post-quantum-encryption-nginx-ubuntu2404/index.md new file mode 100644 index 00000000000..73091379d4d --- /dev/null +++ b/docs/guides/security/encryption/post-quantum-encryption-nginx-ubuntu2404/index.md @@ -0,0 +1,483 @@ +--- +slug: post-quantum-encryption-nginx-ubuntu2404 +title: "Post Quantum Encryption with NGINX on Ubuntu 24.04" +description: "Learn how to set up NGINX on Ubuntu 24.04 with support for the post-quantum cryptography X25519Kyber768Draft00 key exchange in TLS 1.3." +authors: ["Linode"] +contributors: ["Linode"] +published: 2024-10-30 +keywords: ['X25519Kyber768Draft00','post-quantum cryptography','tls 1.3','cybersecurity','ubuntu 24.04','key exhange','OpenSSL','encryption','secure website'] +license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' +external_resources: +- '[Open Quantum Safe](https://openquantumsafe.org/)' +- '[OpenSSL Library](https://openssl-library.org/)' +- '[open-quantum-safe/oqs-provider on GitHub](https://github.com/open-quantum-safe/oqs-provider)' +relations: + platform: + key: post-quantum-encryption-nginx + keywords: + - distribution: Ubuntu 24.04 +--- + +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 how to deploy this algorithm with NGINX on Ubuntu 24.04. The [Open Quantum Safe (OQS) provider](https://github.com/open-quantum-safe/oqs-provider) for OpenSSL is built to enable the post quantum encryption algorithm. After it is configured for the web server, several ways to verify that the server is using the algorithm are demonstrated. + +## Before You Begin + +1. To follow along with the steps in the guide, create a Compute Instance running Ubuntu 24.04. See the [Get started](https://techdocs.akamai.com/cloud-computing/docs/getting-started) and [Create a compute instance](https://techdocs.akamai.com/cloud-computing/docs/create-a-compute-instance) product documentation for instructions. You may also choose to adapt the configuration from this guide to an existing NGINX installation. + +1. Follow the [Set up and secure a Compute Instance](https://techdocs.akamai.com/cloud-computing/docs/set-up-and-secure-a-compute-instance) product documentation to appropriately secure your system. + +1. To implement the algorithm in NGINX, an SSL certificate is required. Instructions for creating a self-signed certificate in this guide. If you prefer to use a certificate from an authority, a domain name or subdomain must be assigned to your Linode instance. Visit your domain name registrar's website, to assign a new record to your Linode instance's IP address. Your IP address is [displayed in the cloud manager](https://techdocs.akamai.com/cloud-computing/docs/managing-ip-addresses-on-a-compute-instance#viewing-ip-addresses). If you use the Linode DNS Manager, visit the [manage DNS records](https://techdocs.akamai.com/cloud-computing/docs/manage-domains) product documentation to view instructions for assigning a new A/AAAA record to your IP address. + +1. For an overview of how TLS encryption works, review the [Understanding TLS Certificates and Connections](https://www.linode.com/docs/guides/what-is-a-tls-certificate/) guide. + +{{< 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 >}} + +## Install Dependencies + +Once your Ubuntu 24.04 compute instance is set up and secured, install the dependencies and system packages needed to build the OQS provider. + +1. Update your package list to ensure you download the latest available versions: + + ```command + sudo apt update + ``` + +1. 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. Install `libssl-dev`, which provides development libraries and headers for OpenSSL, needed to build software that requires cryptographic functions and secure communications: + + ```command + sudo apt install -y libssl-dev + ``` + +1. Install `ninja-build`, a fast and lightweight build system designed to run builds in parallel, speeding up the compilation of large projects: + + ```command + sudo apt install -y ninja-build + ``` + +### Check if you have already installed OpenSSL 3.x + + +```command +openssl version +``` + +If OpenSSL 3.x+ is already installed, go to the "Install the oqs-provider" step. + +## Update OpenSSL + +1. Check if you have already installed OpenSSL >= 3.x: + + ```command + openssl version + ``` + + This should generate output like: + + ```output + OpenSSL 3.0.13 30 Jan 2024 (Library: OpenSSL 3.0.13 30 Jan 2024) + ``` + + If OpenSSL 3.x+ is already installed, skip to the [Install oqs-provider](#install-oqs-provider) section. + +1. Update OpenSSL from Ubuntu repositories: + + ```command + sudo apt install -y openssl + ``` + +1. Verify that you now have OpenSSL >= 3.x: + + ```command + openssl version + ``` + +## Install `oqs-provider` + +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. + +### Clone the `oqs-provider` Repository + +1. Use `git` to clone the `oqs-provider` repository from GitHub: + + ```command + git clone https://github.com/open-quantum-safe/oqs-provider.git + ``` + +1. Change into the `oqs-provider` directory: + + ```command + cd oqs-provider + ``` + +### Build `oqs-provider` + +1. Set the OpenSSL root directory and build the `oqs-provider` using the provided script: + + ```command + scripts/fullbuild.sh + ``` + + {{< note >}} + This process may take a few minutes depending on your system. + {{< /note >}} + +1. Use `cmake` to install the compiled `oqs-provider`: + + ```command + sudo cmake --install _build + ``` + +1. Run the test suite to verify the `oqs-provider` build: + + ```command + scripts/runtests.sh + ``` + + The tail of the output from the tests should resemble: + + ```output + 100% tests passed, 0 tests failed out of 6 + + Total Test time (real) = 93.97 sec + + All oqsprovider tests passed. + ``` + +### Configure OpenSSL to Use the OQS Provider + +Use `nano` to edit the OpenSSL configuration file: + +```command +sudo nano /etc/ssl/openssl.cnf +``` + +Add the following lines at the end: + +```file {title="/etc/ssl/openssl.cnf"} +# PQC via OpenQuantumSafe +[provider_sect] +default = default_sect +oqsprovider = oqsprovider_sect + +[default_sect] +activate = 1 + +[oqsprovider_sect] +activate = 1 +``` + +When done, press CTRL+X, followed by Y then Enter to save the file and exit `nano`. + +### Check Provider Version Information + +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.0.13 + status: active + oqsprovider + name: OpenSSL OQS Provider + version: 0.6.2-dev + status: active +``` + +## Verify the Quantum-Safe KEM Algorithms are Available + +Run: + +```command +openssl list -kem-algorithms -provider oqsprovider | grep kyber +``` + +Output should resemble: + +```output +kyber512 @ oqsprovider +p256_kyber512 @ oqsprovider +x25519_kyber512 @ oqsprovider +kyber768 @ oqsprovider +p384_kyber768 @ oqsprovider +x448_kyber768 @ oqsprovider +x25519_kyber768 @ oqsprovider +p256_kyber768 @ oqsprovider +kyber1024 @ oqsprovider +p521_kyber1024 @ oqsprovider +``` + +## Set Up NGINX + +### Install NGINX + +Use `apt` to install NGINX: + +```command +sudo apt install nginx +``` + +### Set up TLS/SSL Certificates + +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 Let's Encrpyt (Recommended 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. + +- **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: + + 1. First create the directory for your certificates: + + ```command + sudo mkdir /opt/certs + ``` + + 1. 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 NGINX + +1. Edit the main Nginx configuration file: + + ```command + sudo nano /etc/nginx/nginx.conf + ``` + + Add the following line to the top of the file to specify the user: + + ```file {title="/etc/nginx/nginx.conf"} + user www-data; #add this to the top of the file + ``` + +1. Locate the `http` block and add the highlighted lines to include configuration files in the `/etc/nginx/nginx.conf` directory: + + ```file {title="/etc/nginx/nginx.conf" hl_lines="2,3" linenostart="18"} + http { + #Include additional configuration files + include /etc/nginx/conf.d/pqc.conf; + ... + } + ``` + + When done, press CTRL+X, followed by Y then Enter to save the file and exit `nano`. + +1. Create a server configuration file called `pqc.conf` in the `/etc/nginx/conf.d/` directory: + + ```command + sudo nano /etc/nginx/conf.d/pqc.conf + ``` + + Paste this snippet into the file. **Be sure to update the `ssl_certificate` and `ssl_certificate_key` parameters** with the correct file paths for your certificate files: + + ```file {title="/etc/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/pqc.crt; + ssl_certificate_key /opt/certs/pqc.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; + } + } + ``` + + When done, press CTRL+X, followed by Y then Enter to save the file and exit `nano`. + +1. Reload the NGINX service: + + ```command + sudo systemctl reload nginx + ``` + +## Verify Nginx Is Using Post-Quantum Algorithms + +### Option 1: test with `openssl s_client` command + +To test the TLS configuration with Kyber groups using the `openssl s_client` command, you can use the following options: + +```command +openssl s_client -groups x25519_kyber768 -connect localhost:443 +``` + +### Option 2: Capture connection using tcpdump + +1. Enable Kyber support in either Google Chrome or Mozilla Firefox: + + - Chrome: + + 1. Open Chrome and navigate to [chrome://flags](chrome://flags). + + 1. In the search bar, enter `TLS 1.3 hybridized Kyber`. + + 1. Toggle the option to Enabled for `TLS 1.3 hybridized Kyber support`. + + - Firefox: + + 1. Open Chrome and navigate to [about:config](about:config). + + 1. In the search bar, enter `security.tls.enable_kyber`. + + 1. Toggle the option to True for `security.tls.enable_kyber`. + +1. Run tcpdump to capture the network traffic between your browser and the server. In a terminal on your workstation: + + ```command + sudo tcpdump -w pqc.pcap host + ``` + +1. Visit your site using Chrome or Firefox. + +1. Use Wireshark/Tshark to analyze the captured data: + + ```command + tshark -r pqc.pcap -V | grep X25519Kyber768Draft00 + ``` + + Look for the use of `x25519Kyber768Draft00` as one of the key shares within the TLS handshake extension. You should see output like this: + + ```output + Extension: key_share (len=1263) X25519Kyber768Draft00, x25519 + Type: key_share (51) + Length: 1263 + ``` + +### Option 3: Display TLS Connection Details with PHP + +These steps create an index.php page on your web server that displays information about your encryption algorithm: + +1. On your web server, install PHP 8.3 with FPM: + + ```command + sudo apt install -y php-fpm + ``` + +1. Edit `/etc/nginx/conf.d/pqc.conf`: + + 1. Change the `index` parameter to point to the new `index.php` file: + + ```file {title="/etc/nginx/conf.d/example.com.conf"} + server { + ... + index index.php; + ... + ``` + + 1. Add a new `location ~ \.php$` block above the existing `location /` block: + + ```file {title="/etc/nginx/conf.d/example.com.conf" hl_lines="4-8"} + server { + ... + + location ~ \.php$ { + include snippets/fastcgi-php.conf; + fastcgi_param SSL_CURVE $ssl_curve; + fastcgi_pass unix:/var/run/php/php-fpm.sock; + } + + location / { + try_files $uri $uri/ =404; + } + } + ``` + +1. Create a file named `index.php` in /var/www/example.com with this snippet: + + ```command + sudo mkdir -p /var/www/example.com + ``` + + ```file {title="/var/www/example.com/index.php"} + + + + + + SSL Curve Information + + +

Your SSL Curve Information

+ + You are using X25519Kyber768Draft00 which is post-quantum secure.

"; + } else { + echo "

You are using SSL Curve: {$ssl_curve} which is not post-quantum secure.

"; + } + ?> + + + + ``` + +1. Reload NGINX: + + ```command + sudo systemctl reload nginx + ``` + +1. Enable Kyber support in either Google Chrome or Mozilla Firefox: + + - Chrome: + + 1. Open Chrome and navigate to [chrome://flags](chrome://flags). + + 1. In the search bar, enter `TLS 1.3 hybridized Kyber`. + + 1. Toggle the option to Enabled for `TLS 1.3 hybridized Kyber support`. + + - Firefox: + + 1. Open Chrome and navigate to [about:config](about:config). + + 1. In the search bar, enter `security.tls.enable_kyber`. + + 1. Toggle the option to True for `security.tls.enable_kyber`. + +1. Visit your website in your browser. If Kyber support is enabled in your browser, and if the TLS handshake with the web server uses the algorithm, you should see: + + ```output + You are using X25519Kyber768Draft00 which is post-quantum secure + ``` + + Otherwise, this message is displayed: + + ```output + You are using SSL Curve: X25519 which is not post-quantum secure. + ``` + +{{< note >}} +Remember that currently not all browsers support post-quantum algorithms. These browsers offer compatibility: + +- Enabled by default for Chrome 124+ on Desktop. For older Chrome versions or on mobile, you need to toggle `TLS 1.3 hybridized Kyber support` in [chrome://flags](chrome://flags). + +- Enabled by default for Edge 124+. + +- Enabled by default for recent Opera and Brave. + +- Enabled for Firefox 124+ if you turn on `security.tls.enable_kyber` in [about:config](about:config). Firefox 128+: turn on `network.http.http3.enable_kyber` for QUIC/HTTP3. +{{< /note >}} \ No newline at end of file From 88ddcf46349d208f6b95c145ed1715e03033d887 Mon Sep 17 00:00:00 2001 From: Nathan Melehan Date: Wed, 30 Oct 2024 09:30:59 -0400 Subject: [PATCH 08/11] Fix vale and link test errors --- ci/vale/dictionary.txt | 1 + .../encryption/post-quantum-encryption-nginx-debian11/index.md | 2 +- .../post-quantum-encryption-nginx-ubuntu2404/index.md | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/ci/vale/dictionary.txt b/ci/vale/dictionary.txt index bc6ded96b76..6e55fca5889 100644 --- a/ci/vale/dictionary.txt +++ b/ci/vale/dictionary.txt @@ -1279,6 +1279,7 @@ kubespray Kuma kustomize kuznetosv +Kyber lambdabunker Laminas Langa diff --git a/docs/guides/security/encryption/post-quantum-encryption-nginx-debian11/index.md b/docs/guides/security/encryption/post-quantum-encryption-nginx-debian11/index.md index c8d0563e23c..1480595461c 100644 --- a/docs/guides/security/encryption/post-quantum-encryption-nginx-debian11/index.md +++ b/docs/guides/security/encryption/post-quantum-encryption-nginx-debian11/index.md @@ -30,7 +30,7 @@ Deploying this algorithm for your web server currently requires some additional 1. To implement the algorithm in NGINX, an SSL certificate is required. Instructions for creating a self-signed certificate in this guide. If you prefer to use a certificate from an authority, a domain name or subdomain must be assigned to your Linode instance. Visit your domain name registrar's website, to assign a new record to your Linode instance's IP address. Your IP address is [displayed in the cloud manager](https://techdocs.akamai.com/cloud-computing/docs/managing-ip-addresses-on-a-compute-instance#viewing-ip-addresses). If you use the Linode DNS Manager, visit the [manage DNS records](https://techdocs.akamai.com/cloud-computing/docs/manage-domains) product documentation to view instructions for assigning a new A/AAAA record to your IP address. -1. For an overview of how TLS encryption works, review the [Understanding TLS Certificates and Connections](https://www.linode.com/docs/guides/what-is-a-tls-certificate/) guide. +1. For an overview of how TLS encryption works, review the [Understanding TLS Certificates and Connections](/docs/guides/what-is-a-tls-certificate/) guide. {{< 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. diff --git a/docs/guides/security/encryption/post-quantum-encryption-nginx-ubuntu2404/index.md b/docs/guides/security/encryption/post-quantum-encryption-nginx-ubuntu2404/index.md index 73091379d4d..0b6cd598cc5 100644 --- a/docs/guides/security/encryption/post-quantum-encryption-nginx-ubuntu2404/index.md +++ b/docs/guides/security/encryption/post-quantum-encryption-nginx-ubuntu2404/index.md @@ -30,7 +30,7 @@ Deploying this algorithm for your web server currently requires some additional 1. To implement the algorithm in NGINX, an SSL certificate is required. Instructions for creating a self-signed certificate in this guide. If you prefer to use a certificate from an authority, a domain name or subdomain must be assigned to your Linode instance. Visit your domain name registrar's website, to assign a new record to your Linode instance's IP address. Your IP address is [displayed in the cloud manager](https://techdocs.akamai.com/cloud-computing/docs/managing-ip-addresses-on-a-compute-instance#viewing-ip-addresses). If you use the Linode DNS Manager, visit the [manage DNS records](https://techdocs.akamai.com/cloud-computing/docs/manage-domains) product documentation to view instructions for assigning a new A/AAAA record to your IP address. -1. For an overview of how TLS encryption works, review the [Understanding TLS Certificates and Connections](https://www.linode.com/docs/guides/what-is-a-tls-certificate/) guide. +1. For an overview of how TLS encryption works, review the [Understanding TLS Certificates and Connections](/docs/guides/what-is-a-tls-certificate/) guide. {{< 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. From a2ae352a9f1d8d75e3d56b6e809037e7a8281cf0 Mon Sep 17 00:00:00 2001 From: Jan Schaumann Date: Tue, 5 Nov 2024 11:48:53 -0500 Subject: [PATCH 09/11] tweak a few things and update for the latest upstream changes since we started writing these docs --- .../index.md | 50 +++++------ .../index.md | 84 ++++++------------- 2 files changed, 50 insertions(+), 84 deletions(-) diff --git a/docs/guides/security/encryption/post-quantum-encryption-nginx-debian11/index.md b/docs/guides/security/encryption/post-quantum-encryption-nginx-debian11/index.md index 1480595461c..9b40918f7b4 100644 --- a/docs/guides/security/encryption/post-quantum-encryption-nginx-debian11/index.md +++ b/docs/guides/security/encryption/post-quantum-encryption-nginx-debian11/index.md @@ -1,11 +1,11 @@ --- slug: post-quantum-encryption-nginx-debian11 title: "Post Quantum Encryption with NGINX on Debian 11" -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"] +description: "Learn how to set up a Debian 11 Nginx web server with support for the post-quantum cryptography X25519Kyber768Draft00 / ML-KEM key exchange in TLS 1.3." +authors: ["Seweryn Krajczok", "Jan Schaumann"] contributors: ["Linode"] -published: 2024-10-30 -keywords: ['X25519Kyber768Draft00','post-quantum cryptography','tls 1.3','cybersecurity','debian 11','key exhange','OpenSSL','encryption','secure website'] +published: 2024-11-05 +keywords: ['X25519Kyber768Draft00','X25519MLKEM768', 'ML-KEM', '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: - '[Open Quantum Safe](https://openquantumsafe.org/liboqs/)' @@ -20,7 +20,9 @@ relations: 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 how to deploy this algorithm with NGINX on Debian 11. The [Open Quantum Safe (OQS) provider](https://github.com/open-quantum-safe/oqs-provider) for OpenSSL is built to enable the post quantum encryption algorithm. +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 how to deploy this algorithm with NGINX on Debian 11, using the [Open Quantum Safe (OQS) provider](https://github.com/open-quantum-safe/oqs-provider) for OpenSSL, which is used to enable the post quantum encryption algorithm. + +_Note_: we chose Debian 11 here to illustrate the process of building OpenSSL and NGINX from sources. See [this guide](/docs/guides/security/encryption/post-quantum-encryption-nginx-ubuntu2404/) for a document guiding you through the setup on an Ubuntu 24.04 system instead. ## Before You Begin @@ -28,7 +30,7 @@ Deploying this algorithm for your web server currently requires some additional 1. Follow the [Set up and secure a Compute Instance](https://techdocs.akamai.com/cloud-computing/docs/set-up-and-secure-a-compute-instance) product documentation to appropriately secure your system. -1. To implement the algorithm in NGINX, an SSL certificate is required. Instructions for creating a self-signed certificate in this guide. If you prefer to use a certificate from an authority, a domain name or subdomain must be assigned to your Linode instance. Visit your domain name registrar's website, to assign a new record to your Linode instance's IP address. Your IP address is [displayed in the cloud manager](https://techdocs.akamai.com/cloud-computing/docs/managing-ip-addresses-on-a-compute-instance#viewing-ip-addresses). If you use the Linode DNS Manager, visit the [manage DNS records](https://techdocs.akamai.com/cloud-computing/docs/manage-domains) product documentation to view instructions for assigning a new A/AAAA record to your IP address. +1. To implement the algorithm in NGINX, a TLS certificate is required. When using a certificate from a public certificate authority, a domain name or subdomain must be assigned to your Linode instance. Visit your domain name registrar's website, to assign a new record to your Linode instance's IP address. Your IP address is [displayed in the cloud manager](https://techdocs.akamai.com/cloud-computing/docs/managing-ip-addresses-on-a-compute-instance#viewing-ip-addresses). If you use the Linode DNS Manager, visit the [manage DNS records](https://techdocs.akamai.com/cloud-computing/docs/manage-domains) product documentation to view instructions for assigning a new A/AAAA record to your IP address. 1. For an overview of how TLS encryption works, review the [Understanding TLS Certificates and Connections](/docs/guides/what-is-a-tls-certificate/) guide. @@ -71,13 +73,13 @@ Debian 11 comes with OpenSSL version `1.1.1w` by default, but the OQS provider r 1. Download the OpenSSL source code: ```command - wget https://github.com/openssl/openssl/releases/download/openssl-3.3.2/openssl-3.3.2.tar.gz + wget https://github.com/openssl/openssl/releases/download/openssl-3.4.0/openssl-3.4.0.tar.gz ``` 1. Download the corresponding signature file: ```command - wget https://github.com/openssl/openssl/releases/download/openssl-3.3.2/openssl-3.3.2.tar.gz.asc + wget https://github.com/openssl/openssl/releases/download/openssl-3.4.0/openssl-3.4.0.tar.gz.asc ``` ### Verify the OpenSSL Code Signature @@ -133,13 +135,13 @@ Before proceeding with the installation, verify the integrity and authenticity o 1. Finally, verify the OpenSSL source file against its signature: ```command - gpg --verify openssl-3.3.2.tar.gz.asc openssl-3.3.2.tar.gz + gpg --verify openssl-3.4.0.tar.gz.asc openssl-3.4.0.tar.gz ``` You should see a confirmation similar to the output below: ```output - gpg: Signature made Tue 03 Sep 2024 08:46:51 AM EDT + gpg: Signature made Tue 22 Oct 2024 12:27:03 PM UTC gpg: using RSA key BA5473A2B0587B07FB27CF2D216094DFD0CB81EF gpg: Good signature from "OpenSSL " [unknown] ``` @@ -163,13 +165,13 @@ After verifying the source code, the next step is to build OpenSSL from source. 1. Extract the downloaded OpenSSL archive: ```command - tar zxf openssl-3.3.2.tar.gz + tar zxf openssl-3.4.0.tar.gz ``` 1. Change into the extracted OpenSSL source directory: ```command - cd openssl-3.3.2 + cd openssl-3.4.0 ``` 1. Configure the OpenSSL build, specifying the installation path as `/opt` and setting the appropriate runtime library search path: @@ -207,7 +209,7 @@ After verifying the source code, the next step is to build OpenSSL from source. This should return the version number of the OpenSSL build you just installed to `/opt/bin`: ```output - OpenSSL 3.3.2 3 Sep 2024 (Library: OpenSSL 3.3.2 3 Sep 2024) + OpenSSL 3.4.0 22 Oct 2024 (Library: OpenSSL 3.4.0 22 Oct 2024) ``` 1. Now check the active version via the basic `openssl` command: @@ -373,11 +375,11 @@ A couple of dependencies must be installed prior to `oqs-provider`, along with G Providers: default name: OpenSSL Default Provider - version: 3.3.2 + version: 3.4.0 status: active oqsprovider name: OpenSSL OQS Provider - version: 0.6.2-dev + version: 0.7.1-dev status: active ``` @@ -396,13 +398,13 @@ The version of Nginx available for Debian 11 uses OpenSSL version `1.1.1w`. In o 1. Use `wget` to download the Nginx source files: ```command - wget https://nginx.org/download/nginx-1.26.2.tar.gz + wget https://nginx.org/download/nginx-1.27.2.tar.gz ``` 1. Also download the corresponding signature for verification: ```command - wget https://nginx.org/download/nginx-1.26.2.tar.gz.asc + wget https://nginx.org/download/nginx-1.27.2.tar.gz.asc ``` ### Verify the Signature @@ -422,13 +424,13 @@ The version of Nginx available for Debian 11 uses OpenSSL version `1.1.1w`. In o 1. Verify the signature: ```command - gpg --verify nginx-1.26.2.tar.gz.asc nginx-1.26.2.tar.gz + gpg --verify nginx-1.27.2.tar.gz.asc nginx-1.27.2.tar.gz ``` If verification succeeds, you should see output similar to the following: ```output - gpg: Signature made Tue 13 Aug 2024 08:48:05 AM EDT + gpg: Signature made Wed 02 Oct 2024 03:31:12 PM UTC gpg: using RSA key D6786CE303D9A9022998DC6CC8464D549AF75C0A gpg: issuer "s.kandaurov@f5.com" gpg: Good signature from "Sergey Kandaurov " [unknown] @@ -463,13 +465,13 @@ A couple of libraries are required before building Nginx: 1. Extract the source: ```command - tar zxf nginx-1.26.2.tar.gz + tar zxf nginx-1.27.2.tar.gz ``` 1. Change into the extracted source directory: ```command - cd nginx-1.26.2 + cd nginx-1.27.2 ``` 1. Configure the build with the necessary flags: @@ -583,7 +585,7 @@ A couple of libraries are required before building Nginx: ssl_protocols TLSv1.3; ssl_prefer_server_ciphers on; - ssl_ecdh_curve x25519_kyber768:p384_kyber768:x25519:secp384r1:x448:secp256r1:secp521r1; + ssl_ecdh_curve X25519MLKEM768:x25519_kyber768:p384_kyber768:x25519:secp384r1:x448:secp256r1:secp521r1; location / { try_files $uri $uri/ =404; @@ -656,7 +658,7 @@ Nginx should now be installed, configured, and running with OpenSSL 3.x support. Run the `openssl` command with the flags shown below: ```command -openssl s_client -groups x25519_kyber768 -connect localhost:443 +openssl s_client -groups X25519MLKEM768 -connect localhost:443 ``` -This command specifically checks for the `X25519_Kyber768` algorithm during a TLS connection. \ No newline at end of file +This command specifically checks for the `X25519_Kyber768` algorithm during a TLS connection. diff --git a/docs/guides/security/encryption/post-quantum-encryption-nginx-ubuntu2404/index.md b/docs/guides/security/encryption/post-quantum-encryption-nginx-ubuntu2404/index.md index 0b6cd598cc5..c1dd441fe3f 100644 --- a/docs/guides/security/encryption/post-quantum-encryption-nginx-ubuntu2404/index.md +++ b/docs/guides/security/encryption/post-quantum-encryption-nginx-ubuntu2404/index.md @@ -1,11 +1,11 @@ --- slug: post-quantum-encryption-nginx-ubuntu2404 title: "Post Quantum Encryption with NGINX on Ubuntu 24.04" -description: "Learn how to set up NGINX on Ubuntu 24.04 with support for the post-quantum cryptography X25519Kyber768Draft00 key exchange in TLS 1.3." -authors: ["Linode"] +description: "Learn how to set up NGINX on Ubuntu 24.04 with support for the post-quantum cryptography X25519Kyber768Draft00 / ML-KEM key exchange in TLS 1.3." +authors: ["Seweryn Krajczok", "Jan Schaumann"] contributors: ["Linode"] published: 2024-10-30 -keywords: ['X25519Kyber768Draft00','post-quantum cryptography','tls 1.3','cybersecurity','ubuntu 24.04','key exhange','OpenSSL','encryption','secure website'] +keywords: ['X25519Kyber768Draft00','X25519MLKEM768', 'ML-KEM','post-quantum cryptography','tls 1.3','cybersecurity','ubuntu 24.04','key exhange','OpenSSL','encryption','secure website'] license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' external_resources: - '[Open Quantum Safe](https://openquantumsafe.org/)' @@ -20,7 +20,7 @@ relations: 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 how to deploy this algorithm with NGINX on Ubuntu 24.04. The [Open Quantum Safe (OQS) provider](https://github.com/open-quantum-safe/oqs-provider) for OpenSSL is built to enable the post quantum encryption algorithm. After it is configured for the web server, several ways to verify that the server is using the algorithm are demonstrated. +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 how to deploy this algorithm with NGINX on Ubuntu 24.04, using the [Open Quantum Safe (OQS) provider](https://github.com/open-quantum-safe/oqs-provider) for OpenSSL, which is used to enable the post quantum encryption algorithm. After it is configured for the web server, several ways to verify that the server is using the algorithm are demonstrated. ## Before You Begin @@ -28,7 +28,7 @@ Deploying this algorithm for your web server currently requires some additional 1. Follow the [Set up and secure a Compute Instance](https://techdocs.akamai.com/cloud-computing/docs/set-up-and-secure-a-compute-instance) product documentation to appropriately secure your system. -1. To implement the algorithm in NGINX, an SSL certificate is required. Instructions for creating a self-signed certificate in this guide. If you prefer to use a certificate from an authority, a domain name or subdomain must be assigned to your Linode instance. Visit your domain name registrar's website, to assign a new record to your Linode instance's IP address. Your IP address is [displayed in the cloud manager](https://techdocs.akamai.com/cloud-computing/docs/managing-ip-addresses-on-a-compute-instance#viewing-ip-addresses). If you use the Linode DNS Manager, visit the [manage DNS records](https://techdocs.akamai.com/cloud-computing/docs/manage-domains) product documentation to view instructions for assigning a new A/AAAA record to your IP address. +1. To implement the algorithm in NGINX, a TLS certificate is required. When using a certificate from a public certificate authority, a domain name or subdomain must be assigned to your Linode instance. Visit your domain name registrar's website, to assign a new record to your Linode instance's IP address. Your IP address is [displayed in the cloud manager](https://techdocs.akamai.com/cloud-computing/docs/managing-ip-addresses-on-a-compute-instance#viewing-ip-addresses). If you use the Linode DNS Manager, visit the [manage DNS records](https://techdocs.akamai.com/cloud-computing/docs/manage-domains) product documentation to view instructions for assigning a new A/AAAA record to your IP address. 1. For an overview of how TLS encryption works, review the [Understanding TLS Certificates and Connections](/docs/guides/what-is-a-tls-certificate/) guide. @@ -74,20 +74,6 @@ If OpenSSL 3.x+ is already installed, go to the "Install the oqs-provider" step. ## Update OpenSSL -1. Check if you have already installed OpenSSL >= 3.x: - - ```command - openssl version - ``` - - This should generate output like: - - ```output - OpenSSL 3.0.13 30 Jan 2024 (Library: OpenSSL 3.0.13 30 Jan 2024) - ``` - - If OpenSSL 3.x+ is already installed, skip to the [Install oqs-provider](#install-oqs-provider) section. - 1. Update OpenSSL from Ubuntu repositories: ```command @@ -195,7 +181,7 @@ Providers: status: active oqsprovider name: OpenSSL OQS Provider - version: 0.6.2-dev + version: 0.7.1-dev status: active ``` @@ -204,22 +190,22 @@ Providers: Run: ```command -openssl list -kem-algorithms -provider oqsprovider | grep kyber +openssl list -kem-algorithms -provider oqsprovider | egrep -i "(kyber|kem)768" ``` Output should resemble: ```output -kyber512 @ oqsprovider -p256_kyber512 @ oqsprovider -x25519_kyber512 @ oqsprovider -kyber768 @ oqsprovider -p384_kyber768 @ oqsprovider -x448_kyber768 @ oqsprovider -x25519_kyber768 @ oqsprovider -p256_kyber768 @ oqsprovider -kyber1024 @ oqsprovider -p521_kyber1024 @ oqsprovider + kyber768 @ oqsprovider + p384_kyber768 @ oqsprovider + x448_kyber768 @ oqsprovider + x25519_kyber768 @ oqsprovider + p256_kyber768 @ oqsprovider + mlkem768 @ oqsprovider + p384_mlkem768 @ oqsprovider + x448_mlkem768 @ oqsprovider + X25519MLKEM768 @ oqsprovider + SecP256r1MLKEM768 @ oqsprovider ``` ## Set Up NGINX @@ -260,12 +246,6 @@ Ensure that you include the necessary certificates (whether self-signed or from sudo nano /etc/nginx/nginx.conf ``` - Add the following line to the top of the file to specify the user: - - ```file {title="/etc/nginx/nginx.conf"} - user www-data; #add this to the top of the file - ``` - 1. Locate the `http` block and add the highlighted lines to include configuration files in the `/etc/nginx/nginx.conf` directory: ```file {title="/etc/nginx/nginx.conf" hl_lines="2,3" linenostart="18"} @@ -297,7 +277,7 @@ Ensure that you include the necessary certificates (whether self-signed or from ssl_certificate_key /opt/certs/pqc.key; ssl_protocols TLSv1.3; ssl_prefer_server_ciphers on; - ssl_ecdh_curve x25519_kyber768:p384_kyber768:x25519:secp384r1:x448:secp256r1:secp521r1; + ssl_ecdh_curve X25519MLKEM768:x25519_kyber768:p384_kyber768:x25519:secp384r1:x448:secp256r1:secp521r1; location / { try_files $uri $uri/ =404; } @@ -330,9 +310,9 @@ openssl s_client -groups x25519_kyber768 -connect localhost:443 1. Open Chrome and navigate to [chrome://flags](chrome://flags). - 1. In the search bar, enter `TLS 1.3 hybridized Kyber`. + 1. In the search bar, enter `TLS 1.3 post-quantum key agreement`. - 1. Toggle the option to Enabled for `TLS 1.3 hybridized Kyber support`. + 1. Toggle the option to Enabled for `#enable-tls13-kyber` or `#use-ml-kem`. - Firefox: @@ -425,6 +405,8 @@ These steps create an index.php page on your web server that displays informatio if ($ssl_curve === '0x6399') { echo "

You are using X25519Kyber768Draft00 which is post-quantum secure.

"; + } elsif ($ssl_curve === '0x4588') { + echo "

You are using X25519MLKEM768, which is post-quantum secure.

"; } else { echo "

You are using SSL Curve: {$ssl_curve} which is not post-quantum secure.

"; } @@ -440,24 +422,6 @@ These steps create an index.php page on your web server that displays informatio sudo systemctl reload nginx ``` -1. Enable Kyber support in either Google Chrome or Mozilla Firefox: - - - Chrome: - - 1. Open Chrome and navigate to [chrome://flags](chrome://flags). - - 1. In the search bar, enter `TLS 1.3 hybridized Kyber`. - - 1. Toggle the option to Enabled for `TLS 1.3 hybridized Kyber support`. - - - Firefox: - - 1. Open Chrome and navigate to [about:config](about:config). - - 1. In the search bar, enter `security.tls.enable_kyber`. - - 1. Toggle the option to True for `security.tls.enable_kyber`. - 1. Visit your website in your browser. If Kyber support is enabled in your browser, and if the TLS handshake with the web server uses the algorithm, you should see: ```output @@ -473,11 +437,11 @@ These steps create an index.php page on your web server that displays informatio {{< note >}} Remember that currently not all browsers support post-quantum algorithms. These browsers offer compatibility: -- Enabled by default for Chrome 124+ on Desktop. For older Chrome versions or on mobile, you need to toggle `TLS 1.3 hybridized Kyber support` in [chrome://flags](chrome://flags). +- Enabled by default for Chrome 124+ on Desktop. For older Chrome versions or on mobile, you need to toggle `TLS 1.3 post-quantum key agreement` / `#use-ml-kem` in [chrome://flags](chrome://flags). - Enabled by default for Edge 124+. - Enabled by default for recent Opera and Brave. - Enabled for Firefox 124+ if you turn on `security.tls.enable_kyber` in [about:config](about:config). Firefox 128+: turn on `network.http.http3.enable_kyber` for QUIC/HTTP3. -{{< /note >}} \ No newline at end of file +{{< /note >}} From f7039f484f704714e0b190963fbe301f3b697840 Mon Sep 17 00:00:00 2001 From: Nathan Melehan Date: Tue, 5 Nov 2024 21:23:52 -0500 Subject: [PATCH 10/11] Update contributors/authors frontmatter and add contributor pages --- docs/contributors/jan-schaumann/_index.md | 6 ++++++ docs/contributors/seweryn-krajczok/_index.md | 6 ++++++ .../post-quantum-encryption-nginx-debian11/index.md | 2 +- .../post-quantum-encryption-nginx-ubuntu2404/index.md | 2 +- 4 files changed, 14 insertions(+), 2 deletions(-) create mode 100644 docs/contributors/jan-schaumann/_index.md create mode 100644 docs/contributors/seweryn-krajczok/_index.md diff --git a/docs/contributors/jan-schaumann/_index.md b/docs/contributors/jan-schaumann/_index.md new file mode 100644 index 00000000000..bf2cd50cff5 --- /dev/null +++ b/docs/contributors/jan-schaumann/_index.md @@ -0,0 +1,6 @@ +--- +title: "Jan Schaumann" +link: "" +email: "" +description: "The Linode documentation library's profile page and submission listing for Jan Schaumann" +--- \ No newline at end of file diff --git a/docs/contributors/seweryn-krajczok/_index.md b/docs/contributors/seweryn-krajczok/_index.md new file mode 100644 index 00000000000..097e762f85a --- /dev/null +++ b/docs/contributors/seweryn-krajczok/_index.md @@ -0,0 +1,6 @@ +--- +title: "Seweryn Krajczok" +link: "" +email: "" +description: "The Linode documentation library's profile page and submission listing for Seweryn Krajczok" +--- \ No newline at end of file diff --git a/docs/guides/security/encryption/post-quantum-encryption-nginx-debian11/index.md b/docs/guides/security/encryption/post-quantum-encryption-nginx-debian11/index.md index 9b40918f7b4..9350ffc2777 100644 --- a/docs/guides/security/encryption/post-quantum-encryption-nginx-debian11/index.md +++ b/docs/guides/security/encryption/post-quantum-encryption-nginx-debian11/index.md @@ -3,7 +3,7 @@ slug: post-quantum-encryption-nginx-debian11 title: "Post Quantum Encryption with NGINX on Debian 11" description: "Learn how to set up a Debian 11 Nginx web server with support for the post-quantum cryptography X25519Kyber768Draft00 / ML-KEM key exchange in TLS 1.3." authors: ["Seweryn Krajczok", "Jan Schaumann"] -contributors: ["Linode"] +contributors: ["Seweryn Krajczok", "Jan Schaumann"] published: 2024-11-05 keywords: ['X25519Kyber768Draft00','X25519MLKEM768', 'ML-KEM', '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)' diff --git a/docs/guides/security/encryption/post-quantum-encryption-nginx-ubuntu2404/index.md b/docs/guides/security/encryption/post-quantum-encryption-nginx-ubuntu2404/index.md index c1dd441fe3f..70cd750841e 100644 --- a/docs/guides/security/encryption/post-quantum-encryption-nginx-ubuntu2404/index.md +++ b/docs/guides/security/encryption/post-quantum-encryption-nginx-ubuntu2404/index.md @@ -3,7 +3,7 @@ slug: post-quantum-encryption-nginx-ubuntu2404 title: "Post Quantum Encryption with NGINX on Ubuntu 24.04" description: "Learn how to set up NGINX on Ubuntu 24.04 with support for the post-quantum cryptography X25519Kyber768Draft00 / ML-KEM key exchange in TLS 1.3." authors: ["Seweryn Krajczok", "Jan Schaumann"] -contributors: ["Linode"] +contributors: ["Seweryn Krajczok", "Jan Schaumann"] published: 2024-10-30 keywords: ['X25519Kyber768Draft00','X25519MLKEM768', 'ML-KEM','post-quantum cryptography','tls 1.3','cybersecurity','ubuntu 24.04','key exhange','OpenSSL','encryption','secure website'] license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' From dd25a14004f50e751a2d94ed53166da22817bf78 Mon Sep 17 00:00:00 2001 From: Nathan Melehan Date: Tue, 5 Nov 2024 23:52:21 -0500 Subject: [PATCH 11/11] Copy edits --- .../post-quantum-encryption-nginx-debian11/index.md | 10 ++++++---- .../post-quantum-encryption-nginx-ubuntu2404/index.md | 2 +- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/guides/security/encryption/post-quantum-encryption-nginx-debian11/index.md b/docs/guides/security/encryption/post-quantum-encryption-nginx-debian11/index.md index 9350ffc2777..d98974fa44d 100644 --- a/docs/guides/security/encryption/post-quantum-encryption-nginx-debian11/index.md +++ b/docs/guides/security/encryption/post-quantum-encryption-nginx-debian11/index.md @@ -22,7 +22,9 @@ The National Institute of Standards and Technology (NIST) recently [released](ht 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 how to deploy this algorithm with NGINX on Debian 11, using the [Open Quantum Safe (OQS) provider](https://github.com/open-quantum-safe/oqs-provider) for OpenSSL, which is used to enable the post quantum encryption algorithm. -_Note_: we chose Debian 11 here to illustrate the process of building OpenSSL and NGINX from sources. See [this guide](/docs/guides/security/encryption/post-quantum-encryption-nginx-ubuntu2404/) for a document guiding you through the setup on an Ubuntu 24.04 system instead. +{{< note >}} +On Debian 11, the versions of OpenSSL and NGINX available from apt are not compatible with post quantum encryption, so this guide shows how to build them from source instead. On Ubuntu 24.04, post quantum encryption-compatible versions are available through apt, and [this guide](/docs/guides/post-quantum-encryption-nginx-ubuntu2404/) describes how to configure the encryption algorithm on that distribution. +{{< /note >}} ## Before You Begin @@ -30,7 +32,7 @@ _Note_: we chose Debian 11 here to illustrate the process of building OpenSSL an 1. Follow the [Set up and secure a Compute Instance](https://techdocs.akamai.com/cloud-computing/docs/set-up-and-secure-a-compute-instance) product documentation to appropriately secure your system. -1. To implement the algorithm in NGINX, a TLS certificate is required. When using a certificate from a public certificate authority, a domain name or subdomain must be assigned to your Linode instance. Visit your domain name registrar's website, to assign a new record to your Linode instance's IP address. Your IP address is [displayed in the cloud manager](https://techdocs.akamai.com/cloud-computing/docs/managing-ip-addresses-on-a-compute-instance#viewing-ip-addresses). If you use the Linode DNS Manager, visit the [manage DNS records](https://techdocs.akamai.com/cloud-computing/docs/manage-domains) product documentation to view instructions for assigning a new A/AAAA record to your IP address. +1. To implement the algorithm in NGINX, a TLS certificate is required. When using a certificate from a public certificate authority, a domain name or subdomain must be assigned to your Linode instance. Visit your domain name registrar's website to assign a new record to your Linode instance's IP address. Your IP address is [displayed in the cloud manager](https://techdocs.akamai.com/cloud-computing/docs/managing-ip-addresses-on-a-compute-instance#viewing-ip-addresses). If you use the Linode DNS Manager, visit the [manage DNS records](https://techdocs.akamai.com/cloud-computing/docs/manage-domains) product documentation to view instructions for assigning a new A/AAAA record to your IP address. 1. For an overview of how TLS encryption works, review the [Understanding TLS Certificates and Connections](/docs/guides/what-is-a-tls-certificate/) guide. @@ -256,10 +258,10 @@ Adjust your `PATH` environment variable to prioritize the `/opt/bin` directory. openssl version ``` - The output should now show version `3.3.2`, which you installed in `/opt/bin`: + The output should now show version `3.4.0`, which you installed in `/opt/bin`: ```output - OpenSSL 3.3.2 3 Sep 2024 (Library: OpenSSL 3.3.2 3 Sep 2024) + OpenSSL 3.4.0 3 Sep 2024 (Library: OpenSSL 3.4.0 3 Sep 2024) ``` ## Install `oqs-provider` diff --git a/docs/guides/security/encryption/post-quantum-encryption-nginx-ubuntu2404/index.md b/docs/guides/security/encryption/post-quantum-encryption-nginx-ubuntu2404/index.md index 70cd750841e..d9d5c825a10 100644 --- a/docs/guides/security/encryption/post-quantum-encryption-nginx-ubuntu2404/index.md +++ b/docs/guides/security/encryption/post-quantum-encryption-nginx-ubuntu2404/index.md @@ -28,7 +28,7 @@ Deploying this algorithm for your web server currently requires some additional 1. Follow the [Set up and secure a Compute Instance](https://techdocs.akamai.com/cloud-computing/docs/set-up-and-secure-a-compute-instance) product documentation to appropriately secure your system. -1. To implement the algorithm in NGINX, a TLS certificate is required. When using a certificate from a public certificate authority, a domain name or subdomain must be assigned to your Linode instance. Visit your domain name registrar's website, to assign a new record to your Linode instance's IP address. Your IP address is [displayed in the cloud manager](https://techdocs.akamai.com/cloud-computing/docs/managing-ip-addresses-on-a-compute-instance#viewing-ip-addresses). If you use the Linode DNS Manager, visit the [manage DNS records](https://techdocs.akamai.com/cloud-computing/docs/manage-domains) product documentation to view instructions for assigning a new A/AAAA record to your IP address. +1. To implement the algorithm in NGINX, a TLS certificate is required. When using a certificate from a public certificate authority, a domain name or subdomain must be assigned to your Linode instance. Visit your domain name registrar's website to assign a new record to your Linode instance's IP address. Your IP address is [displayed in the cloud manager](https://techdocs.akamai.com/cloud-computing/docs/managing-ip-addresses-on-a-compute-instance#viewing-ip-addresses). If you use the Linode DNS Manager, visit the [manage DNS records](https://techdocs.akamai.com/cloud-computing/docs/manage-domains) product documentation to view instructions for assigning a new A/AAAA record to your IP address. 1. For an overview of how TLS encryption works, review the [Understanding TLS Certificates and Connections](/docs/guides/what-is-a-tls-certificate/) guide.