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