diff --git a/docs/README.adoc b/docs/README.adoc index 1f6d797df..483641980 100644 --- a/docs/README.adoc +++ b/docs/README.adoc @@ -35,6 +35,12 @@ link:../[Return to Project Root] * link:common/create-and-configure-gateways.adoc#creating-and-configuring-gateways[Creating and Configuring Gateways] ** link:common/create-and-configure-gateways.adoc#option-1-istio-gateway-injection[Option 1: Istio Gateway Injection] ** link:common/create-and-configure-gateways.adoc#option-2-kubernetes-gateway-api[Option 2: Kubernetes Gateway API] +* link:common/quantum-secure-gateway.adoc#quantum-secure-gateway[Quantum-Secure Gateway] +** link:common/quantum-secure-gateway.adoc#introduction-to-post-quantum-cryptography[Introduction to Post-Quantum Cryptography] +** link:common/quantum-secure-gateway.adoc#prerequisites[Prerequisites] +** link:common/quantum-secure-gateway.adoc#customize-istio-proxy-image[Customize istio-proxy Image] +** link:common/quantum-secure-gateway.adoc#install-service-mesh[Install Service Mesh] +** link:common/quantum-secure-gateway.adoc#verification-steps[Verification Steps] * link:update-strategy/update-strategy.adoc#update-strategy[Update Strategy] ** link:update-strategy/update-strategy.adoc#inplace[InPlace] *** link:update-strategy/update-strategy.adoc#example-using-the-inplace-strategy[Example using the InPlace strategy] diff --git a/docs/common/quantum-secure-gateway.adoc b/docs/common/quantum-secure-gateway.adoc new file mode 100644 index 000000000..6a741b800 --- /dev/null +++ b/docs/common/quantum-secure-gateway.adoc @@ -0,0 +1,441 @@ +// Variables embedded for GitHub compatibility +:istio_latest_version: 1.26.3 +:istio_latest_version_revision_format: 1-26-3 +:istio_latest_tag: v1.26-latest +:istio_latest_minus_one_version: 1.26.2 +:istio_latest_minus_one_version_revision_format: 1-26-2 + +link:../README.adoc[Return to Project Root] + +== Table of Contents + +* <> +** <> +** <> +** <> +* <> +** <> +** <> +** <> +** <> + +[[introduction-to-post-quantum-cryptography]] +== Introduction to Post-Quantum Cryptography + +[[what-is-post-quantum-cryptography]] +=== What is Post-Quantum Cryptography? + +Post-Quantum Cryptography (PQC) refers to cryptographic algorithms that are designed to be secure against attacks by both classical and quantum computers. As quantum computing technology advances, traditional cryptographic methods like RSA, ECDSA, and ECDH become vulnerable to quantum attacks, particularly through algorithms like Shor's algorithm, which can efficiently factor large integers and solve discrete logarithm problems. + +PQC algorithms are based on mathematical problems that are believed to be hard for both classical and quantum computers to solve, such as: + +* **Lattice-based cryptography**: Based on problems like Learning With Errors (LWE) +* **Code-based cryptography**: Based on error-correcting codes +* **Multivariate cryptography**: Based on solving systems of multivariate polynomial equations +* **Hash-based signatures**: Based on the security of cryptographic hash functions +* **Isogeny-based cryptography**: Based on walks in supersingular isogeny graphs + +[[quantum-threat-to-current-cryptography]] +=== The Quantum Threat to Current Cryptography + +The development of large-scale quantum computers poses a significant threat to current cryptographic systems: + +1. **Shor's Algorithm**: Can efficiently factor large integers and compute discrete logarithms, breaking RSA, ECDSA, and ECDH +2. **Grover's Algorithm**: Provides a quadratic speedup for searching unsorted databases, effectively halving the security level of symmetric cryptographic algorithms +3. **Timeline Concerns**: While large-scale quantum computers don't exist today, experts estimate they could become reality within 10-30 years + +Organizations need to start preparing now because: + +* **Harvest Now, Decrypt Later**: Adversaries may be collecting encrypted data today to decrypt it once quantum computers become available +* **Migration Complexity**: Transitioning to post-quantum cryptography requires significant planning and testing +* **Compliance Requirements**: Various standards bodies and governments are beginning to mandate PQC readiness + +[[pqc-algorithms-and-standards]] +=== PQC Algorithms and Standards + +The U.S. National Institute of Standards and Technology (NIST) has been leading the standardization of post-quantum cryptographic algorithms. In 2022, NIST published the first set of PQC standards: + +**Key Encapsulation Mechanisms (KEMs):** +* **CRYSTALS-KYBER (ML-KEM)**: A lattice-based algorithm for key establishment +* **X25519MLKEM768**: A hybrid approach combining traditional X25519 with ML-KEM-768 + +**Digital Signatures:** +* **CRYSTALS-DILITHIUM (ML-DSA)**: A lattice-based signature algorithm +* **FALCON**: A lattice-based signature algorithm optimized for smaller signatures +* **SPHINCS+**: A hash-based signature algorithm + +The hybrid approach (like X25519MLKEM768) is particularly important during the transition period, as it provides security against both classical and quantum attacks while maintaining compatibility with existing systems. + +[[quantum-secure-gateway]] +== Quantum-Secure Gateway + +The Quantum-Secure Gateway feature in Sail Operator enables you to configure Istio gateways with post-quantum cryptographic algorithms, providing protection against both current and future quantum computer attacks. This implementation uses hybrid key exchange mechanisms that combine traditional cryptography with post-quantum algorithms. + +[[prerequisites]] +=== Prerequisites + +Before setting up a Quantum-Secure Gateway, ensure you have the following: + +1. OpenShift Service Mesh Operator 3.1+ installed in your cluster +2. Gateway API CRDs (available by default on OpenShift Container Platform 4.19+): ++ +[source,shell] +---- +oc apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.3.0/standard-install.yaml +---- + +3. Access to build and push container images to your cluster's image registry +4. Basic understanding of Istio gateways and service mesh concepts + +[[customize-istio-proxy-image]] +=== Customize istio-proxy Image + +OpenShift Service Mesh 3.1 delivers an istio-proxy image built with OpenSSL 3.2 that supports Post-Quantum Cryptography algorithms through the [OQS (Open Quantum Safe) provider](https://github.com/open-quantum-safe/oqs-provider). +However, RHEL 9.6 does not currently provide the OQS provider package, so users must build and integrate it manually into their proxy images. +Future versions of OpenShift Service Mesh will ship with an updated a newer version of OpenSSL with built-in support for PQC algorithms. This will remove the need for users to manually build and integrate the OQS provider, simplifying the deployment of quantum-secure gateways. Users will be able to leverage hybrid and PQC-only cryptographic algorithms in their gateways without requiring custom proxy images or manual OpenSSL configuration. + +Until these future releases become generally available, follow the steps below to build your own quantum-safe istio-proxy image. + +[NOTE] +==== +Post-Quantum Cryptography algorithms will be available out-of-the-box in future releases of OpenShift Service Mesh, eliminating the need for custom proxy images. +==== + +To enable post-quantum safe algorithms in the current release, you need to create a custom istio-proxy image with the OQS provider configured. + +==== Build Custom Proxy Image + +1. Create the Dockerfile for the custom proxy image with OQS provider support: ++ +[source,dockerfile] +---- +FROM docker.io/redhat/ubi9:9.6 AS builder + +ARG LIBOQS_TAG=0.12.0 +ARG OQSPROVIDER_TAG=0.8.0 +ARG INSTALLDIR_OPENSSL=/usr/lib64 +ARG INSTALLDIR_LIBOQS=/opt/liboqs + +RUN dnf install -y git make cmake ninja-build +RUN dnf install -y openssl-devel +RUN dnf install -y gcc gcc-c++ + +WORKDIR /optbuild +RUN git clone --depth 1 --branch ${LIBOQS_TAG} https://github.com/open-quantum-safe/liboqs + +WORKDIR /optbuild/liboqs/build +RUN cmake -G "Ninja" .. \ + -DOPENSSL_ROOT_DIR=${INSTALLDIR_OPENSSL} \ + -DCMAKE_INSTALL_PREFIX=${INSTALLDIR_LIBOQS} && \ + ninja install + +WORKDIR /optbuild +RUN git clone --depth 1 --branch ${OQSPROVIDER_TAG} https://github.com/open-quantum-safe/oqs-provider.git + +WORKDIR /optbuild/oqs-provider +RUN liboqs_DIR=${INSTALLDIR_LIBOQS} cmake \ + -DOPENSSL_ROOT_DIR=${INSTALLDIR_OPENSSL} \ + -DCMAKE_BUILD_TYPE=Release \ + -DCMAKE_PREFIX_PATH=${INSTALLDIR_OPENSSL} \ + -S . -B _build && \ + cmake --build _build && \ + cmake --install _build && \ + cp _build/lib/oqsprovider.so ${INSTALLDIR_OPENSSL}/ossl-modules + +FROM registry.redhat.io/openshift-service-mesh/istio-proxyv2-rhel9:1.26.2 AS final + +ARG INSTALLDIR_OPENSSL=/usr/lib64 +ARG INSTALLDIR_LIBOQS=/opt/liboqs + +COPY --from=builder ${INSTALLDIR_LIBOQS} ${INSTALLDIR_LIBOQS} +COPY --from=builder ${INSTALLDIR_OPENSSL}/ossl-modules ${INSTALLDIR_OPENSSL}/ossl-modules + +USER root +RUN sed '/^default = default_sect$/a oqsprovider = oqsprovider_sect' /etc/pki/tls/openssl.cnf > /tmp/openssl.cnf && \ + printf "\n[oqsprovider_sect]\n" >> /tmp/openssl.cnf && \ + echo "module = /usr/lib64/ossl-modules/oqsprovider.so" >> /tmp/openssl.cnf && \ + echo "activate = 1" >> /tmp/openssl.cnf && \ + cp /tmp/openssl.cnf /etc/pki/tls/openssl.cnf +USER 1000 +---- + +2. Extract pull secret from OpenShift and build the proxy image with OQS provider: ++ +[source,shell] +---- +oc get secret pull-secret -n openshift-config -o jsonpath='{.data.\.dockerconfigjson}' | base64 -d > /tmp/config.json +podman --config /tmp build -t localhost:5000/istio-system/istio-proxyv2-rhel9-oqs:1.26.2 . +---- + +2. Configure permissions for pushing images to the OpenShift image registry: ++ +[source,shell] +---- +oc new-project istio-system +oc policy add-role-to-user system:image-pusher -z default -n istio-system +TOKEN=$(oc create token default -n istio-system) +---- + +3. Create an image stream for the custom istio-proxy and expose the registry: ++ +[source,shell] +---- +oc patch configs.imageregistry.operator.openshift.io/cluster --type=merge -p '{"spec":{"defaultRoute":true}}' +oc create imagestream istio-proxyv2-rhel9-oqs -n istio-system +---- + +4. Push the custom image to the OpenShift registry: ++ +[source,shell] +---- +HOST=$(oc get route default-route -n openshift-image-registry -o jsonpath='{.spec.host}') +podman login --tls-verify=false -u default -p $TOKEN $HOST +podman push --tls-verify=false istio-proxyv2-rhel9-oqs:1.26.2 $HOST/istio-system/istio-proxyv2-rhel9-oqs:1.26.2 +---- + +==== Understanding the Custom Image + +The custom proxy image is built using a multi-stage Dockerfile that: + +1. Builds OQS libraries (liboqs and oqs-provider). +2. Configures OpenSSL to use OQS provider. + +[[install-service-mesh]] +=== Install Service Mesh + +==== Install CNI + +First, install the Istio CNI component: + +[source,shell] +---- +oc new-project istio-cni +oc apply -f - <