From 40e6334bb12883245f5abf1c77b7380fb7a8ce7d Mon Sep 17 00:00:00 2001 From: Duncan Tourolle Date: Wed, 26 Aug 2026 10:13:18 +0200 Subject: [PATCH] Sign the APK with a real key when one is configured The APK has been debug-signed with a key generated on the spot, which is right for putting a build on a test device and useless for anything else: a different signature every run, so nothing can ever update in place. Four secrets now select a real signature -- ANDROID_KEYSTORE_BASE64 and its password, alias and key password. The names are JellyTau's, because that repo already signs its Android build this way against this same runner and one convention across both is one thing to remember. Absence of the secrets is not an error. A fork or a branch build has no access to them and should still produce an installable APK, so the debug path stays exactly as it was. The reverse is an error: if a keystore is supplied and cannot be read, the build fails rather than quietly falling back to a debug key, because a release that is silently debug-signed is worse than no release. Passwords reach apksigner and keytool as `env:`, never `pass:`. `pass:` puts the password in the process table for anything on the box to read. The keystore is written to a 0700 mktemp directory and never into the workspace, which is both what actions/cache saves and what the upload step globs. Also: upload-artifact drops from v4 to v3. v4 was a guess about what this Gitea supports. v3 is what JellyTau uploads its APK with on this runner today, which makes it the version known to work rather than the one that ought to. Co-Authored-By: Claude Opus 5 --- .gitea/workflows/build-and-test.yml | 33 ++++++++++++-- docker/android/assemble-apk.sh | 46 +++++++++++++++++-- docs/android-signing.md | 70 +++++++++++++++++++++++++++++ 3 files changed, 141 insertions(+), 8 deletions(-) create mode 100644 docs/android-signing.md diff --git a/.gitea/workflows/build-and-test.yml b/.gitea/workflows/build-and-test.yml index 5031deb..8d1f8c2 100644 --- a/.gitea/workflows/build-and-test.yml +++ b/.gitea/workflows/build-and-test.yml @@ -295,20 +295,45 @@ jobs: - name: Package the APK env: CARGO_TARGET_DIR: target-android + # Absent secrets mean a debug signature, which is what a fork or a + # branch build should get. Set all three (see docs/android-signing.md) + # and the same job produces a release-signed APK instead. + ANDROID_KEYSTORE_BASE64: ${{ secrets.ANDROID_KEYSTORE_BASE64 }} + KEYSTORE_PASS: ${{ secrets.ANDROID_KEYSTORE_PASSWORD }} + KEY_PASS: ${{ secrets.ANDROID_KEY_PASSWORD }} + KEY_ALIAS: ${{ secrets.ANDROID_KEY_ALIAS }} run: | set -e KEYDIR="$(mktemp -d)" + chmod 700 "$KEYDIR" trap 'rm -rf "$KEYDIR"' EXIT - REPO="$PWD" \ - TARGET_DIR="$PWD/target-android" \ - KEYSTORE="$KEYDIR/debug.keystore" \ + + if [ -n "$ANDROID_KEYSTORE_BASE64" ]; then + # The keystore reaches the runner base64-encoded because a secret + # is a string. It is written under a 0700 mktemp directory, never + # into the workspace: `target-android` is what actions/cache saves, + # and the upload step globs the workspace. + printf '%s' "$ANDROID_KEYSTORE_BASE64" | base64 -d > "$KEYDIR/release.keystore" + export KEYSTORE="$KEYDIR/release.keystore" + else + # Not an error. Unset the rest so assemble-apk.sh takes its debug + # path cleanly rather than seeing a half-configured release one. + export KEYSTORE="$KEYDIR/debug.keystore" + unset KEYSTORE_PASS KEY_PASS KEY_ALIAS + fi + + REPO="$PWD" TARGET_DIR="$PWD/target-android" \ bash docker/android/assemble-apk.sh + # v3, not v4. v4 is untested against this Gitea and its runner; v3 is + # what JellyTau uploads its APK with on this same runner, so it is the + # version known to work here rather than the version that ought to. + # # `if-no-files-found: error` because the failure this guards against is # a green run with an empty artefact list, which reads as success until # somebody goes looking for the file. - name: Upload the APK - uses: actions/upload-artifact@v4 + uses: actions/upload-artifact@v3 with: name: darkroom-arm64-v8a-apk path: target-android/apk/darkroom.apk diff --git a/docker/android/assemble-apk.sh b/docker/android/assemble-apk.sh index ae238ea..2deb050 100755 --- a/docker/android/assemble-apk.sh +++ b/docker/android/assemble-apk.sh @@ -19,6 +19,19 @@ # KEYSTORE signing keystore (default: $TARGET_DIR/debug.keystore) # ABI Android ABI (default: arm64-v8a) # RUST_TARGET Rust target triple (default: aarch64-linux-android) +# +# Signing. With none of these set the APK is debug-signed with a generated +# throwaway key, which is what a test device wants. Set all three for a real +# signature: +# +# KEYSTORE_PASS keystore password — presence of this is what selects +# release signing +# KEY_PASS key password (default: same as KEYSTORE_PASS) +# KEY_ALIAS key alias within the store +# +# The passwords are read from the environment and handed to apksigner as +# `env:`, never `pass:`. `pass:` puts the password in the process table, where +# every other process on the machine can read it out of `ps`. set -euo pipefail HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" @@ -30,6 +43,20 @@ TARGET_DIR="$(cd "${TARGET_DIR}" && pwd)" JNILIBS="${JNILIBS:-${TARGET_DIR}/jniLibs}" OUT="${OUT:-${TARGET_DIR}/apk}" KEYSTORE="${KEYSTORE:-${TARGET_DIR}/debug.keystore}" + +# Release signing is selected by supplying a password, not by a flag, so there +# is no way to ask for a release build and silently get a debug one. +if [[ -n "${KEYSTORE_PASS:-}" ]]; then + SIGNING=release + KEY_ALIAS="${KEY_ALIAS:?KEY_ALIAS is required when KEYSTORE_PASS is set}" + export DR_KS_PASS="${KEYSTORE_PASS}" + export DR_KEY_PASS="${KEY_PASS:-${KEYSTORE_PASS}}" +else + SIGNING=debug + KEY_ALIAS="androiddebugkey" + export DR_KS_PASS=android + export DR_KEY_PASS=android +fi ABI="${ABI:-arm64-v8a}" RUST_TARGET="${RUST_TARGET:-aarch64-linux-android}" @@ -84,11 +111,20 @@ echo " dex: ${DEX}" # Debug-signed only. This gets the app onto a test device; it is not a release # signature, and the store password is the Android convention rather than a # secret worth protecting. -if [[ ! -f "${KEYSTORE}" ]]; then +if [[ "${SIGNING}" == "release" ]]; then + # Never generated on demand. A release key is created once, by hand, and + # kept; conjuring one here would mean every build signed by a different + # identity, which is indistinguishable from having no signing story at all. + [[ -f "${KEYSTORE}" ]] || { + echo "error: KEYSTORE_PASS is set but ${KEYSTORE} does not exist" >&2 + exit 1 + } + echo " signing with the release key (alias ${KEY_ALIAS})" +elif [[ ! -f "${KEYSTORE}" ]]; then echo " generating debug keystore" mkdir -p "$(dirname "${KEYSTORE}")" - keytool -genkeypair -keystore "${KEYSTORE}" -alias androiddebugkey \ - -storepass android -keypass android \ + keytool -genkeypair -keystore "${KEYSTORE}" -alias "${KEY_ALIAS}" \ + -storepass:env DR_KS_PASS -keypass:env DR_KEY_PASS \ -keyalg RSA -keysize 2048 -validity 10950 \ -dname "CN=Android Debug,O=Android,C=US" >/dev/null 2>&1 fi @@ -129,10 +165,12 @@ zip -q -X "${OUT}/unaligned.apk" classes.dex # invalidates the signature. "${BT}/zipalign" -p -f 4 "${OUT}/unaligned.apk" "${OUT}/darkroom.apk" "${BT}/apksigner" sign \ - --ks "${KEYSTORE}" --ks-pass pass:android --key-pass pass:android \ + --ks "${KEYSTORE}" --ks-key-alias "${KEY_ALIAS}" \ + --ks-pass env:DR_KS_PASS --key-pass env:DR_KEY_PASS \ --min-sdk-version "${MIN_API}" \ "${OUT}/darkroom.apk" "${BT}/apksigner" verify --print-certs "${OUT}/darkroom.apk" | head -2 +echo " signing: ${SIGNING}" # The intermediates are not the artefact, and leaving them beside it invites # the wrong file being picked up by a glob. diff --git a/docs/android-signing.md b/docs/android-signing.md new file mode 100644 index 0000000..2bffe84 --- /dev/null +++ b/docs/android-signing.md @@ -0,0 +1,70 @@ +# Signing the Android build + +Every build produces an APK. Which key signs it depends entirely on whether +four secrets are present: + +| secret | what it is | +|---|---| +| `ANDROID_KEYSTORE_BASE64` | the keystore file, base64-encoded | +| `ANDROID_KEYSTORE_PASSWORD` | the store password | +| `ANDROID_KEY_ALIAS` | the alias of the key inside the store | +| `ANDROID_KEY_PASSWORD` | the key password | + +With none of them set, `docker/android/assemble-apk.sh` generates a throwaway +debug key and signs with that. That is the right answer for a branch build or +a fork: the APK installs on a test device and nothing pretends it is a +release. With all of them set, the same script signs with the real key. + +The names match JellyTau's deliberately. One convention across both Android +projects is one thing to remember instead of two. + +## Making the key + +Once, and then never again — keep it forever. Android identifies an app by +its signature, so an app signed with a new key is a *different* app to every +device that has the old one installed. There is no recovery from losing it +beyond telling everybody to uninstall and reinstall. + + keytool -genkeypair -v \ + -keystore darkroom-release.jks \ + -alias darkroom \ + -keyalg RSA -keysize 4096 -validity 10000 \ + -dname "CN=Duncan Tourolle, O=tourolle.paris, C=FR" + +`keytool` prompts for the passwords rather than taking them on the command +line, which keeps them out of shell history. Back the `.jks` up somewhere that +is not this repository and not the machine that builds it. + +## Loading the secrets + + base64 -w0 darkroom-release.jks > /tmp/ks.b64 + tea api --method PUT /repos/dtourolle/DarkRoom/actions/secrets/ANDROID_KEYSTORE_BASE64 \ + -f data=@/tmp/ks.b64 + shred -u /tmp/ks.b64 + + # and the three strings, read rather than typed so they miss the history + read -rs PW && tea api --method PUT \ + /repos/dtourolle/DarkRoom/actions/secrets/ANDROID_KEYSTORE_PASSWORD -f data="$PW" + +...and the same for `ANDROID_KEY_PASSWORD` and `ANDROID_KEY_ALIAS`. Or paste +them into Settings → Actions → Secrets in the web UI, which is less fiddly and +just as good. + +## Checking which key signed a build + +The packaging step prints it, and the APK carries it: + + apksigner verify --print-certs darkroom.apk + +A debug build says `CN=Android Debug`. Anything else is the real key. + +## Signing locally + +`docker/android/package.sh` takes the same environment variables, so a local +release-signed build is: + + KEYSTORE=$PWD/darkroom-release.jks KEY_ALIAS=darkroom \ + KEYSTORE_PASS=... KEY_PASS=... ./docker/android/package.sh + +Without them it debug-signs, and keeps one debug keystore in the build cache +so repeat installs to a device do not need an uninstall first.