Configure post-quantum TLS¶
As quantum computing becomes a reality, traditional public key algorithms like RSA and ECC grow increasingly vulnerable. WSO2 Identity Server mitigates this issue by supporting Post-Quantum Cryptography (PQC) through hybrid key exchange algorithms, specifically the X25519MLKEM768 hybrid key agreement algorithm.
A hybrid key agreement algorithm combines a classical algorithm with a post-quantum algorithm to establish a shared secret. This approach keeps communication secure even if one algorithm is compromised, helping systems transition seamlessly to post-quantum cryptography.
By following this guide, you will enable post-quantum TLS in WSO2 Identity Server for inbound connections. An inbound connection refers to communication initiated by clients, such as browsers, applications, or APIs, connecting securely to WSO2 Identity Server using TLS.
Post-quantum TLS requirements
- Post-quantum TLS is only supported over TLS 1.3.
- WSO2 Identity Server currently supports post-quantum security only on Linux and MacOS operating systems.
Step 1: Build native libraries¶
For post-quantum TLS to work, WSO2 Identity Server requires a few native libraries. These don't come pre-packaged with the WSO2 Identity Server distribution as native libraries depend on the system architecture.
Use one of the following methods to build native libraries.
Method 1: Use system libraries¶
This method relies on your operating system’s existing libraries during both the build process and runtime. This results in a faster build time and minimal disk space usage.
Build dependencies
WSO2 Identity Server requires the following during the build process.
- Build tools (
make
,cmake
,wget
,tar
,autoconf
) - GNU compiler (
gcc
) - Apache Portable Runtime (APR) library
- OpenSSL 3.0 or higher.
To install these dependencies, follow the instructions below based on the operating system.
-
Install the required build dependencies using the command for your relevant Linux distribution.
In Debian-based Linux:
apt-get install make cmake autoconf wget tar gcc libapr1-dev libssl-dev
In Red Hat Linux distributions:
yum install make cmake autoconf wget tar gcc apr-devel openssl-devel perl
-
Use Homebrew to install all the required build dependencies.
brew install wget cmake autoconf openssl@3 apr
-
Add the following line to your shell configuration file (e.g.,
~/.bash_profile
,~/.zshrc
, or~/.bashrc
):For Intel-based Macs:
export PATH="/usr/local/opt/apr/bin:$PATH"
For Apple Silicon-based Macs:
export PATH="/opt/homebrew/opt/apr/bin:$PATH"
Runtime dependencies
WSO2 Identity Server requires the following during runtime.
-
The OpenSSL and APR libraries installed earlier.
-
Install the other dependencies by following the steps below:
- Shut down the WSO2 Identity Server instance if running.
-
Navigate to the
<IS_HOME>/bin/
folder and execute the following command:sh openssl-tls.sh --build_pqclib
Note
If you change the location of the WSO2 Identity Server folder, you need to re-run the above command to reconfigure the runtime libraries.
Method 2: Using self-contained libraries¶
This method installs all dependencies into the WSO2 Identity Server directory, ensuring isolation from the system environment and highest compatibility across different systems and configurations.
Build dependencies
WSO2 Identity Server requires the following during the build process.
- Build tools (
make
,cmake
,wget
,tar
,autoconf
) - GNU compiler (
gcc
/clang
)
To install these dependencies, follow the instructions below based on the operating system.
Install the required build dependencies using the command for your relevant Linux distribution.
In Debian-based Linux:
apt-get install make cmake autoconf wget tar gcc git python3 autoconf libtool-bin
In Red Hat Linux distributions:
yum install make cmake autoconf wget tar gcc perl git python3 autoconf libtool
Use Homebrew to install dependencies.
brew install wget autoconf cmake git python3 autoconf libtool
Runtime dependencies
WSO2 Identity Server requires the following during runtime.
- Shut down the WSO2 Identity Server instance if running.
-
Navigate to the
<IS_HOME>/bin/
folder and execute the following command:sh openssl-tls.sh --build_openssl --build_pqclib
Note
If you change the location of the WSO2 Identity Server folder, you need to re-run the above command to reconfigure the runtime libraries.
Step 2: Enable post-quantum TLS¶
Follow the steps below to enable TLS to use post-quantum cryptography.
- Shut down the WSO2 Identity Server instance if running.
-
Add the following configuration to the
<IS_HOME>/repository/conf/deployment.toml
file.[transport.https.openssl] enabled = true named_groups="X25519MLKEM768:x25519" [transport.https.sslHostConfig.properties] protocols="TLSv1+TLSv1.1+TLSv1.2+TLSv1.3"
-
Restart WSO2 Identity Server.
Disable post-quantum security
Make the following changes to the <IS_HOME>/repository/conf/deployment.toml
file to disable post-quantum security.
-
Remove the configurations you added when enabling it and restart WSO2 Identity Server.
-
You can keep using TLS 1.3 with post-quantum security disabled by adding the following configuration.
[transport.https.openssl] enabled = true [transport.https.sslHostConfig.properties] protocols="TLSv1+TLSv1.1+TLSv1.2+TLSv1.3"