Sicherheitsleitfaden

Die winapp CLI erleichtert die lokale Windows Entwicklung: Sie kann ein Signaturzertifikat generieren, dem Computer vertrauen und den Entwicklermodus für Sie aktivieren. Jeder dieser Schritte ändert den Computerzustand oder erstellt eine Datei, die einen privaten Schlüssel trägt, sodass sie genau wissen können, was sie tun.

Auf dieser Seite wird die Konsequenz der einzelnen Befehle erläutert, wie Sie ihn rückgängig machen und was beim Versenden anders zu tun ist. Entwicklungszertifikate und der Entwicklermodus sind der normale, unterstützte Weg für lokale Tests – hier geht es darum, dass Sie verstehen, worauf Sie sich einlassen, nicht darum, sie zu vermeiden.

Entwicklungszertifikate

MSIX-Pakete müssen signiert werden, bevor Windows sie installieren. Für lokale Tests erstellt winapp cert generate ein selbstsigniertes Zertifikat, damit Sie Ihr eigenes Paket signieren und installieren können, ohne etwas kaufen zu müssen.

Was winapp cert generate erstellt

Das generierte Zertifikat ist ein selbstsigniertes, Endentitätscodesignaturzertifikat:

Der Befehl schreibt zwei Dinge:

• devcert.pfx im aktuellen Verzeichnis (oder in dem Pfad, den Sie an --output übergeben). Diese Datei enthält sowohl das Zertifikat als auch den privaten Schlüssel.
• Eine Kopie des Zertifikats in Ihrem persönlichen Zertifikatspeicher (Cert:\CurrentUser\My).

Mit --export-cer wird auch eine .cer-Datei neben der .pfx geschrieben. Diese Datei enthält nur das öffentliche Zertifikat – keinen privaten Schlüssel – was es zum richtigen Zeitpunkt macht, an einen Teamkollegen oder einen Testcomputer zu übergeben, der Ihren Builds vertrauen muss.

Das Standardkennwort

winapp cert generate verwendet password als PFX-Kennwort, es sei denn, Sie geben --password an. Dieselbe Standardeinstellung gilt auch, wenn Sie dieses Zertifikat später winapp sign bereitstellen, dessen Kennwortoption ebenfalls --password ist, sowie winapp pack, das --cert-password verwendet.

Ein allgemein bekanntes Kennwort bedeutet, dass der private Schlüssel in devcert.pfx praktisch ungeschützt ist – jeder, der die Datei erhält, kann damit Code signieren. Das ist ein vertretbarer Kompromiss für ein Wegwerf-Zertifikat, das ausschließlich lokale Test-Builds auf Ihrem eigenen Rechner signiert, und deshalb gibt es diese Voreinstellung.

Skripts und Agenten müssen das Kennwort nicht selbst vergleichen: winapp cert generate --json meldet "defaultPasswordIsPublic": true und wiederholt die Angabe in einem warnings-Array, wenn der Standardwert verwendet wird. Siehe JSON-Ausgabe für cert generate.

Wo sich die Zertifikatdatei befindet

devcert.pfx ist ein privater Schlüssel auf dem Datenträger. Zwei Regeln bewahren es vor Schwierigkeiten:

Bitte nicht committen.winapp cert generate hängt den Dateinamen des Zertifikats automatisch an .gitignore daneben an, sodass der Standardablauf bereits abgedeckt ist. Wenn Sie die Datei verschieben, umbenennen oder in einem Verzeichnis generieren, das von einem anderen .gitignoreverwaltet wird, überprüfen Sie, ob der Eintrag darauf folgt:

git check-ignore -v devcert.pfx

Wenn nichts gedruckt wird, wird die Datei nicht ignoriert – fügen Sie sie hinzu, bevor Sie einen Commit ausführen.

Bitte nicht paketieren.winapp pack packt alles im Eingabeverzeichnis, sodass eine devcert.pfx, die sich im Ausgabeordner Ihrer App befindet, im ausgelieferten MSIX landet. Generieren Sie das Zertifikat außerhalb des Ordners, den Sie verpacken, wie das Verpacken eines EXE/CLI-Handbuchs zeigt, und bestätigen Sie, dass es nicht vorhanden ist, bevor Sie verteilen:

# Unpack the package and check that no certificate is inside
winapp tool makeappx unpack /p .\MyApp.msix /d .\inspect /o
Get-ChildItem .\inspect -Recurse -Include *.pfx, *.cer

Was winapp cert install gewährt

winapp cert install fügt das Zertifikat dem LocalMachine\TrustedPeople Speicher hinzu. Dies erfordert Administratorrechte, da sie die Vertrauensstellung für jeden Benutzer auf dem Computer ändert.

Sobald sich ein Zertifikat in TrustedPeople befindet, akzeptiert Windows jedes MSIX-Paket, das mit diesem Zertifikat signiert ist, als so vertrauenswürdig, dass es installiert werden kann – nicht nur das Paket, das Sie testen. Für ein Zertifikat, dessen privater Schlüssel Sie lokal speichern und beibehalten, ist dies genau der beabsichtigte Effekt. Es ist auch der Grund, darüber bewusst zu sein:

• Vertrauen Sie Zertifikaten, die Sie selbst generiert haben oder von jemandem stammen, dem Sie die Installation von Software auf dem Computer erlauben würden.
• Installieren Sie kein Entwicklungszertifikat auf gemeinsam genutzten, Produktions- oder Buildcomputern, auf denen andere Personen angewiesen sind.
• Bevorzugen Sie die Verteilung des .cer (nur öffentlichen Schlüssels) und nicht die .pfx Verteilung, wenn ein Kollege Ihr Testpaket installieren muss. Sie erhalten die Möglichkeit, Ihren Builds zu vertrauen, ohne die Fähigkeit zu erlangen, in Ihrem Namen zu signieren.

Um einem .cer auf einem anderen Testcomputer zu vertrauen, führen Sie winapp cert install direkt darauf aus – der Befehl akzeptiert entweder ein .pfx oder ein reines öffentliches .cer:

# Run as Administrator
winapp cert install .\devcert.cer

Das Äquivalent, das nur integrierte Windows Tools verwendet, ist:

# Run as Administrator
Import-Certificate -FilePath .\devcert.cer -CertStoreLocation Cert:\LocalMachine\TrustedPeople

Entfernen eines vertrauenswürdigen Zertifikats

Entwicklungszertifikate laufen standardmäßig nach einem Jahr ab, doch ihr Ablauf bedeutet nicht, dass sie entfernt werden. Wenn Sie ein Zertifikat nicht mehr benötigen – weil das Projekt beendet ist, die Maschine anderweitig verwendet wird oder der Schlüssel möglicherweise kompromittiert wurde –, entfernen Sie es ausdrücklich.

Suchen Sie zuerst seinen Fingerabdruck:

Get-ChildItem Cert:\LocalMachine\TrustedPeople |
    Where-Object { $_.Subject -like '*CN=Contoso*' } |
    Format-List Subject, Thumbprint, NotAfter

Entfernen Sie es dann aus dem Vertrauensspeicher des Computers. Für diesen Schritt ist eine Erhöhung erforderlich:

# Run as Administrator. Replace with the thumbprint from the previous command.
$thumbprint = 'ABCD...'
Remove-Item -Path "Cert:\LocalMachine\TrustedPeople\$thumbprint"

cert generate außerdem das Zertifikat zusammen mit seinem privaten Schlüssel in Ihrem persönlichen Speicher platziert. Entfernen Sie das aus einer normalen Eingabeaufforderung ohne erhöhte Rechte, während Sie mit dem Konto angemeldet sind, mit dem cert generate ausgeführt wurde:

$thumbprint = 'ABCD...'
Remove-Item -Path "Cert:\CurrentUser\My\$thumbprint"

Löschen Sie schließlich .pfx und alle von Ihnen ausgegebenen .cer-Kopien, und heben Sie die Registrierung der Pakete auf, die Sie damit quergeladen haben:

winapp unregister

Entwicklermodus

Windows erfordert, dass im Entwicklermodus ein App-Paket direkt von einem Ordner auf dem Datenträger registriert wird – ein loses Layout – statt ein integriertes, signiertes MSIX zu installieren. Befehle wie winapp run und create-debug-identity sind darauf angewiesen und schlagen ohne dies fehl, und winapp init bietet an, dies für Sie zu aktivieren.

Was sich durch das Aktivieren ändert

Die CLI aktiviert den Entwicklermodus durch Schreiben von zwei DWORD Werten unter HKEY_LOCAL_MACHINE:

HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock
    AllowDevelopmentWithoutDevLicense = 1
    AllowAllTrustedApps               = 1

Da es sich hierbei um computerweite Einstellungen handelt, startet die CLI einen Hilfsprozess mit erhöhten Rechten und Windows zeigt eine Eingabeaufforderung für die Benutzerkontensteuerung an. Wenn Sie die Eingabeaufforderung ablehnen, wird nichts geändert.

Praktisch bedeutet dies, dass die Maschine:

• Registrieren Sie App-Pakete direkt von einem Ordner auf dem Datenträger, ohne dass sie in ein MSIX integriert oder überhaupt signiert werden (AllowDevelopmentWithoutDevLicense).
• Installieren Sie App-Pakete von außerhalb der Microsoft Store, solange sie von einem Zertifikat signiert sind, dem der Computer vertraut – einschließlich aller Entwicklungszertifikate in TrustedPeople (AllowAllTrustedApps).

Steuern, wann sie aktiviert ist

winapp init fragt vor jeder Änderung nach, und --use-defaults überspringt die Frage vollständig, sodass der Entwicklermodus unverändert bleibt. Dadurch werden Skripts und CI standardmäßig sicher ausgeführt:

winapp init --use-defaults

Wenn Sie die Einstellung lieber selbst verwalten möchten, aktivieren Sie sie einmal über das Einstellungssystem >> für Entwickler-Entwicklermodus>, und die CLI erkennt sie und wechselt fort.

Ausschalten

Verwenden Sie das Einstellungssystem >> für Entwickler , und deaktivieren Sie den Entwicklermodus . Dies ist der empfohlene Pfad, da Einstellungen auch den zugeordneten Betriebssystemstatus bereinigen. So bestätigen Sie den Registrierungswert danach:

Get-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock' `
    -Name AllowDevelopmentWithoutDevLicense, AllowAllTrustedApps

Wenn Sie den Entwicklermodus deaktivieren, werden keine vertrauenswürdigen Zertifikate oder bereits installierten Pakete entfernt. Weitere Informationen finden Sie unter Entfernen eines vertrauenswürdigen Zertifikats.

Signierung für die Produktion

Ein Entwicklungszertifikat funktioniert nur für Personen, die es explizit als vertrauenswürdig eingestuft haben. Um Ihre App zu verteilen, signieren Sie sie mit einer Identität, die Windows bereits vertraut.

Auswählen einer Signaturidentität

• Azure Trusted Signing – ein cloudverwalteter Signaturdienst. Der private Schlüssel befindet sich nie auf Ihrem Build-Computer, daher gibt es kein .pfx, das man manuell schützen, preisgeben oder manuell rotieren müsste. Verwenden Sie winapp az-sign, die die Standardanmeldeinformationskette von Azure verwendet und mit GitHub Actions OIDC oder einer verwalteten Identität funktioniert.

  winapp az-sign .\MyApp.msix
  

• Ein Codesignaturzertifikat einer vertrauenswürdigen Zertifizierungsstelle – übergeben es winapp sign als zweites Positionsargument mit seinem Kennwort in --password. Sie sind dann dafür verantwortlich, das Schlüsselmaterial sicher zu speichern; Halten Sie es in einem Hardwaretoken, einem Schlüsseltresor oder im geheimen Speicher Ihres CI-Anbieters und nie im Repository.

• Der Microsoft Store – wenn Sie ausschließlich über den Store verteilen, signiert es das Paket für Sie und Sie müssen sich nicht vor der Übermittlung signieren.

In jedem Fall muss der Zertifikatsbetreff mit dem Publisher Wert in Ihrem Manifest übereinstimmen, einschließlich für sparse Pakete.

Signaturschlüssel aus dem Repository heraushalten

Zertifikat-Kennwörter gehören in Ihrem CI-Geheimspeicher, nicht in einer Konfigurationsdatei. Lesen Sie sie aus der Umgebung, anstatt sie hart zu codieren:

winapp sign .\MyApp.msix $env:SIGNING_CERT_PATH --password $env:SIGNING_CERT_PASSWORD

Das gleiche gilt für die in die Quellcodeverwaltung eingecheckte Buildkonfiguration, z. B. eine Electron Forge-Konfiguration – siehe Electron Packaging. winapp az-sign vermeidet das Problem vollständig, da kein Kennwort übergeben werden muss.

Vor der Veröffentlichung

Eine kurze Checkliste für den Übergang von lokalen Tests zu Verteilung:

• Das Paket ist mit einem von einer Zertifizierungsstelle ausgestellten Zertifikat oder mit Azure Trusted Signing signiert oder im Store eingereicht – nicht mit devcert.pfx.
• Keine .pfx Datei oder .cer Datei befindet sich innerhalb der verpackten Ausgabe.
• In zugesicherten Dateien, Buildskripts oder CI-Protokollen wird kein Zertifikatkennwort angezeigt.
• Der Zertifikatbetreff stimmt mit dem Manifest Publisherüberein.
• Entwicklungszertifikate und der Entwicklermodus sind nicht auf Computern aktiviert, die nur die App ausführen müssen.

Melden eines Sicherheitsproblems

Um eine Sicherheitslücke in der winapp CLI selbst zu melden, folgen Sie dem Prozess in SECURITY.md. Bitte eröffnen Sie kein öffentliches GitHub-Issue für Sicherheitsmeldungen.

Zugehörige Themen

• CLI-Referenz
• Debuggen mit Paketidentität
• Verpacken einer EXE/CLI
• Minimale Verpackung
• Elektronenverpackung
• Signieren eines App-Pakets mit SignTool
• Azure Trusted Signing