Podpisywanie pakietu MSIX: kompleksowy przewodnik

Ten przewodnik przeprowadzi Cię przez proces podpisywania pakietu MSIX dla każdego etapu programowania — od lokalnego testowania przez dystrybucję produkcyjną. Aby zapoznać się z porównaniem opcji podpisywania i kosztów, zobacz Omówienie podpisywania pakietu MSIX.

Wybieranie podejścia do podpisywania

Programowanie: podpisywanie do testowania lokalnego

W przypadku programowania lokalnego użyj certyfikatu z podpisem własnym. Pakiety podpisane własnym certyfikatem można instalować tylko na maszynach, na których certyfikat jest jawnie zaufany — jest to zamierzone i odpowiednie dla celów testowania.

Opcja A: Interfejs wiersza polecenia usługi WinApp (zalecany w przypadku nowych projektów)

WinApp CLI obsługuje generowanie i podpisywanie certyfikatów w jednym kroku.

Krok 1. Instalowanie interfejsu wiersza polecenia usługi WinApp

winget install -e --id Microsoft.WinAppCLI --source winget

Krok 2. Generowanie certyfikatu dewelopera z podpisem własnym

winapp cert generate --manifest .\appxmanifest.xml --output .\devcert.pfx --install

Flaga --manifest odczytuje nazwę wydawcy bezpośrednio z appxmanifest.xml. Flaga --install dodaje certyfikat do magazynu zaufania komputera lokalnego, aby można było natychmiast zainstalować pakiet.

Krok 3. Podpisywanie pakietu

winapp sign MyApp.msix --cert .\devcert.pfx

Opcja B: PowerShell + SignTool (Windows 10 i nowsze)

Użyj tej metody, jeśli nie używasz interfejsu wiersza polecenia usługi WinApp.

Krok 1. Tworzenie certyfikatu z podpisem własnym

Uruchom następujące polecenie w wierszu polecenia programu PowerShell z podwyższonym poziomem uprawnień. Wartość Subject musi dokładnie zgadzać się z Publisher w appxmanifest.xml:

New-SelfSignedCertificate -Type Custom -KeyUsage DigitalSignature `
  -Subject "CN=MyPublisher" `
  -CertStoreLocation "Cert:\CurrentUser\My" `
  -TextExtension @("2.5.29.37={text}1.3.6.1.5.5.7.3.3", "2.5.29.19={text}") `
  -FriendlyName "MyApp Dev Cert"

Zanotuj odcisk palca w danych wyjściowych — będzie on potrzebny w następnych krokach.

Krok 2. Eksportowanie certyfikatu do pliku PFX

$password = ConvertTo-SecureString -String "YourPassword" -Force -AsPlainText
Export-PfxCertificate -cert "Cert:\CurrentUser\My\<Thumbprint>" `
  -FilePath .\devcert.pfx -Password $password

Krok 3. Ufanie certyfikatowi lokalnie

Import-PfxCertificate -CertStoreLocation "Cert:\LocalMachine\TrustedPeople" `
  -FilePath .\devcert.pfx -Password $password

Krok 4. Podpisywanie pakietu

SignTool sign /fd SHA256 /a /f .\devcert.pfx /p "YourPassword" MyApp.msix

Aby uzyskać pełne użycie narzędzia SignTool, zobacz Podpisywanie pakietu aplikacji przy użyciu narzędzia SignTool.

Testowanie: dystrybuowanie do testerów przy użyciu certyfikatu z podpisem własnym

Aby zainstalować pakiet MSIX z podpisem własnym na maszynie testera, certyfikat musi być najpierw zaufany na tej maszynie.

Przekaż testerom certyfikat: Udostępnij plik .pfx lub .cer (tylko klucz publiczny) wraz z pakietem .msix.

Testerzy uruchamiają następujące polecenia w wierszu polecenia programu PowerShell z podwyższonym poziomem uprawnień:

# If you shared a .pfx file (testers need the password)
Import-PfxCertificate -CertStoreLocation "Cert:\LocalMachine\TrustedPeople" `
  -FilePath .\devcert.pfx -Password (ConvertTo-SecureString "YourPassword" -Force -AsPlainText)

# If you shared a .cer file (public key only, no password needed)
Import-Certificate -CertStoreLocation "Cert:\LocalMachine\TrustedPeople" -FilePath .\devcert.cer

Po zaufaniu certyfikatowi testerzy mogą zainstalować .msix , klikając dwukrotnie.

Produkcja: podpisywanie artefaktów Azure (wcześniej zaufane podpisywanie)

Windows 10 wersja 1809 i nowsze, Windows 11 (wszystkie wersje), Windows Server 2016 i nowsze wersje

Azure Artifact Signing to nowa nazwa tego, co wcześniej nazywało się Trusted Signing. Usługa jest identyczna — zmieniono tylko nazwę. Możliwe, że nadal będziesz widzieć "Zaufane podpisywanie" w niektórych narzędziach, takich jak akcja azure/trusted-signing-action GitHub i identyfikator pakietu winget, ponieważ te odwołania są aktualizowane na bieżąco.

Podpisywanie artefaktów w Azure jest zalecaną opcją do użytku produkcyjnego MSIX. Reputacja jest powiązana ze zweryfikowaną tożsamością, a nie z określonym certyfikatem, co oznacza, że tożsamość wydawcy buduje reputację filtru SmartScreen w miarę jak użytkownicy instalują podpisane aplikacje. Zobacz Omówienie podpisywania pakietu MSIX , aby uzyskać informacje o wymaganiach dotyczących uprawnień i kosztach przed skonfigurowaniem konta.

Wymagania wstępne

• Konto do podpisywania artefaktów, które ma ukończoną weryfikację tożsamości oraz utworzony profil certyfikatu. Zobacz wprowadzenie do podpisywania artefaktów.
• Rola podpisującego profil zaufanego certyfikatu przypisana do tożsamości używanej do podpisywania.

Krok 1. Instalowanie narzędzi klienckich podpisywania artefaktów

Narzędzia klienckie podpisywania artefaktów obejmują wymaganą wtyczkę dlib, zgodną wersję narzędzia SignTool i środowisko uruchomieniowe .NET 8. Standardowa składnia narzędzia SignTool nie działa z podpisywaniem artefaktów bez tego pakietu.

winget install -e --id Microsoft.Azure.ArtifactSigningClientTools

Jeśli WinGet nie jest dostępny (na przykład na agencie kompilacji Windows Server), zainstaluj za pomocą programu PowerShell z uprawnieniami administratora.

$ProgressPreference = 'SilentlyContinue'
Invoke-WebRequest -Uri "https://download.microsoft.com/download/70ad2c3b-761f-4aa9-a9de-e7405aa2b4c1/ArtifactSigningClientTools.msi" -OutFile .\ArtifactSigningClientTools.msi
Start-Process msiexec.exe -Wait -ArgumentList '/I ArtifactSigningClientTools.msi /quiet'
Remove-Item .\ArtifactSigningClientTools.msi

Krok 2. Tworzenie pliku JSON metadanych

Utwórz plik o nazwie metadata.json z szczegółami konta podpisywania artefaktów. Identyfikator URI punktu końcowego musi być zgodny z regionem Azure, w którym utworzono konto (znajdź go w portalu Azure w obszarze Konta podpisywania artefaktów jako identyfikator URI Account):

{
  "Endpoint": "https://<region>.codesigning.azure.net/",
  "CodeSigningAccountName": "<your-account-name>",
  "CertificateProfileName": "<your-certificate-profile-name>"
}

Aby uzyskać pełną listę identyfikatorów URI punktów końcowych specyficznych dla regionu, zobacz Podpisywanie integracji.

Krok 3. Uwierzytelnianie

Ustaw poświadczenia Azure jako zmienne środowiskowe (użyj poświadczeń rejestracji aplikacji dla CI/CD):

$env:AZURE_CLIENT_ID     = "<your-client-id>"
$env:AZURE_TENANT_ID     = "<your-tenant-id>"
$env:AZURE_CLIENT_SECRET = "<your-client-secret>"

Alternatywnie uruchom polecenie az login na potrzeby interakcyjnego podpisywania lokalnego.

Krok 4. Podpisywanie pakietu

Użyj narzędzia SignTool zainstalowanego z narzędziami klienta podpisywania artefaktów. Flaga /dlib wskazuje wtyczkę dlib zainstalowaną w poprzednim kroku:

signtool sign /v /fd SHA256 `
  /tr "https://timestamp.acs.microsoft.com" /td SHA256 `
  /dlib "C:\Program Files (x86)\Microsoft\ArtifactSigningClientTools\bin\Azure.CodeSigning.Dlib.dll" `
  /dmdf .\metadata.json `
  MyApp.msix

CI/CD: GitHub Actions

Użyj oficjalnego elementu azure/trusted-signing-action:

- name: Sign MSIX with Azure Artifact Signing
  uses: azure/trusted-signing-action@v0
  with:
    azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
    azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
    azure-client-secret: ${{ secrets.AZURE_CLIENT_SECRET }}
    endpoint: ${{ secrets.AZURE_TRUSTED_SIGNING_ENDPOINT }}
    trusted-signing-account-name: ${{ secrets.AZURE_CODE_SIGNING_NAME }}
    certificate-profile-name: ${{ secrets.AZURE_CERT_PROFILE_NAME }}
    files-folder: ${{ github.workspace }}\output
    files-folder-filter: msix

Aby uzyskać Azure DevOps, zobacz Set up Azure DevOps with Trusted Signing (Konfigurowanie Azure DevOps za pomocą zaufanego podpisywania.

Produkcja: dystrybucja Microsoft Store

Dotyczy: Wszystkie obsługiwane wersje Windowsa

Jeśli dystrybuujesz za pośrednictwem Microsoft Store, nie musisz samodzielnie podpisywać pakietu — sklep podpisuje go podczas procesu przesyłania. Skompiluj pakiet i prześlij go za pośrednictwem Centrum partnerskiego. Sklep zapewnia globalnie zaufany podpis i zarządza wszystkimi certyfikatami.

Produkcja: certyfikat podpisywania kodu OV

Aplikuje do: Windows 10 i nowsze

Jeśli podpisywanie artefaktów nie jest dostępne w Twoim regionie lub w Twojej sytuacji, możesz kupić certyfikat podpisywania kodu OV (Walidacja Organizacji) od urzędu certyfikacji, takiego jak DigiCert, Sectigo lub GlobalSign. Koszty zazwyczaj wahają się od 300–500 USD/rok.

Gdy otrzymasz plik PFX od urzędu certyfikacji:

SignTool sign /fd SHA256 /a /f .\cert.pfx /p "YourPassword" `
  /tr http://timestamp.digicert.com /td SHA256 `
  MyApp.msix

Aby uzyskać pełne opcje podpisywania, zobacz Podpisywanie pakietu aplikacji przy użyciu narzędzia SignTool.

Powiązane artykuły

• Omówienie podpisywania pakietu MSIX
• Podpisywanie pakietu aplikacji przy użyciu narzędzia SignTool
• Tworzenie certyfikatu na potrzeby podpisywania pakietów
• Podpisz pakiety za pomocą Azure Key Vault
• Szybki start podpisywania artefaktów
• Dokumentacja interfejsu wiersza polecenia usługi WinApp
• Przewodnik rozwiązywania problemów z MSIX