安全性指導

Winapp CLI 讓本地 Windows 開發變得簡單：它可以產生簽署憑證，信任你的電腦，並自動開啟開發者模式。 這些步驟會改變機器狀態或產生帶有私鑰的檔案，所以了解它們的確切功能會很有幫助。

本頁說明每個指令的後果、如何撤銷，以及在出貨時該怎麼做才有所不同。 開發證書和開發者模式是本地測試的正常且支援的路徑——目標是讓你了解自己選擇加入的內容，而不是避開它們。

開發證書

MSIX 套件必須先簽署，Windows 才會安裝。 本地測試時，建立 winapp cert generate 自簽憑證，這樣你就能簽署並安裝自己的套件，而不必購買任何東西。

winapp cert generate 建立的內容

產生的憑證是一份自簽的終端實體程式碼簽署憑證：

房產 價值
Key RSA 2048 位元，標記為可匯出
簽名演算法 SHA-256 搭配 RSA（PKCS#1 v1.5）
金鑰使用方式 數位簽章
增強金鑰使用方式 代碼簽章（1.3.6.1.5.5.7.3.3）
基本限制 不是證書授權中心
有效期 預設365天（--valid-days）
主旨 必須與資訊清單中的 Publisher 一致

指令寫了兩件事：

  • devcert.pfx 在目前目錄中（或在你傳遞給 --output 的路徑中）。 此 檔案包含憑證 及其私鑰。
  • 你個人憑證庫中的憑證副本（Cert:\CurrentUser\My）。

使用 --export-cer 時，它也會在 .pfx 旁邊寫入一個 .cer 檔案。 該檔案只包含公開憑證，沒有私鑰，因此交給需要信任你建置的團隊成員或測試機是正確的選擇。

Note

自簽憑證在被明確信任之前，沒有人會信任它。 這對你自己的機器和測試機來說是沒問題的;它不能取代你在發佈應用程式時擁有的真實代碼簽名身份。

預設密碼

winapp cert generate 會使用 --password 作為 PFX 密碼，除非你傳遞 password。 當你之後將該憑證提供給 winapp sign 時，相同的預設值也適用；其密碼選項同樣是 --password。對於 winapp pack 也是如此，它接受 --cert-password。

一個知名的密碼意味著私 devcert.pfx 鑰實際上不受保護——任何取得該檔案的人都可以用它簽署程式碼。 對於只會用來替你自己機器上的本機測試建置簽署的一次性憑證來說，這樣的權衡取捨是可以接受的，而這也正是之所以會有這項預設值的原因。

Important

將預設密碼視為該憑證可棄用的信號。 如果憑證被用來簽署他人安裝的裝置，該憑證不應是 winapp cert generate 帶有預設密碼的憑證——詳見 生產環境的簽署。

腳本與代理程式不必自行比較密碼： winapp cert generate --json 只要預設值生效，就會以陣列形式報告 "defaultPasswordIsPublic": true 並重複揭露 warnings 。 請參考 cert 產生 JSON 輸出。

憑證檔案存放地點

devcert.pfx 是磁碟上的私鑰。 有兩條規則讓它遠離麻煩：

不要提交它。winapp cert generate 會自動將憑證的檔名附加到它旁邊的 .gitignore，因此預設流程已經涵蓋在內。 如果你移動檔案、重新命名，或將其產生到由其他 .gitignore管理的目錄中，請檢查該條目是否緊接該目錄：

git check-ignore -v devcert.pfx

如果沒有列印任何東西，該檔案 就不會 被忽略——在你提交之前先先加入它。

不要將它封裝。winapp pack 會將輸入目錄中的所有內容都封裝起來，因此，位於您應用程式輸出資料夾中的 devcert.pfx 最終會被包含在發佈的 MSIX 中。 如 EXE/CLI 封裝指南 所示，請在要封裝的資料夾外產生憑證，並在發佈前確認該憑證不在其中：

# 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

Tip

如果某個帶有真實私密金鑰的 .pfx 確實被提交或公開了，請將其輪替：產生新的憑證、重新簽章，並依照 移除受信任的憑證 中的步驟停止信任舊憑證。 在之後的提交中刪除該檔案，並不會將它從歷史記錄中移除。

winapp cert install 提供的補助

winapp cert install 將憑證 LocalMachine\TrustedPeople 加入商店。 這需要管理員權限，因為這會改變機器上每個使用者的信任。

一旦憑證匯入TrustedPeople，Windows 就會將任何由該憑證簽署的 MSIX 套件視為受信任並允許安裝，而不只是你當時測試的那個套件。 對於你持有並本地保存私鑰的憑證，這正是預期效果。 這也是我們必須謹慎處理的原因：

  • 只信任你自行產生的憑證，或來自你會允許在這台電腦上安裝軟體的人所提供的憑證。
  • 不要在共用、生產或建置的機器上安裝開發憑證，因為其他人都依賴這些機器。
  • 當同事需要安裝你的測試套件時，建議優先分發 .pfx（僅公開金鑰），而不是 .cer。 他們能夠信任你的建置版本，但無法取得以你的身分簽署的能力。

若要讓另一台測試機器信任 .cer，請直接在該機器上執行 winapp cert install——該指令可接受 .pfx 或僅含公開部分的 .cer：

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

僅使用內建 Windows 工具的相當條件為：

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

移除受信任的憑證

開發證書預設在一年後到期，但到期並不等於被移除。 當你不再需要使用憑證時——例如專案已結束、機器將改作他用，或金鑰可能已外洩——務必明確將其移除。

首先，找出它的指紋：

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

然後將它從電腦的信任存放區移除。 此階梯需抬高：

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

cert generate 同時，將憑證及其私鑰放到你的個人商店。 從一般、未提升權限的命令提示字元中將其移除，並以執行cert generate的帳號登入：

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

Important

在上述情境中執行上述兩個指令。 如果你使用不同的系統管理員帳戶以提升權限執行，Cert:\CurrentUser 在該提升權限的工作階段中是該系統管理員的存放區，而不是你的存放區，因此私密金鑰會留在產生該金鑰之使用者的存放區中。

最後，刪除 .pfx 以及你分發出去的任何 .cer 副本，並取消註冊你用它側載的套件：

winapp unregister

Note

移除憑證並不會移除已經安裝過的套件。 透過 設定 > 應用程式 > 已安裝的應用程式 分別將它們解除安裝，或對於以開發模式註冊的套件，使用 winapp unregister。

開發人員模式

Windows 要求開發者模式直接從磁碟上的資料夾註冊應用程式套件——這是一種鬆散的佈局——而非安裝已建構且簽名的 MSIX。 像 winapp run 和 create-debug-identity 這類指令都仰賴該功能，若未啟用便會失敗，而 winapp init 會提供為你啟用它的選項。

啟用它會帶來什麼改變

CLI 透過在 DWORD 之下寫入兩個 HKEY_LOCAL_MACHINE 值來啟用開發人員模式：

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

由於這些是全機設定，CLI 會啟動一個提升級的輔助程序，Windows 則顯示使用者帳戶控制提示。 如果你拒絕提示，內容不會改變。

實際上，這意味著機器會：

  • 直接從磁碟上的資料夾登錄應用程式套件，無需將它們內建在 MSIX 中或完全不簽署（AllowDevelopmentWithoutDevLicense）。
  • 只要應用程式套件是由電腦所信任的憑證簽署，就可以從 Microsoft Store 外部安裝，包括位於 TrustedPeople（AllowAllTrustedApps）中的任何開發憑證。

Important

開發者模式加上可信開發憑證，是刻意放寬預設安裝限制的做法。 這種組合應該放在開發機和測試機上。 在生產機、自助服務機和共用基礎設施上不要關閉。

控制何時啟用

winapp init 在更改任何內容前先詢問，並且 --use-defaults 完全跳過這個問題，開發者模式則保持不變。 這讓腳本執行和 CI 執行在預設情況下都是安全的：

winapp init --use-defaults

如果你想自己管理設定，可以透過 設定 > 系統 > 的開發 > 者模式 啟用一次，CLI 會偵測到並繼續。

將其關閉

使用開發者設定>系統>並關閉開發者模式。 這是推薦的路徑，因為設定也會清理相關的作業系統狀態。 之後要確認登錄值：

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

關閉開發者模式不會移除受信任憑證或已安裝的套件——詳見 移除受信任憑證。

簽約製作

開發證書只適用於明確信任它的人。 要發佈你的應用程式，請用 Windows 已經信任的身份簽名。

選擇簽署身分

  • Azure 信任簽署 — 一項雲端管理的簽署服務。 私鑰在你的建置機上根本不存在，所以不需要 .pfx 手動保護、洩漏或旋轉。 使用 winapp az-sign，它能以標準 Azure 憑證鏈進行驗證，並支援 GitHub Actions OIDC 或管理身份。

    winapp az-sign .\MyApp.msix

  • 來自受信任憑證授權中心的程式碼簽署憑證——將其 作為第二個位置參數傳送至 ， winapp sign 密碼為 --password。 你必須負責安全存放關鍵材料;把它放在硬體標記、金鑰庫或你 CI 提供者的秘密儲存庫裡，絕不要放在倉庫裡。

  • Microsoft Store — 如果你只透過 Store 發行，它會幫你簽收包裹，你不需要在提交前簽字。

無論在哪種情況下，憑證主體都必須與您資訊清單中的 Publisher 值相符，包括 稀疏套件。

將簽署密鑰保留在儲存庫之外

憑證密碼應該放在你的 CI 秘密儲存庫，而不是設定檔裡。 從環境中讀取，而不是硬編碼：

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

這也適用於提交到版本控制中的建置組態，例如 Electron Forge 組態——請參閱 Electron 封裝。 winapp az-sign 完全避免了這個問題，因為沒有密碼可通過。

發表前

從地方檢測過渡到分銷的簡短檢查清單：

  • 該套件會使用 CA 核發的憑證簽署、使用 Azure 信任簽署 簽署，或提交至市集，而非使用 devcert.pfx。
  • 沒有 .pfx or .cer 檔案在打包輸出裡。
  • 在提交的檔案、建置腳本或 CI 日誌中，都不會出現憑證密碼。
  • 證書主體與清單 Publisher相符。
  • 開發憑證與開發者模式不會在只需 執行 應用程式的機器上啟用。

報告安全問題

若要在 winapp CLI 本身回報安全漏洞，請依 照 SECURITY.md 的流程進行。 請不要為安全報告開啟公開的 GitHub 議題。

  • Last updated on