171 lines
6.4 KiB
Markdown
171 lines
6.4 KiB
Markdown
# AZA Desktop — Signing Readiness
|
||
|
||
## Warum Code Signing?
|
||
|
||
Windows **Smart App Control** (ab Windows 11 22H2) blockiert unbekannte und unsignierte
|
||
Anwendungen automatisch. Auch ohne Smart App Control zeigt Windows SmartScreen bei
|
||
unsignierten Downloads Warnungen, die Kunden verunsichern.
|
||
|
||
**Ziel:** Alle Kundenauslieferungen von AZA Desktop werden mit einem gültigen
|
||
Code-Signing-Zertifikat signiert, um Blockaden und Warnungen zu vermeiden.
|
||
|
||
---
|
||
|
||
## Artefakte, die signiert werden müssen
|
||
|
||
### Priorität 1 — Kritisch (blockiert Smart App Control)
|
||
|
||
| Artefakt | Pfad (nach Build) | Warum |
|
||
|---|---|---|
|
||
| **Haupt-EXE** | `dist\aza_desktop\aza_desktop.exe` | Wird direkt ausgeführt, primäres Ziel von Smart App Control |
|
||
| **Installer** | `dist\installer\aza_desktop_setup.exe` | Erste Datei die der Kunde herunterlädt und startet |
|
||
|
||
### Priorität 2 — Empfohlen (verhindert DLL-Warnungen)
|
||
|
||
| Artefakt | Pfad (nach Build) | Warum |
|
||
|---|---|---|
|
||
| **DLLs in _internal** | `dist\aza_desktop\_internal\*.dll` | Werden zur Laufzeit geladen; einige Sicherheits-Tools prüfen auch geladene DLLs |
|
||
| **PYDs in _internal** | `dist\aza_desktop\_internal\*.pyd` | Python-Extensions (sind technisch DLLs) |
|
||
|
||
### Nicht signieren
|
||
|
||
- Daten-Dateien (`.json`, `.sqlite`, `.txt`, `.env`, `.png`, `.ico`)
|
||
- Python-Bytecode (`.pyc`)
|
||
- Konfigurationsdateien
|
||
|
||
---
|
||
|
||
## Signing-Reihenfolge
|
||
|
||
Die Reihenfolge ist wichtig, da der Installer die bereits signierten Dateien einpackt:
|
||
|
||
```
|
||
1. build_exe.ps1 → aza_desktop.exe + _internal/
|
||
2. sign_release.ps1 → DLLs/PYDs signieren, dann EXE signieren
|
||
3. build_installer.ps1 → Installer aus signierten Dateien bauen
|
||
4. sign_release.ps1 → Installer signieren (oder im selben Lauf)
|
||
5. build_release_artifacts.ps1 → SHA256-Hashes aktualisieren
|
||
6. build_publish_bundle.ps1 → Publish-Bundle erstellen
|
||
```
|
||
|
||
In der aktuellen Pipeline (`build_and_test_release.ps1`) ist der Signing-Schritt
|
||
bereits als optionaler Schritt zwischen Installer-Build und Smoke-Test eingefügt.
|
||
Er wird nur ausgeführt, wenn ein Zertifikat konfiguriert ist.
|
||
|
||
---
|
||
|
||
## Zertifikat beschaffen
|
||
|
||
### Option A: Klassisches EV Code-Signing-Zertifikat (empfohlen für KMU)
|
||
|
||
- Anbieter: DigiCert, Sectigo, GlobalSign
|
||
- Typ: **EV Code Signing** (Extended Validation)
|
||
- Vorteile:
|
||
- Sofortige SmartScreen-Reputation (kein Reputation-Aufbau nötig)
|
||
- Höchstes Vertrauen bei Smart App Control
|
||
- Lieferform: Hardware-Token (USB) oder Cloud-HSM
|
||
- Kosten: ca. CHF 400–600 / Jahr
|
||
- Validierung: Firma muss im Handelsregister eingetragen sein
|
||
|
||
### Option B: Azure Trusted Signing (Microsoft)
|
||
|
||
- Dienst: Azure Trusted Signing (ehemals Azure Code Signing)
|
||
- Vorteile:
|
||
- Direkte Microsoft-Reputation
|
||
- Kein Hardware-Token nötig
|
||
- CI/CD-Integration via Azure CLI
|
||
- Voraussetzungen:
|
||
- Azure-Konto
|
||
- Identitätsvalidierung über Microsoft
|
||
- Kosten: ab ca. USD 10 / Monat (Basic-Tier)
|
||
|
||
### Empfehlung
|
||
|
||
Für **AZA MedWork** empfehle ich **Option A (EV Code Signing)**, weil:
|
||
- Sofortige SmartScreen-Reputation ohne Aufbauphase
|
||
- Funktioniert unabhängig von Cloud-Diensten
|
||
- Breite Akzeptanz bei allen Windows-Versionen
|
||
|
||
---
|
||
|
||
## Umgebungsvariablen für sign_release.ps1
|
||
|
||
| Variable | Beschreibung | Pflicht |
|
||
|---|---|---|
|
||
| `AZA_SIGN_CERT_THUMBPRINT` | SHA-1 Thumbprint des Zertifikats im Windows Certificate Store | Eins von beiden |
|
||
| `AZA_SIGN_PFX_PATH` | Pfad zur .pfx-Datei | Eins von beiden |
|
||
| `AZA_SIGN_PFX_PASSWORD` | Passwort der .pfx-Datei | Optional |
|
||
| `AZA_SIGN_TIMESTAMP_URL` | Timestamp-Server (Standard: `http://timestamp.digicert.com`) | Optional |
|
||
| `AZA_SIGNTOOL_PATH` | Pfad zu signtool.exe (Standard: automatische Suche) | Optional |
|
||
|
||
**Wichtig:** Keine Zertifikate oder Passwörter ins Repository committen!
|
||
|
||
---
|
||
|
||
## Konsistente Publisher-Identität
|
||
|
||
Für optimale SmartScreen-/Smart-App-Control-Reputation:
|
||
|
||
- **Immer denselben Publisher-Namen** verwenden
|
||
- **Immer dasselbe Zertifikat** für alle Releases verwenden
|
||
- Der Publisher-Name im Inno-Setup-Installer (`AppPublisher`) muss mit dem
|
||
Zertifikats-Subject übereinstimmen
|
||
- Nach Festlegung den Publisher-Namen **nicht mehr ändern** (Reputationsverlust)
|
||
|
||
### Aktuelle Namensformen im Projekt (Stand 2026-03-23)
|
||
|
||
| Namensform | Rolle | Signing-relevant |
|
||
|---|---|---|
|
||
| **AZA MedWork** | Firma / Publisher | **JA** |
|
||
| **AZA Desktop** | Produktname | Nein |
|
||
| **AZA Medical AI Assistant** | Interner Projektname / Marketing | Nein |
|
||
|
||
Aktueller Wert in `installer\aza_installer.iss`: `AppPublisher = "AZA MedWork"`
|
||
|
||
### Vor Zertifikatskauf prüfen
|
||
|
||
1. Wie lautet der offizielle Firmenname im Handelsregister?
|
||
(z.B. "AZA MedWork", "AZA MedWork GmbH", "MedWork GmbH")
|
||
2. EV-Zertifikats-Anbieter validiert gegen den HR-Eintrag
|
||
3. Subject/CN/O im Zertifikat muss EXAKT zum HR-Namen passen
|
||
4. `AppPublisher` in `aza_installer.iss` muss EXAKT zum Zertifikat passen
|
||
5. Falls HR-Name von "AZA MedWork" abweicht, folgende Stellen gemeinsam anpassen:
|
||
- `installer/aza_installer.iss` → `MyAppPublisher`
|
||
- `legal/privacy_policy.md`
|
||
- `legal/ai_consent.md`
|
||
- `deploy/WOOCOMMERCE_PRODUCT.md` (Absendername)
|
||
- `deploy/WORDPRESS_GOLIVE.md` (Absendername)
|
||
- `apps/diktat/diktat_app.py` (Docstring)
|
||
- `aza_consent.py` (Docstring)
|
||
|
||
### Nicht anpassen (nicht signing-relevant)
|
||
|
||
- `project_status.json` → "AZA Medical AI Assistant" (interner Projektname)
|
||
- `billing/invoice_template.json` → "AZA Medical AI Assistant License" (Rechnungsposition)
|
||
- `web/index.html`, `web/download.html` → Marketing-Footer
|
||
|
||
---
|
||
|
||
## Checkliste vor erstem signierten Release
|
||
|
||
- [ ] EV Code-Signing-Zertifikat beschafft
|
||
- [ ] signtool.exe installiert (Windows SDK)
|
||
- [ ] Umgebungsvariablen gesetzt (AZA_SIGN_CERT_THUMBPRINT oder PFX)
|
||
- [ ] `sign_release.ps1 -DryRun` erfolgreich durchlaufen
|
||
- [ ] `sign_release.ps1` erfolgreich durchlaufen (echter Signing-Lauf)
|
||
- [ ] Signatur mit `Get-AuthenticodeSignature` verifiziert
|
||
- [ ] `build_release_artifacts.ps1` erneut ausgeführt (Hashes aktualisiert)
|
||
- [ ] Installer auf sauberem Windows-PC getestet (Smart App Control aktiv)
|
||
- [ ] Publisher-Name im Zertifikat stimmt mit Inno-Setup `AppPublisher` überein
|
||
|
||
---
|
||
|
||
## Dateien in diesem Projekt (Signing-bezogen)
|
||
|
||
| Datei | Zweck |
|
||
|---|---|
|
||
| `sign_release.ps1` | Signing-Skript (signiert EXE, DLLs, Installer) |
|
||
| `build_and_test_release.ps1` | Release-Pipeline (Signing-Schritt integriert) |
|
||
| `build_release_artifacts.ps1` | Artefakt-Report (enthält jetzt Signatur-Status) |
|
||
| `SIGNING_READINESS.md` | Diese Dokumentation |
|