Codesignierung

Codesignierung Ihrer Anwendung

Diese Anleitung beschreibt, wie Sie Ihre Wails-Anwendungen für macOS, Windows und Linux signieren. Wails v3 bietet integrierte CLI-Werkzeuge für Codesignierung, Notarisierung und die Verwaltung von PGP-Schlüsseln.

• macOS – Signieren und notarisieren Sie Ihre macOS-Anwendungen
• Windows – Signieren Sie Ihre ausführbaren Windows-Dateien und -Pakete
• Linux – Signieren Sie DEB- und RPM-Pakete mit PGP-Schlüsseln

Plattformübergreifende Signierungsmatrix

Diese Matrix zeigt, was Sie von jeder Quellplattform aus signieren können:

Signierungs-Backends

Wails wählt automatisch das beste verfügbare Signierungs-Backend aus:

Bei der Ausführung auf der nativen Plattform verwendet Wails für maximale Kompatibilität die nativen Werkzeuge. Bei der Cross-Kompilierung verwendet es die integrierte Signierungsunterstützung.

Schnellstart

Am schnellsten konfigurieren Sie die Signierung mit dem Einrichtungsassistenten:

wails3 setup

Dadurch wird eine gemeinsame Signierungskonfiguration in ~/.config/wails/defaults.yaml gespeichert, die beim Signieren auf jeder Plattform berücksichtigt wird (siehe Konfigurationsrangfolge). Der Signierungsschritt:

• Erkennt – von jedem Host aus –, welche Signierungswerkzeuge für die gewünschte Zielplattform installiert sind, und zeigt den Installationsbefehl für Ihr Betriebssystem an (z. B. brew install gnupg, sudo apt install osslsigncode, winget install GnuPG.Gpg4win).
• Listet unter macOS die Developer-ID-Zertifikate aus Ihrem Schlüsselbund auf.
• Listet für Linux Ihre GPG-Schlüssel auf und kann einen neuen Schlüssel erzeugen und exportieren.
• Kann für Windows über OpenSSL ein selbstsigniertes Zertifikat erzeugen (zu Testzwecken).
• Speichert Passwörter sicher im Schlüsselbund Ihres Systems (nicht in Taskfiles).

Konfigurationsrangfolge

Wenn Sie eine Signierungsaufgabe ausführen, wird jede Signierungsoption in dieser Reihenfolge aufgelöst (der erste Treffer gilt):

1. Ein explizit an wails3 tool sign übergebenes Flag (z. B. --pgp-key, --certificate, --identity).
2. Die entsprechende Taskfile-Variable des Projekts (PGP_KEY, SIGN_CERTIFICATE/SIGN_THUMBPRINT, SIGN_IDENTITY, …).
3. Die globale Konfiguration in ~/.config/wails/defaults.yaml (geschrieben von wails3 setup).

Das bedeutet, dass die Taskfile-Variablen optionale Überschreibungen sind: Ist eine Variable nicht gesetzt, wird der global konfigurierte Schlüssel, das global konfigurierte Zertifikat oder die global konfigurierte Identität verwendet. Liefert keine der drei Quellen einen Wert, meldet der Signierungsbefehl einen eindeutigen Fehler mit Hinweisen zur Konfiguration.

Projektbezogene Konfiguration

Um die Signierung nur für ein einzelnes Projekt statt global zu konfigurieren, führen Sie den projektbezogenen Assistenten im Projekt aus. Er schreibt vars in die build/<platform>/Taskfile.yml-Dateien dieses Projekts:

wails3 setup signing                                   # all detected platforms
wails3 setup signing --platform windows --platform linux

Manuelle Konfiguration

Alternativ können Sie die plattformspezifischen Taskfiles manuell bearbeiten. Bearbeiten Sie den Abschnitt vars am Anfang jeder Datei:

vars:
  SIGN_IDENTITY: "Developer ID Application: Your Company (TEAMID)"
  KEYCHAIN_PROFILE: "my-notarize-profile"
  # ENTITLEMENTS: "build/darwin/entitlements.plist"

wails3 task darwin:sign           # Sign only
wails3 task darwin:sign:notarize  # Sign and notarize

vars:
  SIGN_CERTIFICATE: "path/to/certificate.pfx"
  # Or use thumbprint instead:
  # SIGN_THUMBPRINT: "certificate-thumbprint"
  # TIMESTAMP_SERVER: "http://timestamp.digicert.com"

wails3 task windows:sign           # Sign executable
wails3 task windows:sign:installer # Sign NSIS installer

vars:
  PGP_KEY: "path/to/signing-key.asc"
  # SIGN_ROLE: "builder"  # Options: origin, maint, archive, builder

wails3 task linux:sign:deb       # Sign DEB package
wails3 task linux:sign:rpm       # Sign RPM package
wails3 task linux:sign:packages  # Sign all packages

Sie können den Signierungsstatus auch direkt über das System prüfen:

# List available macOS code-signing identities
security find-identity -v -p codesigning

# List PGP keys (Linux package signing)
gpg --list-keys

Verwenden Sie für die interaktive Einrichtung der Signierungskonfiguration aller Plattformen den Assistenten:

wails3 setup signing

Codesignierung unter macOS

Voraussetzungen

• Apple-Developer-Account ($99/Jahr)
• Developer ID Application-Zertifikat
• Installierte Xcode Command Line Tools

Signierungsidentitäten

Prüfen Sie die verfügbaren Signierungsidentitäten:

security find-identity -v -p codesigning

Ausgabe:

Found 2 signing identities:

  Developer ID Application: Your Company (ABCD1234) [valid]
    Hash: ABC123DEF456...

  Apple Development: your@email.com (XYZ789) [valid]
    Hash: DEF789ABC123...

Konfiguration

Bearbeiten Sie build/darwin/Taskfile.yml und legen Sie die Signierungsvariablen fest:

vars:
  SIGN_IDENTITY: "Developer ID Application: Your Company (TEAMID)"
  KEYCHAIN_PROFILE: "my-notarize-profile"
  ENTITLEMENTS: "build/darwin/entitlements.plist"

Führen Sie anschließend Folgendes aus:

wails3 task darwin:sign           # Build, package, and sign
wails3 task darwin:sign:notarize  # Build, package, sign, and notarize

Entitlements

Entitlements steuern, auf welche Funktionen Ihre App zugreifen darf. Wails-Apps benötigen für Entwicklung und Produktion in der Regel unterschiedliche Entitlements:

• Entwicklung: Erfordert Entitlements für JIT, nicht signierten Speicher und Debugging
• Produktion: Minimale Entitlements (nur Netzwerkzugriff)

Verwenden Sie den interaktiven Einrichtungsassistenten, um beide Dateien zu erzeugen:

wails3 setup entitlements

Dadurch werden folgende Dateien erstellt:

• build/darwin/entitlements.dev.plist – Für Entwicklungs-Builds
• build/darwin/entitlements.plist – Für Produktions-/signierte Builds

Verfügbare Voreinstellungen:\

Legen Sie anschließend in den Variablen Ihres Taskfiles ENTITLEMENTS so fest, dass es auf die entsprechende Datei verweist.

Beglaubigung

Apple verlangt, dass alle verteilten Apps beglaubigt werden.

xcrun notarytool store-credentials "my-notarize-profile" \
  --apple-id "your@email.com" \
  --team-id "ABCD1234" \
  --password "app-specific-password"

wails3 task darwin:sign:notarize

spctl --assess --verbose=2 bin/MyApp.app

Codesignierung unter Windows

Voraussetzungen

• Codesignierungszertifikat (von DigiCert, Sectigo usw.)
• Für die native Signierung unter Windows: installiertes Windows SDK (für signtool.exe)
• Für plattformübergreifendes Signieren unter macOS/Linux: osslsigncode (im Signierschritt wails3 setup wird der hostspezifische Installationsbefehl angezeigt)

Selbstsigniertes Zertifikat erzeugen (Testzwecke)

Wenn Sie lediglich die Signierpipeline testen möchten, führen Sie wails3 setup aus, öffnen Sie im Signierschritt die Registerkarte Windows und wählen Sie Selbstsigniertes Zertifikat erzeugen. Dabei wird mit OpenSSL eine Codesignatur-.pfx erstellt und ihr Pfad in der globalen Konfiguration gespeichert.

Konfiguration

Bearbeiten Sie build/windows/Taskfile.yml und legen Sie die Signiervariablen fest:

vars:
  SIGN_CERTIFICATE: "path/to/certificate.pfx"
  # Or use thumbprint instead:
  # SIGN_THUMBPRINT: "certificate-thumbprint"
  # TIMESTAMP_SERVER: "http://timestamp.digicert.com"

Führen Sie anschließend Folgendes aus:

wails3 task windows:sign           # Build and sign executable
wails3 task windows:sign:installer # Build and sign NSIS installer

Plattformübergreifendes Signieren

Ausführbare Windows-Dateien können auf jeder Plattform signiert werden. Dieselbe Taskfile-Konfiguration und dieselben Befehle funktionieren unter macOS und Linux.

Unterstützte Windows-Formate

Signieren von Linux-Paketen

Linux-Pakete (DEB und RPM) werden mit PGP-/GPG-Schlüsseln signiert. Anders als die Codesignierung unter Windows und macOS weist das Signieren von Linux-Paketen nach, dass das Paket aus einer vertrauenswürdigen Quelle stammt, und nicht, dass das Betriebssystem dem Code vertraut.

Voraussetzungen

• PGP-Schlüsselpaar (kann mit Wails erzeugt werden)

PGP-Schlüssel erzeugen

Am einfachsten geht dies mit dem Einrichtungsassistenten: Führen Sie wails3 setup aus, öffnen Sie im Signierschritt die Registerkarte Linux und wählen Sie Neuen GPG-Schlüssel erstellen. Der Assistent:

• erzeugt einen RSA-4096-Schlüssel in Ihrem GPG-Schlüsselbund (lassen Sie die Passphrase für einen unbeaufsichtigt verwendbaren, CI-geeigneten Schlüssel leer),
• exportiert ihn nach ~/.wails/signing/<keyid>.asc (die Datei, mit der ein Build signiert wird) und
• speichert sowohl die Schlüssel-ID als auch den Exportpfad in ~/.config/wails/defaults.yaml, sodass der Schlüssel beim Signieren automatisch verwendet wird.

Sie können dies mit gpg auch manuell durchführen:

# Interactive — the wizard will prompt for name, email, key size and expiry.
gpg --full-generate-key

# Export the key pair to ASCII-armoured files for the Taskfile to consume.
gpg --armor --export-secret-keys "your@email.com" > signing-key.asc
gpg --armor --export "your@email.com" > signing-key.pub.asc

Empfohlene Einstellungen: RSA mit 4096 Bit, 1 Jahr Gültigkeitsdauer und Schutz durch ein starkes Passwort.

Konfiguration

Bearbeiten Sie build/linux/Taskfile.yml und legen Sie die Signiervariablen fest:

vars:
  PGP_KEY: "path/to/signing-key.asc"
  # SIGN_ROLE: "builder"  # Options: origin, maint, archive, builder

Führen Sie anschließend Folgendes aus:

wails3 task linux:sign:deb       # Build and sign DEB package
wails3 task linux:sign:rpm       # Build and sign RPM package
wails3 task linux:sign:packages  # Build and sign all packages

DEB-Signaturrollen

Für DEB-Pakete können Sie die Signaturrolle über SIGN_ROLE angeben:

• origin: Signatur des Paketursprungs
• maint: Signatur des Paketbetreuers
• archive: Signatur des Archivbetreuers
• builder: Signatur des Paketerstellers (Standard)

Plattformübergreifendes Signieren

Linux-Pakete können auf jeder Plattform signiert werden. Dieselbe Taskfile-Konfiguration und dieselben Befehle funktionieren unter Windows und macOS.

Schlüsselinformationen anzeigen

gpg --show-keys signing-key.asc

Ausgabe:

pub   rsa4096 2024-01-15 [SC] [expires: 2025-01-15]
      1234 5678 90AB CDEF 1234 5678 90AB CDEF 1234 5678
uid                      Your Name <your@email.com>

Linux-Pakete überprüfen

# Verify DEB signature
dpkg-sig --verify myapp_1.0.0_amd64.deb

# Verify RPM signature
rpm --checksig myapp-1.0.0.x86_64.rpm

Öffentlichen Schlüssel verteilen

Benutzer benötigen Ihren öffentlichen Schlüssel, um Pakete zu überprüfen:

# Export public key for distribution
gpg --armor --export "your@email.com" > myapp-signing.pub.asc

# Users can import it:
# For DEB (apt):
sudo apt-key add myapp-signing.pub.asc
# Or for modern apt:
sudo cp myapp-signing.pub.asc /etc/apt/trusted.gpg.d/

# For RPM:
sudo rpm --import myapp-signing.pub.asc

GitHub-Actions-Integration

In CI-Umgebungen werden Passwörter über Umgebungsvariablen statt über den Schlüsselbund des Systems bereitgestellt:

Sie können Taskfile-Variablen auch direkt übergeben:

wails3 task darwin:sign SIGN_IDENTITY="$SIGN_IDENTITY" KEYCHAIN_PROFILE="$KEYCHAIN_PROFILE"

macOS-Workflow

name: Build and Sign macOS

on:
  push:
    tags: ['v*']

jobs:
  build:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.23'

      - name: Install Wails
        run: go install github.com/wailsapp/wails/v3/cmd/wails3@latest

      - name: Import Certificate
        env:
          CERTIFICATE_BASE64: ${{ secrets.MACOS_CERTIFICATE }}
          CERTIFICATE_PASSWORD: ${{ secrets.MACOS_CERTIFICATE_PASSWORD }}
        run: |
          echo $CERTIFICATE_BASE64 | base64 --decode > certificate.p12
          security create-keychain -p "" build.keychain
          security default-keychain -s build.keychain
          security unlock-keychain -p "" build.keychain
          security import certificate.p12 -k build.keychain -P "$CERTIFICATE_PASSWORD" -T /usr/bin/codesign
          security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k "" build.keychain

      - name: Store Notarization Credentials
        env:
          APPLE_ID: ${{ secrets.APPLE_ID }}
          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
          APPLE_APP_PASSWORD: ${{ secrets.APPLE_APP_PASSWORD }}
        run: |
          xcrun notarytool store-credentials "notarize-profile" \
            --apple-id "$APPLE_ID" \
            --team-id "$APPLE_TEAM_ID" \
            --password "$APPLE_APP_PASSWORD"

      - name: Build, Sign, and Notarize
        env:
          SIGN_IDENTITY: ${{ secrets.MACOS_SIGN_IDENTITY }}
        run: |
          wails3 task darwin:sign:notarize \
            SIGN_IDENTITY="$SIGN_IDENTITY" \
            KEYCHAIN_PROFILE="notarize-profile"

      - name: Upload Artifact
        uses: actions/upload-artifact@v4
        with:
          name: MyApp-macOS
          path: bin/*.app

Windows-Workflow

name: Build and Sign Windows

on:
  push:
    tags: ['v*']

jobs:
  build:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.23'

      - name: Install Wails
        run: go install github.com/wailsapp/wails/v3/cmd/wails3@latest

      - name: Import Certificate
        env:
          CERTIFICATE_BASE64: ${{ secrets.WINDOWS_CERTIFICATE }}
        run: |
          $certBytes = [Convert]::FromBase64String($env:CERTIFICATE_BASE64)
          [IO.File]::WriteAllBytes("certificate.pfx", $certBytes)

      - name: Build and Sign
        env:
          WAILS_WINDOWS_CERT_PASSWORD: ${{ secrets.WINDOWS_CERTIFICATE_PASSWORD }}
        run: |
          wails3 task windows:sign SIGN_CERTIFICATE=certificate.pfx

      - name: Upload Artifact
        uses: actions/upload-artifact@v4
        with:
          name: MyApp-Windows
          path: bin/*.exe

Plattformübergreifender Workflow (Linux-Runner)

Signieren Sie Windows- und Linux-Pakete mit einem einzigen Linux-Runner:

name: Build and Sign (Cross-Platform)

on:
  push:
    tags: ['v*']

jobs:
  build-and-sign:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.23'

      - name: Install Wails
        run: go install github.com/wailsapp/wails/v3/cmd/wails3@latest

      - name: Install Build Dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y nsis rpm

      # Import certificates
      - name: Import Certificates
        env:
          WINDOWS_CERT_BASE64: ${{ secrets.WINDOWS_CERTIFICATE }}
          PGP_KEY_BASE64: ${{ secrets.PGP_PRIVATE_KEY }}
        run: |
          echo "$WINDOWS_CERT_BASE64" | base64 -d > certificate.pfx
          echo "$PGP_KEY_BASE64" | base64 -d > signing-key.asc

      # Build and sign Windows
      - name: Build and Sign Windows
        env:
          WAILS_WINDOWS_CERT_PASSWORD: ${{ secrets.WINDOWS_CERTIFICATE_PASSWORD }}
        run: |
          wails3 task windows:sign SIGN_CERTIFICATE=certificate.pfx

      # Build and sign Linux packages
      - name: Build and Sign Linux Packages
        env:
          WAILS_PGP_PASSWORD: ${{ secrets.PGP_PASSWORD }}
        run: |
          wails3 task linux:sign:packages PGP_KEY=signing-key.asc

      # Cleanup secrets
      - name: Cleanup
        if: always()
        run: rm -f certificate.pfx signing-key.asc

      - name: Upload Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: signed-binaries
          path: |
            bin/*.exe
            bin/*.deb
            bin/*.rpm

CLI-Referenz

wails3 setup signing

Interaktiver Assistent zum Konfigurieren der Signierung für Ihr Projekt.

wails3 setup signing [flags]

Flags:
  --platform    Platform to configure (darwin, windows, linux). Repeatable.
                If omitted, auto-detects which platforms to configure from the build directory.

Der Assistent führt Sie durch folgende Schritte:

• macOS: Auswählen eines Developer-ID-Zertifikats und Konfigurieren der Anmeldedaten für die Beglaubigung (ruft xcrun notarytool store-credentials auf).
• Windows: Auswählen zwischen Zertifikatsdatei und Fingerabdruck sowie Festlegen von Passwort und Zeitstempelserver.
• Linux: Verwenden eines vorhandenen PGP-Schlüssels oder Erzeugen eines neuen Schlüssels (ruft gpg auf) sowie Konfigurieren der Signaturrolle.

wails3 setup entitlements

Interaktiver Assistent zum Konfigurieren von macOS-Berechtigungen.

wails3 setup entitlements [flags]

Flags:
  --output    Output path for entitlements.plist (default: build/darwin/entitlements.plist)

Voreinstellungen:

• Entwicklung: Erstellt entitlements.dev.plist mit Berechtigungen für JIT, Debugging und Netzwerkzugriff
• Produktion: Erstellt entitlements.plist mit minimalen Berechtigungen
• Beide: Erstellt beide Dateien (empfohlen)
• App Store: Erstellt Sandbox-Berechtigungen für den Mac App Store
• Benutzerdefiniert: Einzelne Berechtigungen und Zieldatei auswählen

wails3 sign

Signiert Binärdateien und Pakete für die aktuelle oder angegebene Plattform. Dies ist ein Wrapper, der die entsprechende plattformspezifische Signatur-Task aufruft.

wails3 sign
wails3 sign GOOS=darwin
wails3 sign GOOS=windows
wails3 sign GOOS=linux

Dadurch wird die entsprechende Task <platform>:sign ausgeführt, die die Signaturkonfiguration aus Ihrem Taskfile verwendet.

wails3 tool sign

Low-Level-Befehl zum direkten Signieren einer bestimmten Datei. Wird intern von den Taskfiles verwendet.

wails3 tool sign [flags]

Allgemeine Optionen:\

Flags für Windows/macOS:\

macOS-spezifische Flags:\

Windows-spezifische Flags:\

Linux-spezifische Flags:\

Signierungsstatus prüfen (native Werkzeuge)

In v3 gibt es keinen wails3 signing-Befehl. Verwenden Sie zum Prüfen des Signierungsstatus direkt die nativen Werkzeuge:

Fehlerbehebung

macOS-Probleme

„Kein Developer-ID-Zertifikat gefunden“

• Stellen Sie sicher, dass Ihr Zertifikat im Schlüsselbund installiert ist
• Prüfen Sie mit security find-identity -v -p codesigning, dass es nicht abgelaufen ist.
• Stellen Sie sicher, dass Sie über ein „Developer ID Application“-Zertifikat verfügen (nicht nur über „Apple Development“)

„Beglaubigung fehlgeschlagen“

• Prüfen Sie das Beglaubigungsprotokoll: xcrun notarytool log <submission-id> --keychain-profile <profile>
• Stellen Sie sicher, dass die Hardened Runtime aktiviert ist
• Vergewissern Sie sich, dass Ihre App keine unsignierten Binärdateien enthält

„Codesign fehlgeschlagen“

• Stellen Sie sicher, dass der Schlüsselbund entsperrt ist: security unlock-keychain
• Prüfen Sie die Dateiberechtigungen des App-Bundles

Windows-Probleme

„Zertifikat nicht gefunden“

• Überprüfen Sie, ob der Zertifikatspfad korrekt ist
• Prüfen Sie das Zertifikatspasswort
• Stellen Sie sicher, dass das Zertifikat gültig ist (nicht abgelaufen oder widerrufen)

„Fehler des Zeitstempelservers“

• Versuchen Sie es mit einem anderen Zeitstempelserver:
  • http://timestamp.digicert.com
  • http://timestamp.sectigo.com
  • http://timestamp.comodoca.com

Linux-Probleme

„Ungültiger PGP-Schlüssel“

• Stellen Sie sicher, dass die Schlüsseldatei im ASCII-armierten Format vorliegt
• Stellen Sie mit gpg --show-keys <key.asc> sicher, dass der Schlüssel nicht abgelaufen ist
• Überprüfen Sie, ob das Passwort korrekt ist

„Signaturprüfung fehlgeschlagen“

• Stellen Sie sicher, dass der öffentliche Schlüssel ordnungsgemäß importiert wurde
• Stellen Sie sicher, dass das Paket nach dem Signieren nicht verändert wurde

Weitere Ressourcen

Offizielle Dokumentation

• Apple-Leitfaden zur Codesignierung
• Apple-Dokumentation zur Notarisierung
• Microsoft-Codesignierung
• Signieren von Debian-Paketen
• Signieren von RPM-Paketen