Panduan keamanan

CLI winapp membuat pengembangan Windows lokal mudah: ini dapat menghasilkan sertifikat penandatanganan, mempercayainya di komputer Anda, dan mengaktifkan Mode Pengembang untuk Anda. Setiap langkah tersebut mengubah status mesin atau membuat file yang membawa kunci privat, sehingga membantu mengetahui dengan tepat apa yang mereka lakukan.

Halaman ini menjelaskan konsekuensi dari setiap perintah, cara membatalkannya, dan apa yang harus dilakukan secara berbeda saat Anda mengirim. Sertifikat pengembangan dan Mode Pengembang adalah jalur normal yang didukung untuk pengujian lokal — tujuannya di sini adalah Anda memahami apa yang Anda pilih, bukan berarti Anda menghindarinya.

Sertifikat pengembangan

Paket MSIX harus ditandatangani sebelum Windows akan menginstalnya. Untuk pengujian lokal, winapp cert generate buat sertifikat yang ditandatangani sendiri sehingga Anda dapat menandatangani dan menginstal paket Anda sendiri tanpa membeli apa pun.

Apa yang winapp cert generate dibuat

Sertifikat yang dihasilkan adalah sertifikat penandatanganan kode entitas akhir yang ditandatangani sendiri:

Harta benda Nilai
Key RSA 2048-bit, ditandai dapat diekspor
Algoritma tanda tangan SHA-256 dengan RSA (PKCS#1 v1.5)
Penggunaan kunci Tanda tangan digital
Penggunaan kunci yang ditingkatkan Penandatanganan kode (1.3.6.1.5.5.7.3.3)
Batasan dasar Bukan otoritas sertifikat
Validitas 365 hari secara default (--valid-days)
Subject Harus cocok dengan Publisher di manifes Anda

Perintah menulis dua hal:

  • devcert.pfx di direktori saat ini (atau jalur yang Anda teruskan ke --output). File ini berisi sertifikat dan kunci privatnya.
  • Salinan sertifikat di penyimpanan sertifikat pribadi Anda (Cert:\CurrentUser\My).

Dengan --export-cer, juga dibuat file .cer di sebelah .pfx. File tersebut hanya berisi sertifikat publik — tidak ada kunci privat — yang menjadikannya hal yang tepat untuk diberikan kepada rekan setim atau mesin uji yang perlu mempercayai build Anda.

Note

Sertifikat yang ditandatangani sendiri tidak dipercaya oleh siapa pun hingga seseorang secara eksplisit memercayainya. Tidak masalah untuk mesin Anda sendiri dan mesin uji Anda sendiri; ini bukan pengganti identitas penandatanganan kode nyata saat Anda mendistribusikan aplikasi Anda.

Kata sandi bawaan

winapp cert generate menggunakan password sebagai kata sandi PFX kecuali jika Anda memberikan --password. Setelan bawaan yang sama berlaku saat Anda kemudian memberikan sertifikat tersebut kepada winapp sign, yang opsi kata sandinya juga menggunakan --password, dan kepada winapp pack, yang menggunakan --cert-password.

Kata sandi terkenal berarti kunci privat di devcert.pfx secara efektif tidak terlindungi - siapa pun yang mendapatkan file dapat menandatangani kode dengannya. Itu adalah kompromi yang dapat diterima untuk sertifikat sekali pakai yang hanya digunakan untuk menandatangani build pengujian lokal di mesin Anda sendiri, dan itulah alasan setelan bawaan ini ada.

Important

Perlakukan kata sandi default sebagai sinyal bahwa sertifikat sekali pakai. Jika sertifikat pernah digunakan untuk menandatangani sesuatu yang akan diinstal orang lain, sertifikat tidak boleh berupa winapp cert generate sertifikat dengan kata sandi default — lihat Menandatangani untuk produksi.

Skrip dan agen tidak perlu membandingkan kata sandi itu sendiri: winapp cert generate --json melaporkan "defaultPasswordIsPublic": true dan mengulangi pengungkapan dalam warnings array setiap kali default berlaku. Lihat sertifikasi menghasilkan output JSON.

Tempat file sertifikat berada

devcert.pfx adalah kunci privat pada disk. Dua aturan menjauhkannya dari masalah:

Jangan lakukan itu.winapp cert generate secara otomatis menambahkan nama file sertifikat ke sebelahnya .gitignore , sehingga alur default sudah tercakup. Jika Anda memindahkan file, mengganti namanya, atau menghasilkannya ke direktori yang dikelola oleh direktori lain .gitignore, periksa apakah entri mengikutinya:

git check-ignore -v devcert.pfx

Jika tidak ada output, file tersebut tidak diabaikan — tambahkan file itu sebelum Anda melakukan commit.

Jangan sertakan ini dalam paket.winapp pack mengemas semua yang ada dalam direktori input, sehingga devcert.pfx yang berada di folder output aplikasi Anda akan ikut masuk ke dalam MSIX yang didistribusikan. Buat sertifikat di luar folder yang Anda paketkan, seperti yang ditunjukkan oleh panduan Packaging a EXE/CLI , dan konfirmasikan tidak ada sebelum Anda mendistribusikan:

# 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

Jika .pfx dengan kunci privat asli pernah ter-commit atau dipublikasikan, lakukan rotasi: buat sertifikat baru, tandatangani ulang, dan hentikan kepercayaan terhadap sertifikat lama menggunakan langkah-langkah di Menghapus sertifikat tepercaya. Menghapus file dari commit berikutnya tidak akan menghapusnya dari riwayat.

Apa yang diberikan winapp cert install

winapp cert install menambahkan sertifikat ke penyimpanan LocalMachine\TrustedPeople . Ini memerlukan hak istimewa administrator, karena mengubah kepercayaan untuk setiap pengguna di komputer.

Setelah sertifikat berada di TrustedPeople, Windows akan menerima paket MSIX apa pun yang ditandatangani oleh sertifikat tersebut sebagai cukup tepercaya untuk diinstal - bukan hanya paket yang Anda uji. Untuk sertifikat yang kunci privatnya Anda pegang dan simpan secara lokal, itulah efek yang dimaksudkan. Ini juga alasan untuk bersikap sengaja dalam melakukannya:

  • Percayai sertifikat yang Anda buat sendiri, atau yang berasal dari orang yang akan Anda izinkan menginstal perangkat lunak di komputer ini.
  • Jangan menginstal sertifikat pengembangan pada komputer bersama, produksi, atau build yang diandalkan orang lain.
  • Lebih suka mendistribusikan .cer (kunci publik saja) daripada .pfx ketika kolega perlu menginstal paket pengujian Anda. Mereka dapat memercayai hasil build Anda tanpa memiliki kemampuan untuk menandatangani atas nama Anda.

Untuk memercayai .cer di mesin uji lain, jalankan winapp cert install langsung di mesin tersebut — perintah ini menerima baik .pfx maupun .cer yang hanya berisi kunci publik:

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

Yang setara hanya menggunakan alat Windows bawaan adalah:

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

Menghapus sertifikat tepercaya

Sertifikat pengembangan secara bawaan kedaluwarsa setelah satu tahun, tetapi kedaluwarsanya tidak berarti sertifikat tersebut dihapus. Setelah Anda selesai dengan sertifikat — proyek berakhir, komputer sedang digunakan kembali, atau kunci mungkin bocor — hapus secara eksplisit.

Pertama, temukan thumbprint-nya:

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

Kemudian hapus itu dari repositori kepercayaan mesin. Langkah ini membutuhkan elevasi:

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

cert generate juga menempatkan sertifikat, bersama dengan kunci privatnya, di toko pribadi Anda. Hapus itu dari prompt normal tanpa hak akses administrator, masuk sebagai akun yang menjalankan cert generate:

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

Important

Jalankan dua perintah di atas dalam konteks yang ditampilkan. Jika Anda menjalankannya dengan hak istimewa lebih tinggi menggunakan akun administrator yang berbeda, Cert:\CurrentUser dalam sesi yang dielevasi tersebut adalah penyimpanan milik administrator itu — bukan milik Anda — sehingga kunci privat akan tertinggal di penyimpanan pengguna yang membuatnya.

Terakhir, hapus .pfx dan salinan .cer apa pun yang telah Anda bagikan, lalu batalkan registrasi paket yang Anda sideload dengannya:

winapp unregister

Note

Menghapus sertifikat tidak menghapus paket yang sudah diinstal dengannya. Copot pemasangannya satu per satu melalui Pengaturan > Aplikasi > Aplikasi yang diinstal, atau gunakan winapp unregister untuk paket yang terdaftar dalam mode pengembangan.

Mode pengembang

Windows memerlukan Mode Pengembang untuk mendaftarkan paket aplikasi langsung dari folder pada disk — tata letak yang longgar — alih-alih menginstal MSIX bawaan yang ditandatangani. Perintah seperti winapp run dan create-debug-identity mengandalkan itu dan gagal tanpanya, dan winapp init menawarkan untuk mengaktifkannya untuk Anda.

Apa yang berubah saat diaktifkan

CLI memungkinkan Mode Pengembang dengan menulis dua DWORD nilai di bawah HKEY_LOCAL_MACHINE:

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

Karena ini adalah pengaturan di seluruh komputer, CLI meluncurkan proses pembantu yang ditinggikan dan Windows menunjukkan perintah Kontrol Akun Pengguna. Tidak ada yang diubah jika Anda menolak perintah.

Praktis, ini berarti mesin akan:

  • Daftarkan paket aplikasi langsung dari folder di disk, tanpa harus membangunnya menjadi MSIX atau menandatanganinya sama sekali (AllowDevelopmentWithoutDevLicense).
  • Instal paket aplikasi dari luar Microsoft Store selama ditandatangani oleh sertifikat yang dipercaya mesin — termasuk sertifikat pengembangan apa pun di TrustedPeople (AllowAllTrustedApps).

Important

Mode Pengembang beserta sertifikat pengembangan yang tepercaya merupakan pelonggaran yang disengaja terhadap pembatasan penginstalan bawaan. Kombinasi itu cocok digunakan pada komputer pengembangan dan pengujian. Biarkan tetap dinonaktifkan pada mesin produksi, kios, dan infrastruktur bersama.

Mengontrol kapan diaktifkan

winapp init bertanya sebelum mengubah apa pun, dan --use-defaults melewati pertanyaan sepenuhnya, meninggalkan Mode Pengembang tidak tersentuh. Itu membuat skrip dan CI berjalan aman secara default:

winapp init --use-defaults

Jika Anda lebih suka mengelola pengaturan sendiri, aktifkan sekali melalui > Pengaturan Sistem > Untuk > Pengembang Mode Pengembang dan CLI akan mendeteksinya dan melanjutkan.

Mematikannya

Gunakan Sistem > Pengaturan > Untuk pengembang dan matikan Mode Pengembang. Ini adalah jalur yang direkomendasikan, karena Pengaturan juga membersihkan status OS terkait. Untuk mengonfirmasi nilai registri setelahnya:

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

Menonaktifkan Mode Pengembang tidak menghapus sertifikat tepercaya atau paket yang sudah diinstal — lihat Menghapus sertifikat tepercaya.

Penandatanganan untuk produksi

Sertifikat pengembangan hanya berfungsi untuk orang yang secara eksplisit mempercayainya. Untuk mendistribusikan aplikasi Anda, tanda tangani dengan identitas yang sudah Windows percayai.

Pilih identitas penandatanganan

  • Penandatanganan Tepercaya Azure — layanan penandatanganan yang dikelola cloud. Kunci privat tidak pernah ada di mesin build Anda, jadi tidak ada .pfx yang perlu dilindungi, dibocorkan, atau dirotasi secara manual. Gunakan winapp az-sign, yang mengautentikasi dengan rantai kredensial Azure standar dan bekerja dengan GitHub Actions OIDC atau identitas terkelola.

    winapp az-sign .\MyApp.msix

  • Sertifikat penandatanganan kode dari otoritas sertifikat tepercaya — teruskan ke winapp sign sebagai argumen posisi kedua, dengan kata sandinya di --password. Anda kemudian bertanggung jawab untuk menyimpan materi kunci dengan aman; simpan dalam token perangkat keras, brankas kunci, atau penyimpanan rahasia penyedia CI Anda, dan tidak pernah ada di repositori.

  • Microsoft Store — jika Anda mendistribusikan secara eksklusif melalui Store, itu menandatangani paket untuk Anda dan Anda tidak perlu menandatangani sebelum pengiriman.

Dalam semua kasus, subjek sertifikat harus sesuai dengan nilai Publisher dalam manifes Anda, termasuk untuk paket sparse.

Jauhkan rahasia penandatanganan dari repositori

Kata sandi sertifikat berada di penyimpanan rahasia CI Anda, bukan dalam file konfigurasi. Ambil dari variabel lingkungan alih-alih menuliskannya langsung:

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

Hal yang sama berlaku untuk membangun konfigurasi yang diperiksa ke kontrol sumber, seperti konfigurasi Electron Forge — lihat Kemasan elektron. winapp az-sign menghindari masalah sepenuhnya, karena tidak ada kata sandi yang akan diteruskan.

Sebelum Anda menerbitkan

Daftar periksa singkat untuk transisi dari pengujian lokal ke distribusi:

  • Paket ditandatangani dengan sertifikat yang dikeluarkan CA, Penandatanganan Tepercaya Azure, atau dikirimkan ke Toko — bukan dengan devcert.pfx.
  • Tidak ada .pfx atau .cer file berada di dalam output paket.
  • Kata sandi sertifikat tidak muncul dalam file yang di-commit, skrip build, atau log CI.
  • Subjek sertifikat cocok dengan manifes Publisher.
  • Sertifikat pengembangan dan Mode Pengembang tidak diaktifkan pada komputer yang hanya perlu menjalankan aplikasi.

Melaporkan masalah keamanan

Untuk melaporkan kerentanan keamanan di CLI winapp itu sendiri, ikuti proses di SECURITY.md. Jangan buka masalah GitHub publik untuk laporan keamanan.

  • Last updated on