aza/AzA march 2026 - Kopie (18)/SIGNING_READINESS.md

# 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 |