Güvenlik kılavuzu

Winapp CLI yerel Windows geliştirmeyi kolaylaştırır: bir imzalama sertifikası oluşturabilir, makinenizde güvenebilir ve sizin için Geliştirici Modu'nu açabilir. Bu adımların her biri makine durumunu değiştirir veya özel anahtar taşıyan bir dosya oluşturur, böylece tam olarak ne yaptıklarını bilmenize yardımcı olur.

Bu sayfa, her komutun neye yol açtığını, bunun nasıl geri alınacağını ve yayınladığınızda neleri farklı yapmanız gerektiğini açıklar. Geliştirme sertifikaları ve Geliştirici Modu, yerel test için normal ve desteklenen yoldur; burada amaç, neleri tercih ettiğinizi anlamanızdır, onlardan kaçındığınızdan değil.

Geliştirme sertifikaları

Windows yüklemeden önce MSIX paketlerinin imzalanması gerekir. Yerel test için, winapp cert generate hiçbir şey satın almadan kendi paketinizi imzalayıp yükleyebilmeniz için otomatik olarak imzalanan bir sertifika oluşturur.

winapp cert generate ne oluşturur

Oluşturulan sertifika, otomatik olarak imzalanan, son varlık kod imzalama sertifikasıdır:

Property Değer
Key RSA 2048 bit, dışarı aktarılabilir olarak işaretlenmiş
İmza algoritması RSA ile SHA-256 (PKCS#1 v1.5)
Anahtar kullanımı Dijital imza
Gelişmiş anahtar kullanımı Kod imzalama (1.3.6.1.5.5.7.3.3)
Temel kısıtlamalar Sertifika yetkilisi değil
Geçerlilik Varsayılan olarak 365 gün (--valid-days)
Subject Manifest dosyanızdaki Publisher ile eşleşmelidir

komutu iki şey yazar:

  • devcert.pfx geçerli dizinde (veya --output öğesine belirttiğiniz yolda). Bu dosya hem sertifikayı hem de özel anahtarını içerir.
  • Kişisel sertifika deponuzdaki sertifikanın bir kopyası (Cert:\CurrentUser\My).

--export-cer ile, .cer dosyasının yanına bir .pfx dosyası da yazar. Bu dosya yalnızca genel sertifikayı (özel anahtar yok) içerir ve bu da derlemelerinize güvenmesi gereken bir ekip arkadaşınıza veya test makinesine teslim edilmesi gereken doğru şey olmasını sağlar.

Note

Otomatik olarak imzalanan bir sertifikaya, birisi açıkça güvenene kadar kimse tarafından güvenilmez. Kendi makineniz ve kendi test makineleriniz için uygundur; uygulamanızı dağıtırken gerçek bir kod imzalama kimliğinin yerine geçmez.

Varsayılan parola

password iletmezseniz, winapp cert generate PFX parolası olarak --password kullanır. Aynı varsayılan, daha sonra bu sertifikayı parola seçeneği de --password olan winapp sign bileşenine ve --cert-password alan winapp pack bileşenine sağladığınızda da geçerlidir.

İyi bilinen bir parola, içindeki devcert.pfx özel anahtarın etkin bir şekilde korumasız olduğu anlamına gelir; dosyayı alan herkes onunla kod imzalayabilir. Bu, yalnızca kendi makinenizdeki yerel test derlemelerini imzalayan geçici bir sertifika için kabul edilebilir bir ödünleşimdir ve varsayılanın neden mevcut olduğunu da açıklar.

Important

Varsayılan parolayı sertifikanın atılabilir olduğunu belirten bir sinyal olarak değerlendirin. Sertifika, başka bir kişinin yükleyeceği bir şeyi imzalamak için kullanılırsa, varsayılan parolaya sahip bir winapp cert generate sertifika olmamalıdır; bkz. Üretim için imzalama.

Betiklerin ve aracıların parolayı kendilerinin karşılaştırması gerekmez: varsayılan geçerli olduğunda, winapp cert generate --jsonwarnings öğesini bildirir ve bildirimi bir "defaultPasswordIsPublic": true dizisinde yineler. Bkz. cert generate JSON output.

Sertifika dosyasının bulunduğu yer

devcert.pfx , disk üzerindeki özel bir anahtardır. İki kural bunu beladan uzak tutar:

Commit etmeyin.winapp cert generate sertifikanın dosya adını hemen yanındaki .gitignore öğesine otomatik olarak ekler, dolayısıyla varsayılan akış zaten kapsanır. Dosyayı taşırsanız, yeniden adlandırırsanız veya onu farklı bir .gitignore tarafından yönetilen bir dizinde oluşturursanız, girdinin onu izlediğini doğrulayın:

git check-ignore -v devcert.pfx

Eğer bu hiçbir çıktı vermezse, dosya yok sayılmıyor; commit etmeden önce ekleyin.

Paketlemeyin.winapp pack giriş dizinindeki her şeyi paketler; bu nedenle uygulamanızın çıktı klasöründe bulunan bir devcert.pfx, dağıtılan MSIX'in içine girer. EXE/CLI Paketleme kılavuzunda gösterildiği gibi sertifikayı paketlediğiniz klasörün dışında oluşturun ve dağıtmadan önce olmadığını onaylayın:

# 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

Gerçek bir özel anahtara sahip bir .pfx depoya kaydedilir veya yayımlanırsa, bunu değiştirin: yeni bir sertifika oluşturun, yeniden imzalayın ve Güvenilen sertifikayı kaldırma bölümündeki adımları izleyerek eski sertifikaya güvenmeyi bırakın. Dosyayı daha sonraki bir işlemeden silmek, dosyayı geçmişten kaldırmaz.

winapp cert install neler sağlar

winapp cert install sertifikayı LocalMachine\TrustedPeople deposuna ekler. Bu, makinedeki her kullanıcı için güveni değiştirdiğinden yönetici ayrıcalıkları gerektirir.

Bir sertifika içinde TrustedPeopleolduğunda, Windows yalnızca test ettiğiniz paketi değil, bu sertifika tarafından imzalanan tüm MSIX paketini yüklemek için yeterince güvenilir olarak kabul eder. Özel anahtarını tuttuğunuz ve yerel olarak tuttuğunuz bir sertifika için, tam olarak istenen etki budur. Ayrıca bu konuda bilinçli olmanın nedeni de budur:

  • Kendi oluşturduğunuz veya makineye yazılım yüklemesine izin vereceğiniz birinden gelen sertifikalara güvenin.
  • Diğer kişilerin güvendiği paylaşılan, üretim veya derleme makinelerine geliştirme sertifikası yüklemeyin.
  • Bir iş arkadaşınızın test paketinizi yüklemesi gerektiğinde, .pfx yerine .cer'ı (yalnızca açık anahtar) dağıtmayı tercih edin. Böylece, sizin adınıza imza atma yetkisini kazanmadan derlemelerinize güvenebilirler.

Başka bir test makinesinde bir .cer’a güvenmek için, winapp cert install komutunu doğrudan o makinede çalıştırın — komut, .pfx ya da yalnızca ortak kısmı olan bir .cer kabul eder:

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

Yalnızca yerleşik Windows araçlarını kullanan eşdeğeri:

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

Güvenilen sertifikayı kaldırma

Geliştirme sertifikalarının süresi varsayılan olarak bir yıl sonra dolar, ancak süresinin dolması kaldırıldığı anlamına gelmez. Bir sertifikaya artık ihtiyacınız kalmadığında — proje sona erdiğinde, makine başka bir amaçla yeniden kullanıldığında veya anahtar ele geçirilmiş olabileceğinde — onu özellikle kaldırın.

İlk olarak parmak izini bulun:

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

Ardından makine güven deposundan kaldırın. Bu adımın yükseltilmesi gerekir:

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

cert generate ayrıca sertifikayı özel anahtarıyla birlikte kişisel mağazanıza yerleştirmiştir. Bunu, cert generate öğesini çalıştıran hesapla oturum açılmış normal, yükseltilmemiş bir istemden kaldırın:

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

Important

Yukarıdaki iki komutu gösterilen bağlamlarda çalıştırın. Farklı bir yönetici hesabı kullanarak yükselttiyseniz, Cert:\CurrentUser bu yükseltilmiş oturumda yöneticinin deposu (sizin değil) olduğundan, özel anahtar oluşturan kullanıcının deposunda kalır.

Son olarak, .cer öğesini ve dağıttığınız tüm .pfx kopyalarını silin ve bununla yandan yüklediğiniz paketlerin kaydını kaldırın:

winapp unregister

Note

Sertifika kaldırıldığında, zaten yüklü olan paketler kaldırılmaz. Bunları, Ayarlar > Uygulamalar > Yüklü uygulamalar üzerinden veya geliştirme modunda kayıtlı paketler için winapp unregister kullanarak ayrı ayrı kaldırın.

Geliştirici Modu

Windows, yerleşik, imzalı bir MSIX yüklemek yerine Geliştirici Modu'nun uygulama paketini doğrudan disk üzerindeki bir klasörden (gevşek bir düzen) kaydetmesini gerektirir. winapp run ve create-debug-identity gibi komutlar buna dayanır ve bu olmadan çalışmaz; winapp init ise bunu sizin için etkinleştirmeyi önerir.

Etkinleştirildiğinde ne değişir?

CLI, DWORD altına iki HKEY_LOCAL_MACHINE değeri yazarak Geliştirici Modu'nu etkinleştirir:

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

Bunlar makine genelindeki ayarlar olduğundan, CLI yükseltilmiş bir yardımcı işlemi başlatır ve Windows bir Kullanıcı Hesabı Denetimi istemi gösterir. İstemi reddederseniz hiçbir şey değişmez.

Pratik olarak, bu makinenin şunları yapacağı anlamına gelir:

  • Uygulama paketlerini, MSIX olarak oluşturulmadan veya hiç imzalanmadan, doğrudan diskteki bir klasörden kaydedin (AllowDevelopmentWithoutDevLicense).
  • TrustedPeople(AllowAllTrustedApps) içindeki tüm geliştirme sertifikaları dahil olmak üzere, uygulama paketlerini Microsoft Store dışından, cihazın güvendiği bir sertifika tarafından imzalanmış olmaları koşuluyla yükleyin.

Important

Geliştirici Modu ve güvenilir geliştirme sertifikası, varsayılan yükleme kısıtlamalarının kasıtlı olarak gevşetilmesidir. Bu kombinasyon geliştirme ve test makinelerinde olmalıdır. Bunu üretim makinelerinde, bilgi noktalarında ve paylaşılan altyapıda kapalı bırakın.

Ne zaman etkinleştirildiğini denetleme

winapp init herhangi bir şeyi değiştirmeden önce sorar; --use-defaults ise soruyu tamamen atlayarak Geliştirici Modu'nu olduğu gibi bırakır. Bu, betiklerin çalıştırılmasını ve CI'nin varsayılan olarak güvenli çalışmasını sağlar:

winapp init --use-defaults

Ayarı kendiniz yönetmek isterseniz, Geliştiriciler > için Ayarlar > Sistemi > Geliştirici Modu aracılığıyla bir kez etkinleştirin; CLI bunu algılar ve devam eder.

Kapatma

Ayarlar > Sistemi'ni > geliştiriciler için kullanın ve Geliştirici Modu'nu kapatın. Ayarlar ilişkili işletim sistemi durumunu da temizlediğinden, önerilen yol budur. Daha sonra kayıt defteri değerini onaylamak için:

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

Geliştirici Modu'nu kapatmak güvenilen sertifikaları veya zaten yüklü paketleri kaldırmaz; bkz. Güvenilen sertifikayı kaldırma.

Üretim için imzalama

Geliştirme sertifikası yalnızca açıkça güvenen kişiler için çalışır. Uygulamanızı dağıtmak için, onu Windows'un zaten güvendiği bir kimlikle imzalayın.

İmzalama kimliği seçme

  • Azure Güvenilen İmzalama— bulut tarafından yönetilen bir imzalama hizmeti. Özel anahtar derleme makinenizde hiçbir zaman bulunmaz; bu nedenle korunacak, sızdırılacak veya elle döndürülecek bir .pfx yoktur. Standart Azure kimlik bilgisi zinciriyle kimlik doğrulayan ve GitHub Actions OIDC veya yönetilen kimlikle çalışan winapp az-sign kullanın.

    winapp az-sign .\MyApp.msix

  • Güvenilir bir sertifika yetkilisi tarafından verilen bir kod imzalama sertifikası — bunu ikinci konumsal bağımsız değişken olarak --password öğesine iletin; parolasını ise winapp sign içinde belirtin. Daha sonra anahtar materyalini güvenli bir biçimde saklamak sizin sorumluluğunuzdadır; bunu bir donanım token’ında, bir anahtar kasasında veya CI sağlayıcınızın gizli deposunda saklayın ve asla kod deposunda saklamayın.

  • Microsoft Store: Özel olarak Mağaza üzerinden dağıtım yapıyorsanız paketi sizin için imzalar ve göndermeden önce imzalamanız gerekmez.

Her durumda, seyrek paketler de dahil olmak üzere sertifika konusunun Publisher bildiriminizdeki değerle eşleşmesi gerekir.

İmzalama gizli anahtarlarını depodan uzak tutun

Sertifika parolaları, yapılandırma dosyasına değil CI gizli dizi deponuza aittir. Bunları sabit kodlamak yerine ortamdan okuyun:

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

Aynı durum, Electron Forge yapılandırması gibi kaynak denetimine iade edilmiş derleme yapılandırması için de geçerlidir. Bkz. Elektron paketleme. winapp az-sign, iletilecek bir parola olmadığından bu sorunu tamamen ortadan kaldırır.

Yayımlamadan önce

Yerel testten dağıtıma geçiş için kısa bir denetim listesi:

  • Paket, CA tarafından verilmiş bir sertifikayla veya Azure Güvenilen İmzalama ile imzalanır ya da Mağaza’ya gönderilir — devcert.pfx ile değil.
  • Paketlenmiş çıktının içinde .pfx veya .cer dosyası yok.
  • Kaydedilmiş dosyalarda, derleme betiklerinde veya CI günlüklerinde sertifika parolası görüntülenmez.
  • Sertifika konusu bildirimiyle eşleşir Publisher.
  • Geliştirme sertifikaları ve Geliştirici Modu yalnızca uygulamayı çalıştırması gereken makinelerde etkinleştirilmez.

Güvenlik sorunu bildirme

Winapp CLI'nın kendisinde bir güvenlik açığı bildirmek için SECURITY.md'daki işlemi izleyin. Lütfen güvenlik raporları için genel bir GitHub sorunu açmayın.

  • Last updated on