From 2691c39fa25ba294c4366b3e215a9cb6c1cda154 Mon Sep 17 00:00:00 2001
From: Emil Lerch <emil@lerch.org>
Date: Sat, 29 Jul 2023 19:49:33 -0700
Subject: [PATCH] Clean up build/update readme

Closes #1
---
 .gitea/workflows/build.yaml | 17 ++-----------
 README.md                   | 49 +++++++++++++++++++++++++++++++++++++
 2 files changed, 51 insertions(+), 15 deletions(-)

diff --git a/.gitea/workflows/build.yaml b/.gitea/workflows/build.yaml
index f879199..0eae737 100644
--- a/.gitea/workflows/build.yaml
+++ b/.gitea/workflows/build.yaml
@@ -36,7 +36,6 @@ jobs:
           topic: ${{ secrets.NTFY_TOPIC }}
           user: ${{ secrets.NTFY_USER }}
           password: ${{ secrets.NTFY_PASSWORD }}
-      - run: echo "Build status is ${{ job.status }}."
   sign:
     runs-on: ubuntu-latest
     needs: build
@@ -54,22 +53,13 @@ jobs:
           pin: ${{ secrets.HSM_USER_PIN }}
           files: flexilib
           public_key: 'https://emil.lerch.org/serverpublic.pem'
-      - run: echo "Signature URL is ${{ steps.sign.outputs.URL_0 }}"
+      - name: Output signature URL
+        run: echo "Signature URL is ${{ steps.sign.outputs.URL_0 }}"
       - name: Upload Artifact
         uses: actions/upload-artifact@v3
         with:
           name: signature
           path: ${{ steps.sign.outputs.SIG_0 }}
-      # - run: |
-      #     echo "Source 0 should be ./bar: ${{ steps.sign.outputs.SOURCE_0 }}"
-      # - run: |
-      #     echo "Signature 0 should be ./bar.sig: ${{ steps.sign.outputs.SIG_0 }}"
-      # - run: echo "URL of bar (0) is ${{ steps.sign.outputs.URL_0 }}"
-      # - run: |
-      #     echo "Source 1 should be ./foo: ${{ steps.sign.outputs.SOURCE_1 }}"
-      # - run: |
-      #     echo "Signature 1 should be ./foo.sig: ${{ steps.sign.outputs.SIG_1 }}"
-      # - run: echo "URL of foo (1) is ${{ steps.sign.outputs.URL_1 }}"
       - name: Notify
         uses: https://git.lerch.org/lobo/action-notify-ntfy@v2
         if: always()
@@ -78,7 +68,6 @@ jobs:
           topic: ${{ secrets.NTFY_TOPIC }}
           user: ${{ secrets.NTFY_USER }}
           password: ${{ secrets.NTFY_PASSWORD }}
-      - run: echo "Sign status is ${{ job.status }}."
   deploy:
     runs-on: ubuntu-latest
     container:
@@ -96,7 +85,6 @@ jobs:
       - name: Get short ref
         id: vars
         run: echo "shortsha=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT
-      - run: "echo ${{ steps.vars.outputs.shortsha }}"
       -
         name: Login to Gitea
         uses: docker/login-action@v2
@@ -121,4 +109,3 @@ jobs:
           topic: ${{ secrets.NTFY_TOPIC }}
           user: ${{ secrets.NTFY_USER }}
           password: ${{ secrets.NTFY_PASSWORD }}
-      - run: echo "Deploy status is ${{ job.status }}."
diff --git a/README.md b/README.md
index 77e6434..4fa3f6f 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,55 @@ This project provides slightly better development and performance characteristic
 if the library used is written in [zig](https://ziglang.org). An example zig-based
 library can be found in src/main-lib.zig.
 
+Deployment
+----------
+
+Gitea actions are configured to build, sign, and deploy the source code. Each
+successful build will generate an artifact, which can be found at
+[https://git.lerch.org/lobo/FlexiLib/actions](https://git.lerch.org/lobo/FlexiLib/actions).
+
+Two artifacts will be available:
+
+* The flexilib binary, compiled for linux x86_64 with GNU libc. GNU libc is
+  necessary due to the dynamic loading involved, but otherwise it should be
+  possible to use the binary as is on any glibc-based Linux distribution.
+* A signature file generated from the HSM-based signing process. This can be
+  verified for authenticity against [sigstore](https://sigstore.dev/) public
+  transparency log with [rekor](ihttps://github.com/sigstore/rekor).
+
+Additionally, a docker container image will be build and uploaded using the
+tag `git.lerch.org/lobo/flexilib:<shortsha>`. For example, `docker pull git.lerch.org/lobo/flexilib:c02cd20`
+will get the docker container with flexilib from git commit `c02cd20`.
+
+Signature Validation
+--------------------
+
+To verify the build artifacts, you will need the rekor CLI and four additional
+things:
+
+* The signature file stored as a build artifact
+* The flexilib executable, also from the build
+* A downloaded version of the [server public key](https://emil.lerch.org/serverpublic.pem).
+  Theoretically rekor can take the URL at the command line, but this doesn't seem
+  to work for me
+* The sigstore entry URL from the Sign job in the Gitea action
+
+Once those four things are assembled, the following command will verify the
+executable matches the output from the build run at the time of the run:
+
+`rekor verify --artifact flexilib --entry <entry url> --signature signature --pki-format x509 --public-key serverpublic.pem`
+
+As an example, using output from [run 8](https://git.lerch.org/lobo/FlexiLib/actions/runs/8/jobs/1):
+
+```sh
+rekor verify \
+ --artifact flexilib \
+ --entry https://rekor.sigstore.dev/api/v1/log/entries/73a64ca9cc712f9645bfe79ae104b101e3ef7022172f0bfc3aa34d4f45ca2af8 \
+ --signature signature \
+ --pki-format x509 \
+ --public-key serverpublic.pem
+```
+
 Architecture
 ------------