======================================================================== screenTAP — Raspberry Pi signage image How to VERIFY it, then flash it ======================================================================== This folder contains a ready-to-flash Raspberry Pi image that boots straight into the screenTAP player (full-screen, locked-down kiosk). Files in this folder: screentap-pi-YYYYMMDD.img.xz the image (compressed, ~700 MB) screentap-pi-YYYYMMDD.img.xz.sha256 checksum (corruption check only) screentap-pi-YYYYMMDD.img.xz.cosign.bundle the signature <-- proves authenticity verify-image.sh the verifier (run this first) README.txt this file ------------------------------------------------------------------------ STEP 1 — VERIFY BEFORE YOU FLASH (do not skip this) ------------------------------------------------------------------------ A Pi image runs as root on every device you flash it to. If someone swapped this image for a poisoned one, flashing it would hand them every screen you deploy. So prove it was built and signed by screenTAP's own GitHub CI before writing it to a card. The .sha256 only tells you the download wasn't CORRUPTED. It does NOT prove the image wasn't TAMPERED WITH — an attacker who swaps the image swaps its checksum too. The cosign signature is what proves authenticity, and it cannot be forged without control of screenTAP's GitHub identity. 1. Install cosign (the verifier tool) from a PINNED release — NOT "curl | bash the latest", which reintroduces the exact risk we're closing here: https://github.com/sigstore/cosign/releases (macOS: brew install cosign is also fine.) 2. Download ALL of these into one folder (you probably already have them): screentap-pi-YYYYMMDD.img.xz screentap-pi-YYYYMMDD.img.xz.cosign.bundle verify-image.sh 3. Run the verifier: chmod +x verify-image.sh ./verify-image.sh screentap-pi-YYYYMMDD.img.xz PASS -> it prints "signature valid … Safe to flash." Continue. FAIL -> it exits non-zero and prints an error. DO NOT FLASH. Re-download from the official screenTAP link and try again; if it still fails, stop and report it. The signature works fully OFFLINE (the bundle carries its own proof), so this also works on an air-gapped flashing station. IMPORTANT (L5): get verify-image.sh from a DIFFERENT origin than the image. The verifier is published next to the image for convenience, but a verifier sitting in the same bucket as the image could be swapped for one that always prints "OK" — checking a signature with a doctored checker proves nothing. Fetch it from the version-controlled repo instead: curl -fsSLO https://raw.githubusercontent.com/JohnRoberts-prod/screentap/main/pi-image/verify-image.sh The image signature ITSELF still can't be forged (the identity pin holds), so this guards specifically against the download source swapping the checker. Sanity-check that verify-image.sh's pinned identity has NOT been loosened — the two --certificate-* lines inside it must pin EXACTLY: identity : https://github.com/JohnRoberts-prod/screentap/.github/workflows/pi-image.yml@refs/(heads/main|tags/)... issuer : https://token.actions.githubusercontent.com If those pins are missing or widened, ANY Sigstore signature would pass and the check is worthless — do not trust that copy. ------------------------------------------------------------------------ STEP 2 — FLASH IT ------------------------------------------------------------------------ 1. Open Raspberry Pi Imager (https://www.raspberrypi.com/software/). 2. Choose OS -> "Use custom" -> select the VERIFIED .img.xz. 3. Choose storage -> your SD card -> Write. Do NOT use Imager's settings (gear icon). You don't need it — the screen asks for your Wi-Fi itself, on screen, in Step 3. Setting a username and password there renames the image's built-in kiosk account, which stops the screen booting into the player and drops it at a login prompt instead. ------------------------------------------------------------------------ STEP 3 — CONNECT IT TO WI-FI (skip if you're using an Ethernet cable) ------------------------------------------------------------------------ Put the SD card in the Pi, connect it to your screen, and power it on. - Using Ethernet? Plug the cable in. There's nothing to set up. - Using Wi-Fi? After a few seconds the screen shows instructions: 1. On your phone, join the Wi-Fi network: screenTAP-setup 2. Enter the password shown on the screen 3. The setup page opens on your phone by itself (like hotel Wi-Fi). If it doesn't, open http://10.42.0.1 in your browser. 4. Pick your Wi-Fi network and enter its password Your phone will drop off the setup network while the screen connects — that's normal. The screen then shows its pairing code. If you ever move the screen or change your router, it shows those same Wi-Fi instructions again automatically. Nothing to re-flash. ------------------------------------------------------------------------ STEP 4 — PAIR IT ------------------------------------------------------------------------ 1. The screen shows a pairing code. 2. In the screenTAP portal: Screens -> Add screen -> enter the code. 3. Assign a playlist. Done. ------------------------------------------------------------------------ Questions / problems: support@screentap.co.uk ========================================================================