Sign, silent, update¶

Exercise sign-silent-update-ci-annex.pdf · PDF

You have seen this window: "Windows protected your PC. Unknown publisher." And you have probably clicked "Run anyway". So how did you know the file was the one its author made, and not one somebody changed on the way? You did not.

To the rest of the world, the .deb from the last page is an anonymous file. Here it gets a name and a seal. It also learns to install itself on 300 PCs with nobody watching, to leave cleanly, and to update itself once it is out there.

The seal¶

Keep one picture for this page: your package is a sealed parcel.

A wax seal on a parcel says two things: who closed it, because only they own that stamp, and that nobody has opened it since, because a broken seal shows. It says nothing about whether what is inside is any good.

A digital signature is a short piece of data computed from a file and the signer's private key. Anyone with the public key can check that the file is unchanged and who sealed it.

So there are two keys:

Two seals: do not mix them¶

Your app can carry two different seals, for two different inspectors:

A certificate authority is a company that checks who you are and vouches for your public key. A self-signed certificate is one you vouch for yourself. It proves the file was not changed, but not who you are: anybody can self-sign as "Microsoft".

Linux has no SmartScreen, so nobody checks a .deb you download by hand. The habit there is a detached signature, a separate .asc file next to the package, plus a checksum, a short fingerprint of the file. That is what you do next.

Seal it, break it¶

Create a test key with GPG, the standard signing tool on Linux. This stamp is good for class and worthless for the public, because nobody has a reason to trust it.

gpg --batch --passphrase '' --quick-generate-key "Your Name <you@example.com>" default default never

Seal and check, in the folder of your .deb:

gpg --detach-sign --armor NoteBox_1.0.0_amd64.deb      # writes NoteBox_1.0.0_amd64.deb.asc
gpg --verify NoteBox_1.0.0_amd64.deb.asc NoteBox_1.0.0_amd64.deb
sha256sum NoteBox_1.0.0_amd64.deb > SHA256SUMS && sha256sum -c SHA256SUMS

You should see Good signature from "Your Name <you@example.com>" and NoteBox_1.0.0_amd64.deb: OK. Use your own file name: it carries your app's name and version.

Now break the seal, on a copy:

cp NoteBox_1.0.0_amd64.deb tampered.deb && echo x >> tampered.deb
gpg --verify NoteBox_1.0.0_amd64.deb.asc tampered.deb

BAD signature. You added one letter and a line break to a 3 MB file, and it noticed. The signature is computed from every byte.

The other seal¶

The Tauri updater has its own key, and its own command:

npm run tauri signer generate -- -w ~/notebox.key
npm run tauri signer sign -- -f ~/notebox.key src-tauri/target/release/bundle/deb/NoteBox_1.0.0_amd64.deb

It asks for a password. In class you can press Enter twice for none. For a real app, set one. It writes notebox.key (private) and notebox.key.pub (public) to your home folder, outside the repository, and a .sig next to the package.

On Windows¶

For a test, create a self-signed certificate in PowerShell:

New-SelfSignedCertificate -Type CodeSigningCert -Subject "CN=NoteBox Classroom" -CertStoreLocation Cert:\CurrentUser\My

Copy its thumbprint to certificateThumbprint in bundle > windows, set digestAlgorithm to sha256, add a timestampUrl, and build. Check the result with Get-AuthenticodeSignature. SmartScreen will still warn the public, because the stamp is yours.

Install without a word¶

An unattended or silent installation has no window, no question and no click.

It is how an administrator installs your app on every PC of a school overnight. If your package asks even one question, it cannot be deployed that way.

sudo apt install -y ./NoteBox_1.0.0_amd64.deb
dpkg -s note-box | head -3        # Status: install ok installed
which notebox                     # /usr/bin/notebox
notebox &                         # the app opens, with its welcome notes

Three traps hide in those lines:

• The ./. Without it, apt looks in the repositories for a package named like your file.
• The package name. It is note-box, not the file name. Tauri writes the product name in kebab-case: lowercase words joined by hyphens.
• The -y. It answers "yes" to the only question apt asks.

The same idea exists on every system:

Leave no trace¶

Add two notes in your installed NoteBox and close it, so there is something to lose. Then list, remove and look:

dpkg -L note-box                  # every file the package installed
sudo apt remove -y note-box
dpkg -s note-box                  # "is not installed"
ls /usr/lib/NoteBox /usr/bin/notebox /usr/share/applications/NoteBox.desktop   # all gone
ls ~/.local/share/com.iessonferrer.notebox                                      # still there

The app is gone, so whose folder is that? It belongs to the user. Their notes live in the WebView's storage, in a folder named after the identifier. Install the app again and the two notes are back. Your folder name will match your own identifier.

A clean uninstall leaves nothing the installer put on the system: no program files, menu entries, shortcuts or system settings.

User data is a separate decision, and each system has its custom:

Open the parcel¶

Sooner or later tauri build is not enough. There is a company policy to meet, a file to add or a field to fix, and you must know what is in the box. That is when you reach for external tools: packaging programs that do not belong to Tauri.

A .deb is an archive with two parts: control (the label) and data (the files). dpkg-deb is Debian's own tool for them:

dpkg-deb -I NoteBox_1.0.0_amd64.deb     # the label: Package, Version, Depends...
dpkg-deb -c NoteBox_1.0.0_amd64.deb     # the contents, file by file

Look for what you packed: usr/bin/notebox, usr/lib/NoteBox/resources/welcome-notes.json, the icons under usr/share/icons/hicolor/. And Depends: libwebkit2gtk-4.1-0, libgtk-3-0, the things that do not travel.

Tauri leaves its working folder next to the package, so you can repack it yourself and change one line of the label:

cd src-tauri/target/release/bundle/deb
mkdir -p pkg/DEBIAN && cp -r NoteBox_1.0.0_amd64/data/* pkg/
cp NoteBox_1.0.0_amd64/control/control pkg/DEBIAN/
# edit pkg/DEBIAN/control: Maintainer: Your Name <you@example.com>
dpkg-deb --build --root-owner-group pkg notebox-external.deb
dpkg-deb -I notebox-external.deb

That is a valid package, and no line of Tauri built it.

The same split exists inside the Tauri CLI, the command-line tool you have been using. npm run tauri build -- --no-bundle only compiles. npm run tauri bundle -- --bundles deb only packages. On Windows the external tools are makensis, the NSIS compiler, for which Tauri leaves the generated script in target\release\nsis\x64\installer.nsi, and WiX.

The update¶

NoteBox 1.0.0 is on 500 PCs and has a bug. How do the 500 get 1.0.1? Nobody reinstalls by hand. The app has to ask a server by itself. Here is the whole road:

flowchart LR
    subgraph DEV ["You"]
        A["<b>Tag</b><br>git tag v1.0.1"]
    end
    subgraph ROBOT ["CI: clean machines"]
        B["<b>Runners</b><br>Windows, Ubuntu, macOS"]
        C["<b>Build</b><br>tauri build"]
        D["<b>Seal 1</b><br>code signing"]
        E["<b>Seal 2</b><br>updater .sig"]
    end
    subgraph WEB ["The server"]
        F["<b>Upload</b><br>the packages"]
        G["<b>latest.json</b><br>newest version,<br>URL, signature"]
    end
    subgraph USER ["The user's PC"]
        H["<b>Installed app</b><br>asks, downloads,<br>verifies, installs"]
    end
    A --> B --> C --> D --> E --> F --> G --> H

On which station would a stolen laptop be a disaster? Wherever the private keys are.

It takes three pieces. First, install the plugins. The updater plugin does the updating and the process plugin restarts the app:

npm run tauri add updater
npm run tauri add process

Check that src-tauri/capabilities/default.json lists the permissions updater:default and process:default.

The config. In tauri.conf.json:

"bundle": {
  "createUpdaterArtifacts": true
},
"plugins": {
  "updater": {
    "pubkey": "CONTENT OF notebox.key.pub",
    "endpoints": ["https://example.com/notebox/latest.json"]
  }
}

pubkey is the text of the key, not a path to a file. In production the endpoint must use HTTPS. For the build to sign, the private key must be in the environment variable TAURI_SIGNING_PRIVATE_KEY. A .env file does not work for this, as the docs warn.

The announcement. A small file on your web server, latest.json:

{
  "version": "1.0.1",
  "notes": "Fixes the delete bug",
  "pub_date": "2027-02-19T10:00:00Z",
  "platforms": {
    "linux-x86_64": {
      "signature": "CONTENT OF THE .sig FILE",
      "url": "https://example.com/notebox/NoteBox_1.0.1_amd64.AppImage"
    }
  }
}

Only version and each platform's url and signature are required. The platform keys follow the form OS-ARCH, like windows-x86_64.

The app. Three calls:

import { check } from '@tauri-apps/plugin-updater';
import { relaunch } from '@tauri-apps/plugin-process';

const update = await check();
if (update) {
    await update.downloadAndInstall();
    await relaunch();
}

check() reads latest.json and compares versions. downloadAndInstall() fetches the file and verifies the seal against your public key. relaunch() restarts the app.

The robot that builds¶

tauri build only packages for the system it runs on. For three systems you need three machines, clean and identical every time.

Continuous integration (CI) is a service that runs your build commands on fresh machines when something happens in your repository. Each of those machines is a runner.

CI is not only for big teams. It is the way one person can release for three systems without owning three computers. This workflow is based on the example in the Tauri docs, trimmed to one machine per system. Read it for what it does: you are not asked to type it.

# .github/workflows/publish.yml
name: publish

on:
  workflow_dispatch:
  push:
    branches:
      - release

jobs:
  publish-tauri:
    permissions:
      contents: write
    strategy:
      fail-fast: false
      matrix:
        platform: [macos-latest, ubuntu-22.04, windows-latest]
    runs-on: ${{ matrix.platform }}
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v6
        with:
          node-version: lts/*
          cache: npm
      - uses: dtolnay/rust-toolchain@stable
      - name: Install Linux libraries
        if: matrix.platform == 'ubuntu-22.04'
        run: |
          sudo apt-get update
          sudo apt-get install -y libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf xdg-utils
      - run: npm install
      - uses: tauri-apps/tauri-action@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
          TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
        with:
          tagName: app-v__VERSION__
          releaseName: App v__VERSION__
          releaseBody: See the assets to download this version and install.
          releaseDraft: true
          prerelease: false

Why ubuntu-22.04 and not the newest? A Linux package built on an old system runs on newer ones, and not the reverse. A newer base can raise the minimum version of glibc, the system's core C library, and then your app fails on older systems with an error like GLIBC_2.33' not found. So you build on the oldest system you want to support that still has WebKitGTK 4.1.

Release checklist¶

Before you call a version finished, can you show a proof of each line?

Key takeaways¶

• A digital signature proves who sealed a file and that it was not changed. It says nothing about the contents.
• Code signing is checked by the operating system and is optional. The updater signature is checked by your own app and is mandatory. The private key is the secret, and the public key goes inside the app.
• An unattended install has no questions: apt install -y, /S for NSIS and /quiet for msiexec.
• A clean uninstall removes what the installer put on the system. User data is a separate decision, and it never goes away during an update.
• External tools like dpkg-deb let you inspect and rebuild a package outside tauri build.
• The updater reads latest.json, verifies the seal and installs. CI builds on clean runners, with the keys kept in secrets.

Quick check¶

That is the whole road: from a web app in a browser tab to a signed package that installs itself, leaves cleanly and updates on its own. An app people can actually install is no longer a prototype. Go back to the Unit 8 overview and check every outcome off the list.