HAproxy

.circleci/config.yml

@@ -53,6 +53,15 @@ jobs:
             sleep 2 &&
             docker run --network httpd-test oqs-curl curl -k https://oqs-httpd:4433
           working_directory: httpd
+      - run:
+          name: Test HAproxy
+          command: |
+            docker build --build-arg MAKE_DEFINES="-j 18" -t oqs-haproxy-img . &&
+            docker network create haproxy-test &&
+            docker run --network haproxy-test --detach --rm --name oqs-haproxy oqs-haproxy-img &&
+            sleep 4 &&
+            docker run --network haproxy-test oqs-curl curl -k https://oqs-haproxy:4433
+          working_directory: haproxy
       - run:
           name: Test nginx
           command: |
@@ -79,6 +88,8 @@ jobs:
                   docker push $TARGETNAME/curl-dev &&
                   docker tag oqs-httpd-img $TARGETNAME/httpd:latest &&
                   docker push $TARGETNAME/httpd:latest &&
+                  docker tag oqs-haproxy-img $TARGETNAME/haproxy:latest &&
+                  docker push $TARGETNAME/haproxy:latest &&
                   docker tag oqs-nginx-img $TARGETNAME/nginx:latest &&
                   docker push $TARGETNAME/nginx:latest
 

README.md

@@ -15,5 +15,6 @@ Currently supported packages:
 | **Apache httpd** | [Github: oqs-demos/httpd](httpd)       | [Dockerhub: openquantumsafe/httpd](https://hub.docker.com/repository/docker/openquantumsafe/httpd)                           |
 | **nginx**        | [Github: oqs-demos/nginx](nginx)       | [Dockerhub: openquantumsafe/nginx](https://hub.docker.com/repository/docker/openquantumsafe/nginx)                           |
 | **Chromium**     | [Github: oqs-demos/chromium](chromium) | [Binary for Ubuntu 18.04](https://github.com/open-quantum-safe/oqs-demos/releases/download/v0.4.0/chromium-ubuntu-0.4.0.tgz) |
+| **HAproxy**        | [Github: oqs-demos/haproxy](haproxy)       | [Dockerhub: openquantumsafe/haproxy](https://hub.docker.com/repository/docker/openquantumsafe/haproxy)                           |
 
 You can use the curl and Chromium clients with the Open Quantum Safe test server at https://test.openquantumsafe.org/.

curl/Dockerfile

@@ -50,7 +50,7 @@ RUN git clone --depth 1 --branch main https://github.com/open-quantum-safe/liboq
 # build liboqs shared and static
 WORKDIR /opt/liboqs
 RUN mkdir build && cd build && cmake -G"Ninja" .. ${LIBOQS_BUILD_DEFINES} -DBUILD_SHARED_LIBS=ON -DCMAKE_INSTALL_PREFIX=/opt/ossl-src/oqs && ninja install
-RUN mkdir build-static && cd build-static && cmake -G"Ninja" .. -DCMAKE_BUILD_TYPE=${LIBOQS_BUILD_TYPE} -DBUILD_SHARED_LIBS=OFF -DCMAKE_INSTALL_PREFIX=/opt/ossl-src/oqs && ninja install
+RUN mkdir build-static && cd build-static && cmake -G"Ninja" .. ${LIBOQS_BUILD_DEFINES} -DBUILD_SHARED_LIBS=OFF -DCMAKE_INSTALL_PREFIX=/opt/ossl-src/oqs && ninja install
 
 # build OQS-OpenSSL
 WORKDIR /opt/ossl-src

haproxy/Dockerfile

@@ -0,0 +1,118 @@
+# Multi-stage build: First the full builder image:
+
+# First: global build arguments: 
+
+# liboqs build type variant; build non-optimized by default (maximum portability of image):
+ARG LIBOQS_BUILD_DEFINES="-DOQS_USE_CPU_EXTENSIONS=OFF"
+
+ARG BUILDDIR=/root
+
+# installation paths
+ARG INSTALLPATH=/opt/oqssa
+ARG HAPROXY_PATH=/opt/haproxy
+
+# defines the QSC signature algorithm used for the certificates:
+ARG SIG_ALG="dilithium3"
+
+# define the haproxy version to include
+ARG HAPROXY_VERSION=2.2.6
+
+# Pass parameters to `make`. Most notably set parallelism (`-j` [degree]) 
+# only if you know your machine can handle it 
+ARG MAKE_DEFINES=""
+
+
+FROM alpine as intermediate
+
+# Take in global args
+ARG INSTALLPATH
+ARG BUILDDIR
+ARG LIBOQS_BUILD_DEFINES
+ARG HAPROXY_PATH
+ARG SIG_ALG
+ARG HAPROXY_VERSION
+ARG MAKE_DEFINES
+
+
+# Get all software packages required for builing all components:
+# All SW-build and docker-image build prereqs
+RUN apk update && apk upgrade && apk add openssl make build-base linux-headers openssl-dev autoconf automake git libtool unzip wget cmake 
+
+# get sources
+WORKDIR ${BUILDDIR}
+RUN git clone --depth 1 --branch main https://github.com/open-quantum-safe/liboqs && \
+    git clone --depth 1 --branch OQS-OpenSSL_1_1_1-stable https://github.com/open-quantum-safe/openssl && \
+    wget http://www.haproxy.org/download/2.2/src/haproxy-${HAPROXY_VERSION}.tar.gz && tar xzvf haproxy-${HAPROXY_VERSION}.tar.gz && mv haproxy-${HAPROXY_VERSION} haproxy
+
+# build liboqs (dynamic linking only)
+WORKDIR ${BUILDDIR}/liboqs
+RUN mkdir build && cd build && if [[ -z "$MAKE_DEFINES" ]] ; then nproc=$(getconf _NPROCESSORS_ONLN) && MAKE_DEFINES="-j $nproc"; fi && cmake .. ${LIBOQS_BUILD_DEFINES} -DBUILD_SHARED_LIBS=ON -DCMAKE_INSTALL_PREFIX=${BUILDDIR}/openssl/oqs && make $MAKE_DEFINES && make install
+
+# build OQS-OpenSSL (again, dynamic/shared libs only)
+WORKDIR ${BUILDDIR}/openssl
+RUN LDFLAGS="-Wl,-rpath -Wl,$INSTALLPATH/lib" ./Configure linux-x86_64 -lm --prefix=$INSTALLPATH && if [[ -z "$MAKE_DEFINES" ]] ; then nproc=$(getconf _NPROCESSORS_ONLN) && MAKE_DEFINES="-j $nproc"; fi && make $MAKE_DEFINES && make install_sw
+
+# build haproxy
+WORKDIR ${BUILDDIR}/haproxy
+
+RUN if [[ -z "$MAKE_DEFINES" ]] ; then nproc=$(getconf _NPROCESSORS_ONLN) && MAKE_DEFINES="-j $nproc"; fi && make $MAKE_DEFINES LDFLAGS="-Wl,-rpath,$INSTALLPATH/lib" SSL_INC=$INSTALLPATH/include SSL_LIB=$INSTALLPATH/lib TARGET=linux-musl USE_OPENSSL=1 && make PREFIX=$INSTALLPATH install
+
+#
+# prepare to run haproxy
+ARG OPENSSL_CNF=${BUILDDIR}/openssl/apps/openssl.cnf
+
+# Set a default QSC signature algorithm from the list at https://github.com/open-quantum-safe/openssl#authentication
+ARG SIG_ALG=dilithium3
+
+WORKDIR ${HAPROXY_PATH}
+    # generate CA key and cert
+    # generate server CSR
+    # generate server cert
+RUN set -x && \
+    mkdir pki && \
+    mkdir cacert && \
+    ${INSTALLPATH}/bin/openssl req -x509 -new -newkey ${SIG_ALG} -keyout cacert/CA.key -out cacert/CA.crt -nodes -subj "/CN=oqstest CA" -days 365 -config ${OPENSSL_CNF} && \
+    ${INSTALLPATH}/bin/openssl req -new -newkey ${SIG_ALG} -keyout pki/server.key -out pki/server.csr -nodes -subj "/CN=oqs-haproxy" -config ${OPENSSL_CNF} && \
+    ${INSTALLPATH}/bin/openssl x509 -req -in pki/server.csr -out pki/server.crt -CA cacert/CA.crt -CAkey cacert/CA.key -CAcreateserial -days 365
+
+# second stage: Only create minimal image without build tooling and intermediate build results generated above:
+FROM alpine
+# Take in global args
+ARG HAPROXY_PATH
+ARG INSTALLPATH
+
+# lighttpd as built-in backend
+RUN apk add lighttpd
+#
+# Only retain the ${*_PATH} contents in the final image
+COPY --from=intermediate ${HAPROXY_PATH} ${HAPROXY_PATH}
+COPY --from=intermediate ${INSTALLPATH} ${INSTALLPATH}
+
+COPY conf ${HAPROXY_PATH}/conf/
+WORKDIR ${HAPROXY_PATH}
+
+ADD lighttpd.conf /etc/lighttpd/lighttpd.conf
+ADD lighttpd2.conf /etc/lighttpd/lighttpd2.conf
+ADD start.sh ${HAPROXY_PATH}/start.sh
+
+# set up normal user
+RUN addgroup -g 1000 -S oqs && adduser --uid 1000 -S oqs -G oqs && chown -R oqs.oqs ${HAPROXY_PATH}
+
+# set up file permissions for lighttpd
+RUN mkdir -p /opt/lighttpd/log && mkdir -p /opt/lighttpd/log2 && chown -R oqs.oqs /opt
+
+# set up demo backend using lighttpd:
+RUN echo "Hello World from lighthttpd backend #1. If you see this, all is fine: lighttpd data served via haproxy protected by OQSSL..." > /var/www/localhost/htdocs/index.html
+RUN mkdir -p /var/www/localhost2/htdocs && echo "Hello World from lighthttpd backend #2. If you see this, all is fine: lighttpd data served via haproxy protected by OQSSL..." > /var/www/localhost2/htdocs/index.html
+
+USER oqs
+
+# Ensure haproxy just runs
+ENV PATH ${HAPROXY_PATH}/sbin:$PATH
+
+EXPOSE 4433
+#
+STOPSIGNAL SIGTERM
+
+CMD ["/opt/haproxy/start.sh"]
+

haproxy/README.md

@@ -0,0 +1,53 @@
+## Purpose 
+
+This directory contains a Dockerfile that builds [haproxy](https://www.haproxy.org) with the [OQS OpenSSL 1.1.1 fork](https://github.com/open-quantum-safe/openssl), which allows haproxy to negotiate quantum-safe keys and use quantum-safe authentication in TLS 1.3.
+
+## Getting started
+
+[Install Docker](https://docs.docker.com/install) and run the following commands in this directory:
+
+1. `docker build --build-arg SIG_ALG=<SIG> --tag oqs-haproxy-img .` (`<SIG>` can be any of the authentication algorithms listed [here](https://github.com/open-quantum-safe/openssl#authentication)). An alternative, simplified build instruction is `docker build -t oqs-haproxy-img .`: This will generate the image with a default QSC algorithm (dilithium3 -- see Dockerfile to change this).
+2. `docker run --detach --rm --name oqs-haproxy -p 4433:4433 oqs-haproxy-img`
+
+This will start a docker container that has haproxy listening for TLS 1.3 connections on port 4433. Actual data will be served via a load-balanced `lighttpd` server running on ports 8181 and 8182.
+
+
+## Usage
+
+Complete information how to use the image is [available in the separate file USAGE.md](USAGE.md).
+
+## Build options
+
+The Dockerfile provided allows for significant customization of the image built:
+
+### LIBOQS_BUILD_DEFINES
+
+This permits changing the build options for the underlying library with the quantum safe algorithms. All possible options are documented [here](https://github.com/open-quantum-safe/liboqs/wiki/Customizing-liboqs).
+
+By default, the image is built such as to have maximum portability regardless of CPU type and optimizations available, i.e. to run on the widest possible range of cloud machines.
+
+### SIG_ALG
+
+This defines the quantum-safe cryptographic signature algorithm for the internally generated (demonstration) CA and server certificates.
+
+The default value is 'dilithium3' but can be set to any value documented [here](https://github.com/open-quantum-safe/openssl#authentication).
+
+
+### HAPROXY_PATH
+
+This defines the resultant location of the haproxy installation.
+
+By default this is '/opt/haproxy'. It is recommended to not change this. Also, all [usage documentation](USAGE.md) assumes this path.
+
+### HAPROXY_VERSION
+
+This defines the haproxy software version to be build into the image. By default, this is an LTS version.
+
+The default version set is known to work OK but one could try any value available [for download](https://www.haproxy.org/#down).
+
+### MAKE_DEFINES
+
+Allow setting parameters to `make` operation, e.g., '-j nnn' where nnn defines the number of jobs run in parallel during build.
+
+The default is conservative and known not to overload normal machines. If one has a very powerful (many cores, >64GB RAM) machine, passing larger numbers (or only '-j' for maximum parallelism) speeds up building considerably.
+

haproxy/USAGE.md

@@ -0,0 +1,168 @@
+## Purpose 
+
+This is an [haproxy](https://www.haproxy.org) docker image building on the [OQS OpenSSL 1.1.1 fork](https://github.com/open-quantum-safe/openssl), which allows haproxy to negotiate quantum-safe keys and use quantum-safe authentication using TLS 1.3.
+
+If you built the docker image yourself following the instructions [here](https://github.com/open-quantum-safe/oqs-demos/tree/main/haproxy), exchange the  name of the image from 'openquantumsafe/haproxy' in the examples below suitably.
+
+This image has a built-in non-root user to permit execution without particular [docker privileges](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities) such as to allow installation in all types of Kubernetes clusters.
+
+Also built-in is a backend server whose content is served via the load-balancing features of HAproxy. This is a standard lighttpd without any special configuration settings.
+
+## Quick start 
+
+Assuming Docker is [installed](https://docs.docker.com/install) the following command 
+
+```
+docker run -p 4433:4433 openquantumsafe/haproxy
+```
+
+will start up the QSC-enabled haproxy running and listening for quantum-safe crypto protected TLS 1.3 connections on port 4433.
+
+To retrieve a test page, a quantum-safe crypto client program is required. For the most simple use case, use the [docker image for curl](https://hub.docker.com/r/openquantumsafe/curl) with the required quantum-safe crypto enablement. 
+
+If you started the OQS-haproxy image on a machine with a registered IP name the required command is simply
+
+```
+docker run -it openquantumsafe/curl curl -k https://<ip-name-of-testmachine>:4433
+```
+
+If you try this on your local computer, you need to execute both images within one docker network as follows:
+
+```
+docker network create haproxy-test
+docker run --network haproxy-test --name oqs-haproxy -p 4433:4433 openquantumsafe/haproxy
+docker run --network haproxy-test -it openquantumsafe/curl curl -k https://oqs-haproxy:4433
+```
+
+## Slightly more advanced usage options
+
+This haproxy image supports all quantum-safe key exchange algorithms [presently supported by OQS-OpenSSL](https://github.com/open-quantum-safe/openssl#key-exchange). If you want to control with algorithm is actually used, you can request one from the list above to the curl command with the '--curves' parameter, e.g., requesting the hybrid Frodo976Shake variant also configured into the default 'haproxy.cfg' file:
+
+```
+docker run -it openquantumsafe/curl curl -k https://oqs-haproxy:4433  --curves p384_frodo976shake
+```
+
+
+## Seriously more advanced usage options
+
+### haproxy configuration
+
+If you want to adapt the docker image to your needs you may want to change the haproxy configuration file. To facilitate this, you just need to mount your own 'haproxy.cfg' file into the image at the path `/opt/haproxy/conf`. Assuming you stored your own file `haproxy.cfg` into a local folder named `haproxy-conf` the required command would look like this:
+
+```
+docker run -p 4433:4433 -v `pwd`/haproxy-conf:/opt/haproxy/conf openquantumsafe/haproxy
+```
+
+*Note*: Of particular interest is the `bind` parameter `curves` as it can be used to set the (quantum safe) cryptographic algorithms supported by the haproxy installation. See the example in the 'haproxy.cfg' built into the image and [accessible here](https://github.com/open-quantum-safe/oqs-demos/blob/main/haproxy/conf/haproxy.cfg).
+
+### Validate server certificate
+
+If you look carefully at the curl command above, you will notice the option `-k` which turns off server certificate validation. In the quick start option, this is OK, but if you want to be sure that the set up can actually perform quantum-safe certificate validation, you need to retrieve the CA certificate pre-loaded into the haproxy image in order to pass it to the curl command for validation. This is thus a two-step process:
+
+1) Extract CA certificate to local file 'CA.crt': `docker run -it openquantumsafe/haproxy cat cacert/CA.crt > CA.crt`
+2) Make this certificate available to curl for verification
+
+```
+docker run -v `pwd`:/opt/cacert -it openquantumsafe/curl curl --cacert /opt/cacert/CA.crt https://<ip-name-of-testmachine>:4433
+```
+
+*Note*: This command will report a mismatch between the name of your machine and 'oqs-haproxy', which is the name of the server built into the demo server certificate. Read below how to rectify this with your own server certificate.
+
+A completely successful call requires use of a local docker-network where the server name is ensured to match the one encoded in the certificate:
+
+```
+docker run --network haproxy-test -v `pwd`:/opt/cacert -it openquantumsafe/curl curl --cacert /opt/cacert/CA.crt https://oqs-haproxy:4433
+```
+
+## Completely standalone deployment
+
+For ease of demonstration, the OQS-haproxy image comes with a server and CA certificate preloaded. For a real deployment, the installation of server-specific certificates is required. Also this can be facilitated by mounting your own server key and certificate into the image at the path '/opt/haproxy/pki'. Again, assuming server certificate and key are placed in a local folder named `server-pki` the startup command would look like this:
+
+```
+docker run -p 4433:4433 -v `pwd`/server-pki:/opt/haproxy/pki openquantumsafe/haproxy
+```
+
+
+### Creating (test) CA and server certificates
+
+For creating the required keys and certificates, it is also possible to utilize the [openquantumsafe/curl](https://hub.docker.com/r/openquantumsafe/curl) image using standard `openssl` commands. 
+
+An example sequence is shown below, using 
+- 'qteslapi' for signing the CA certificate,
+- 'dilithium2' for signing the server certificate,
+- 'haproxy.server.my.org' as the address of the server for which the certificate is intended.
+
+Instead of 'qteslapi' or 'dilithium2' any of the [quantum safe authentication algorithms presently supported](https://github.com/open-quantum-safe/openssl#authentication) can be used.
+
+```
+# create and enter directory to contain keys and certificates
+mkdir -p server-pki && cd server-pki
+
+# create CA key and certificate using qteslapi
+docker run -v `pwd`:/opt/tmp -it openquantumsafe/curl openssl req -x509 -new -newkey qteslapi -keyout /opt/tmp/CA.key -out /opt/tmp/CA.crt -nodes -subj "/CN=oqstest CA" -days 365
+
+# create server key using dilithium2
+docker run -v `pwd`:/opt/tmp -it openquantumsafe/curl openssl req -new -newkey dilithium2 -keyout /opt/tmp/server.key -out /opt/tmp/server.csr -nodes -subj "/CN=haproxy.server.my.org"
+
+# create server certificate
+docker run -v `pwd`:/opt/tmp -it openquantumsafe/curl openssl x509 -req -in /opt/tmp/server.csr -out /opt/tmp/server.crt -CA /opt/tmp/CA.crt -CAkey /opt/tmp/CA.key -CAcreateserial -days 365
+```
+
+*Note*: You may want to leave away the `-nodes` option to the CA key generation command above to ensure the key is encrypted. You can then safe it for future use at another location.
+
+## Further options
+
+The HAproxy configuration contained in the docker image also starts up a statistics UI at port 8484.
+
+### docker -name and --rm options
+
+To ease rapid startup and teardown, we strongly recommend using the docker [--name](https://docs.docker.com/engine/reference/commandline/run/#assign-name-and-allocate-pseudo-tty---name--it) and automatic removal option [--rm](https://docs.docker.com/engine/reference/commandline/run/).
+
+## List of specific configuration options at a glance
+
+### Port: 4433
+
+Port at which haproxy listens by default for quantum-safe TLS connections. Defined/changeable in `haproxy.cfg`.
+
+### Port: 8484
+
+Port at which haproxy listens by default for plain statistics UI requests. Defined/changeable in `haproxy.cfg`.
+
+### haproxy configuration folder location: /opt/haproxy/conf
+
+This folder contains `haproxy.cfg` for baseline haproxy configuration.
+
+### haproxy PKI location: /opt/haproxy/pki
+
+#### Server key: /opt/haproxy/pki/server.key
+
+#### Server certificate: /opt/haproxy/pki/server.crt
+
+## Putting it all together
+
+If you want to run your own, fully customized quantum safe haproxy installation on your machine you can do this with this docker image by running this command (assuming you followed the instructions above for generating your own server keys and certificates).
+
+```
+
+# Start image with all config folders bind-mounted
+docker run --rm --name haproxy.server.my.org \
+       -p 4433:4433 \
+       -p 8484:8484 \
+       -v `pwd`/server-pki:/opt/haproxy/pki \
+       -v `pwd`/haproxy-conf:/opt/haproxy/conf \
+       openquantumsafe/haproxy
+```
+
+Validating that all works as desired can be done by retrieving a document using server validation and this command:
+
+```
+# Give curl access to CA certificate via bind-mount
+docker run -v `pwd`/server-pki:/opt/tmp -it openquantumsafe/curl \
+           curl --cacert /opt/tmp/CA.crt https://haproxy.server.my.org:4433
+```
+
+Again, if you don't have your own server and want to test on a local machine, start both of them in a docker network (adding the option `--network haproxy-test`). 
+
+## Disclaimer
+
+[THIS IS NOT FIT FOR PRODUCTIVE USE](https://github.com/open-quantum-safe/openssl#limitations-and-security).