diff --git a/.github/workflow-templates/template.yml b/.github/workflow-templates/template.yml new file mode 100644 index 0000000..2f9442c --- /dev/null +++ b/.github/workflow-templates/template.yml @@ -0,0 +1,100 @@ +# This is a template workflow for a new demo +# To get started replace all instances of with the name of your demo below and add the demo to the build.yml workflow +name: + +on: + push: + branches: [ 'main' ] + paths: ['.github/workflows/.yml', '/**'] + pull_request: + branches: [ 'main' ] + paths: ['.github/workflows/.yml', '/**'] + workflow_call: + inputs: + build_main: + description: "Build using liboqs and oqsprovider main branches" + required: false + default: false + type: boolean + release_tag: + description: "Which docker tag to push to" + required: false + type: string + workflow_dispatch: + inputs: + build_main: + description: "Build using liboqs and oqsprovider main branches" + required: false + default: false + type: boolean + release_tag: + description: "Which docker tag to push to" + required: false + type: string + +env: + build-args: | + LIBOQS_TAG=main + OQSPROVIDER_TAG=main + push: ${{ github.repository == 'open-quantum-safe/oqs-demos' && github.ref == 'refs/heads/main' && github.event_name != 'pull_request' && inputs.build_main != 'true' }} + +jobs: + build: + strategy: + fail-fast: false + matrix: + include: + - arch: x86_64 + runner: ubuntu-latest + - arch: arm64 + runner: oqs-arm64 + runs-on: ${{ matrix.runner }} + steps: + - uses: actions/checkout@v4 + - uses: docker/login-action@v3 + if: env.push == 'true' + with: + username: ${{ secrets.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + - uses: docker/login-action@v3 + with: + registry: ghcr.io + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Build the Docker image + uses: docker/build-push-action@v6 + with: + load: true + context: + build-args: | + MAKE_DEFINES=-j4 + ${{ (inputs.build_main == 'true') && env.build-args || null }} + tags: + + - name: Test + run: | + echo "Add tests here" + + - name: Push Docker image to registries + if: env.push == 'true' + uses: docker/build-push-action@v6 + with: + push: true + context: + build-args: | + MAKE_DEFINES=-j4 + ${{ (inputs.build_main == 'true') && env.build-args || null }} + tags: | + ghcr.io/${{ github.repository_owner }}/:${{ inputs.release_tag || 'latest' }}-${{ matrix.arch }} + openquantumsafe/:${{ inputs.release_tag || 'latest' }}-${{ matrix.arch }} + + push: + if: ${{ github.repository == 'open-quantum-safe/oqs-demos' && github.ref == 'refs/heads/main' && github.event_name != 'pull_request' && inputs.build_main != 'true' }} + needs: build + runs-on: ubuntu-latest + steps: + - uses: ./.github/workflows/manifest + with: + image_name: + release_tag: ${{ inputs.release_tag || 'latest' }} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e1eec28 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,25 @@ +# Contributing new quantum-safe application integrations + +All submissions must meet acceptance criteria given below. Demos may be removed if they no longer meet the acceptance criteria. + +## Documentation requirements + +- Purpose of integration and upstream (code origin) location must be clearly documented. +- README must contain all steps to build the OQS-enabled code. +- An optional USAGE file must be present if the integration can be built into a docker image. + +## Execution requirements + +- If possible, a Dockerfile should be provided such as to automate the integration completely. In this case, a separate USAGE file must be available that shall document usage of the docker file at [docker hub](https://hub.docker.com/orgs/openquantumsafe/repositories). +- If a docker file is provided, it is expected that build-and-test code is added to the continuous integration environment testing (see below). + +## Maintenance + +We hope the contributor will intend to help update the integration over time as the upstream code bases as well as the underlying algorithms and APIs evolve. + +## Continuous Integration + +Each demo should have it's own GitHub Actions workflow to handle building, testing, and pushing its Docker image. An [example template](.github/workflow-templates/template.yml) is provided to get started. + +A workflow should run the build and test steps whenever changes are detected for the integration in a pull request or push to main. +The push step should only be triggered when the workflow is run on the main branch of the upstream repository (not forks) and not when building against the latest liboqs and oqs-provider code. \ No newline at end of file diff --git a/README.md b/README.md index 39b15d3..0d1349a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,5 @@ -[![GitHub actions](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/linux.yml/badge.svg)](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/linux.yml) +[![openssl](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/openssl3.yml/badge.svg)](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/openssl3.yml) [![QUIC](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/quic.yml/badge.svg)](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/quic.yml) -[![open-quantum-safe](https://circleci.com/gh/open-quantum-safe/oqs-demos.svg?style=svg)](https://app.circleci.com/pipelines/github/open-quantum-safe/oqs-demos) oqs-demos ========= @@ -11,7 +10,7 @@ A repository of instructions (with associated patches and scripts) to enable, th In most cases, Dockerfiles encode the instructions for ease-of-use: Just do `docker build -t .`. For more detailed usage instructions (parameters, algorithms, etc.) refer to the README for each package. Pre-built Docker images may also be available. -As the level of interest in providing and maintaining these integrations for public consumption has fallen, the packages are tagged with the github monikers of the persons willing to keep supporting them or the term "Unmaintained". If that tag is listed, no CI and github support for the integration is available and the code shall be seen as a snapshot that once worked only. +As the level of interest in providing and maintaining these integrations for public consumption has fallen, the packages are tagged with the github monikers of the persons willing to keep supporting them or the term "Unmaintained". If that tag is listed, no github support for the integration is available and the code shall be seen as a snapshot that once worked only. We are explicitly soliciting contributors to maintain those integrations labelled "Unmaintained". @@ -19,18 +18,18 @@ Currently available integrations at their respective support level: | | **Build instructions** | **Pre-built Docker image or binary files** | Support | |-------------------|----------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -------- | -| **curl** | [Github: oqs-demos/curl](curl) | [Dockerhub: openquantumsafe/curl](https://hub.docker.com/repository/docker/openquantumsafe/curl), [Dockerhub: openquantumsafe/curl-quic](https://hub.docker.com/repository/docker/openquantumsafe/curl-quic) | Maintained: @baentsch, @pi-314159 -| **Apache httpd** | [Github: oqs-demos/httpd](httpd) | [Dockerhub: openquantumsafe/httpd](https://hub.docker.com/repository/docker/openquantumsafe/httpd) | Maintained: @baentsch -| **nginx** | [Github: oqs-demos/nginx](nginx) | [Dockerhub: openquantumsafe/nginx](https://hub.docker.com/repository/docker/openquantumsafe/nginx), [Dockerhub: openquantumsafe/nginx-quic](https://hub.docker.com/repository/docker/openquantumsafe/nginx-quic) | Maintained: @baentsch, @bhess, @pi-314159 +| **curl** | [Github: oqs-demos/curl](curl) | [Dockerhub: openquantumsafe/curl](https://hub.docker.com/repository/docker/openquantumsafe/curl), [Dockerhub: openquantumsafe/curl-quic](https://hub.docker.com/repository/docker/openquantumsafe/curl-quic) | [![curl](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/curl.yml/badge.svg)](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/curl.yml) Maintained: @baentsch, @pi-314159 +| **Apache httpd** | [Github: oqs-demos/httpd](httpd) | [Dockerhub: openquantumsafe/httpd](https://hub.docker.com/repository/docker/openquantumsafe/httpd) | [![httpd](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/httpd.yml/badge.svg)](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/httpd.yml) Maintained: @baentsch +| **nginx** | [Github: oqs-demos/nginx](nginx) | [Dockerhub: openquantumsafe/nginx](https://hub.docker.com/repository/docker/openquantumsafe/nginx), [Dockerhub: openquantumsafe/nginx-quic](https://hub.docker.com/repository/docker/openquantumsafe/nginx-quic) | [![nginx](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/nginx.yml/badge.svg)](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/nginx.yml) Maintained: @baentsch, @bhess, @pi-314159 | **Chromium** | [Github: oqs-demos/chromium](chromium) (limited support) | - | Maintained: @pi-314159 -| **Locust** | [Github: oqs-demos/locust](locust) | - | Maintained: @davidgca -| **Wireshark** | [Github: oqs-demos/wireshark](wireshark) | [Dockerhub: openquantumsafe/wireshark](https://hub.docker.com/repository/docker/openquantumsafe/wireshark) | Maintained: @hayyaaf -| **OpenSSH** | [Github: oqs-demos/openssh](openssh) | [Dockerhub: openquantumsafe/openssh](https://hub.docker.com/repository/docker/openquantumsafe/openssh) | Unmaintained -| **OpenVPN** | [Github: oqs-demos/openvpn](openvpn) | [Dockerhub: openquantumsafe/openvpn](https://hub.docker.com/repository/docker/openquantumsafe/openvpn) | Unmaintained -| **ngtcp2** | [Github: oqs-demos/ngtcp2](ngtcp2) | Dockerhub: [Server: openquantumsafe/ngtcp2-server](https://hub.docker.com/repository/docker/openquantumsafe/ngtcp2-server), [Client: openquantumsafe/ngtcp2-client](https://hub.docker.com/repository/docker/openquantumsafe/ngtcp2-client) | Unmaintained -| **h2load** | [Github: oqs-demos/h2load](h2load) | [ Dockerhub: openquantumsafe/h2load](https://hub.docker.com/repository/docker/openquantumsafe/h2load) | Unmaintained -| **HAproxy** | [Github: oqs-demos/haproxy](haproxy) | [Dockerhub: openquantumsafe/haproxy](https://hub.docker.com/repository/docker/openquantumsafe/haproxy) | Unmaintained -| **Mosquitto** | [Github: oqs-demos/mosquitto](mosquitto) | [Dockerhub: openquantumsafe/mosquitto](https://hub.docker.com/repository/docker/openquantumsafe/mosquitto) | Unmaintained +| **Locust** | [Github: oqs-demos/locust](locust) | - | [![locust](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/locust.yml/badge.svg)](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/locust.yml) Maintained: @davidgca +| **Wireshark** | [Github: oqs-demos/wireshark](wireshark) | [Dockerhub: openquantumsafe/wireshark](https://hub.docker.com/repository/docker/openquantumsafe/wireshark) | [![wireshark](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/wireshark.yml/badge.svg)](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/wireshark.yml) Maintained: @hayyaaf +| **OpenSSH** | [Github: oqs-demos/openssh](openssh) | [Dockerhub: openquantumsafe/openssh](https://hub.docker.com/repository/docker/openquantumsafe/openssh) | [![openssh](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/openssh.yml/badge.svg)](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/openssh.yml) Unmaintained +| **OpenVPN** | [Github: oqs-demos/openvpn](openvpn) | [Dockerhub: openquantumsafe/openvpn](https://hub.docker.com/repository/docker/openquantumsafe/openvpn) | [![openvpn](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/openvpn.yml/badge.svg)](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/openvpn.yml) Unmaintained +| **ngtcp2** | [Github: oqs-demos/ngtcp2](ngtcp2) | Dockerhub: [Server: openquantumsafe/ngtcp2-server](https://hub.docker.com/repository/docker/openquantumsafe/ngtcp2-server), [Client: openquantumsafe/ngtcp2-client](https://hub.docker.com/repository/docker/openquantumsafe/ngtcp2-client) | [![ngtcp2](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/ngtcp2.yml/badge.svg)](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/ngtcp2.yml) Unmaintained +| **h2load** | [Github: oqs-demos/h2load](h2load) | [ Dockerhub: openquantumsafe/h2load](https://hub.docker.com/repository/docker/openquantumsafe/h2load) | [![h2load](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/h2load.yml/badge.svg)](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/h2load.yml) Unmaintained +| **HAproxy** | [Github: oqs-demos/haproxy](haproxy) | [Dockerhub: openquantumsafe/haproxy](https://hub.docker.com/repository/docker/openquantumsafe/haproxy) | [![haproxy](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/haproxy.yml/badge.svg)](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/haproxy.yml) Unmaintained +| **Mosquitto** | [Github: oqs-demos/mosquitto](mosquitto) | [Dockerhub: openquantumsafe/mosquitto](https://hub.docker.com/repository/docker/openquantumsafe/mosquitto) | [![mosquitto](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/mosquitto.yml/badge.svg)](https://github.com/open-quantum-safe/oqs-demos/actions/workflows/mosquitto.yml) Unmaintained | **Epiphany** | [Github: oqs-demos/epiphany](epiphany) | [Dockerhub: openquantumsafe/epiphany](https://hub.docker.com/repository/docker/openquantumsafe/epiphany) | Deprecated | **OpenLiteSpeed** | [Github: oqs-demos/openlitespeed](openlitespeed) | [ Dockerhub: openquantumsafe/openlitespeed](https://hub.docker.com/repository/docker/openquantumsafe/openlitespeed) | Deprecated | **Envoy** | [Github: oqs-demos/envoy](envoy) | [ Dockerhub: openquantumsafe/envoy](https://hub.docker.com/repository/docker/openquantumsafe/envoy) | Deprecated @@ -38,9 +37,11 @@ Currently available integrations at their respective support level: It should be possible to use the openssl (s_client) and curl clients with all algorithm combinations available at the Open Quantum Safe TLS/X.509 interoperability test server at https://test.openquantumsafe.org (set up using `oqs-provider v0.7.0` and `liboqs v0.11.0`) but no guarantees are given for software not explicitly labelled with the name of a person offering support for it. Since [OQS-BoringSSL](https://github.com/open-quantum-safe/boringssl) no longer maintains the same set of algorithms, software that depends on OQS-BoringSSL (e.g., nginx-quic and curl-quic) may not fully (inter)operate with the test server. +When updates to an integration with a Dockerfile are pushed to `main`, an updated `latest` image is pushed to DockerHub and ghcr.io with support for both x86_64 and arm64. + ## Contributing -Contributions are gratefully welcomed. See our [Contributing Guide](https://github.com/open-quantum-safe/oqs-demos/wiki/Contributing-guide) for more details. +Contributions are gratefully welcomed. See our [Contributing Guide](CONTRIBUTING.md) for more details. ## License