signtool ksp ile Windows KSP Entegrasyonu

signtool ksp, Windows sslTrus Key Storage Provider (KSP) yönetimini sağlar. KSP kurulumu ve yapılandırması tamamlandıktan sonra, Microsoft signtool.exe CNG Provider aracılığıyla uzak imzalama hizmetini çağırabilir ve özel anahtarı yerel olarak tutmaya gerek kalmaz.

Dikkat

signtool ksp tüm alt komutları yalnızca Windows platformunu destekler. Windows dışı bir platformda herhangi bir ksp alt komutu yürütüldüğünde şu döndürülür: key storage provider is only supported on windows

---

Alt Komutlara Genel Bakış

signtool ksp [command]

Alt komut	Kullanım Amacı
install	KSP DLL'yi kurar ve kaydeder
uninstall	KSP'yi kayıttan kaldırır ve DLL'yi siler
list	Kaydedilmiş KSP anahtar yapılandırmalarını listeler
add	Yeni KSP anahtar yapılandırması ekler (etkileşimli)
del	Belirtilen KSP anahtar yapılandırmasını siler (etkileşimli)

Açıklama

--address parametresi yalnızca ksp add durumunda geçerlidir; sertifika PEM'ini almak ve uzak hizmet adresini kaydetmek için kullanılır.

---

KSP Kurulumu

signtool ksp install

Çalıştırdıktan sonra:

1. Gömülü sslTrusKSP.dll öğesini ProgramData/sslTrusKSP/sslTrusKSP.dll içine yazın.
2. ProgramData içindeki DLL sürümü System32 içindekinden farklıysa, DLL'yi System32'ye kopyalayın.
3. CNG Provider'ı kaydedin: sslTrus Key Storage Provider.
4. KSP yapılandırma dosyasını kaydedin ProgramData/sslTrusKSP/config.dat (DPAPI şifreli).

Dikkat

install sistem düzeyinde CNG Provider kayıt defterini değiştirir, yönetici terminalinde çalıştırılması önerilir. DLL sürümünün aynı olduğu tespit edilirse, ksp is already installed kaydedilir ve doğrudan geri döner.

---

KSP'yi Kaldırma

signtool ksp uninstall

Yürütme sonrasında:

1. CNG Provider'ı kayıttan kaldırın: sslTrus Key Storage Provider.
2. ProgramData/sslTrusKSP/sslTrusKSP.dll öğesini silin.
3. System32 içindeki sslTrusKSP.dll öğesini silin.

Açıklama

uninstall, ProgramData/sslTrusKSP dizininin tamamını silmez. Kaydedilmiş config.dat, sertifika dosyaları ve günlüklerin elle temizlenmesi gerekir.

---

Anahtar yapılandırmasını görüntüleme

signtool ksp list

Çıktı alanı açıklaması:

Alan	Anlamı
No	Sıra numarası
CertCode	Sertifika numarası
ServerUrl	nicsrs veya default olarak görüntülenir
AccessKey	Access Key
AccessSecret	Maskelenmiş Access Secret

Açıklama

• Yapılandırma dosyası yoksa no ksp configuration döndürülür.
• Yapılandırma mevcut ancak anahtar listesi boşsa no ksp key kaydedin.
• AccessSecret maskelenmiş olarak görüntülenir, ancak yapılandırma dosyasının kendisi yine de hassas dosya olarak yönetilmelidir.

---

Anahtar Yapılandırması Ekleme

signtool ksp add

Belirtilen NICSRS Adresi:

signtool ksp add --address nicsrs

Komut etkileşimlidir, sırasıyla girin:

Please enter the access key: your-access-key
Please enter the access secret: your-access-secret
Please enter the certificate code: CERT_CODE

Çalıştırıldıktan sonra:

1. Sertifika PEM'ini almak için uzak /v1/codesign/cert çağrılır.
2. Sertifika ProgramData/sslTrusKSP/CERT_CODE.crt olarak kaydedilir.
3. Anahtar yapılandırması ProgramData/sslTrusKSP/config.dat içine yazılır (DPAPI şifrelemesi).

Sertifika numarası zaten mevcutsa şu uyarı görüntülenir:

The certificate code already exists, do you want to override it? [y/N]

y yazarak üzerine yazın; başka bir değer girin veya doğrudan Enter’a basarsanız vazgeçilir.

Dikkat

ksp add etkileşimli bir komuttur; --access-key, --cert-code gibi etkileşimli olmayan parametreler şu anda desteklenmemektedir. Yapılandırma eklemek uzak API’ye erişir ve sertifika PEM’ini yerel ProgramData dizinine yazar.

---

Anahtar Yapılandırmasını Silme

signtool ksp del

Sertifika numarasını etkileşimli olarak girin:

Please enter the certificate code: CERT_CODE

Yürütmeden sonra config.dat içinden eşleşen anahtar yapılandırmasını silin ve şifrelenmiş yapılandırma dosyasını yeniden kaydedin.

Açıklama

Mevcut uygulama yalnızca yapılandırma öğesini siler, ProgramData/sslTrusKSP/CERT_CODE.crt sertifika dosyasını silmez.

---

Microsoft signtool.exe'yi KSP aracılığıyla kullanma

KSP yapılandırması tamamlandıktan sonra, Sağlayıcı'yı çağırmak için Windows SDK'daki Microsoft signtool.exe aracını kullanın.

Dikkat

Aşağıdaki komutlardaki signtool.exe, Microsoft Windows SDK ile birlikte gelen araçtır, sslTrus CLI değildir. Geçerli dizinde veya PATH'te her ikisi birden bulunuyorsa, karışıklığı önlemek için Windows SDK içindeki signtool.exe tam yolunu kullanın.

SHA256 imzalama örneği:

signtool.exe sign /v ^
  /csp "sslTrus Key Storage Provider" ^
  /kc CERT_CODE ^
  /f C:\ProgramData\sslTrusKSP\CERT_CODE.crt ^
  /fd SHA256 ^
  /tr http://timestamp.acs.microsoft.com ^
  /td SHA256 ^
  .\EXAMPLE.exe

Ek SHA1 imzası ekleme örneği:

signtool.exe sign /v ^
  /csp "sslTrus Key Storage Provider" ^
  /kc CERT_CODE ^
  /f C:\ProgramData\sslTrusKSP\CERT_CODE.crt ^
  /fd SHA1 ^
  /tr http://timestamp.acs.microsoft.com ^
  /td SHA256 ^
  /as ^
  .\EXAMPLE.exe

Parametre Açıklaması:

Parametre	Anlamı
/csp "sslTrus Key Storage Provider"	sslTrus tarafından kurulan KSP Sağlayıcısını belirtir
/kc CERT_CODE	KSP anahtar adını belirtir; sertifika numarası olarak kararlaştırılmıştır
/f C:\ProgramData\sslTrusKSP\CERT_CODE.crt	ksp add tarafından kaydedilen sertifika dosyasını belirtir
/fd SHA256 veya /fd SHA1	Dosya özet algoritması
/tr <url>	RFC3161 zaman damgası hizmeti
/td SHA256	Zaman damgası özet algoritması
/as	İmzayı ekler, mevcut imzayı üzerine yazmaz

---

Sorun Giderme Referansı

Hata Mesajı	Olası Neden	Çözüm Önerisi
key storage provider is only supported on windows	Windows dışı bir platformda ksp komutu çalıştırıldı.	KSP işlemlerini yalnızca Windows üzerinde gerçekleştirin.
no ksp configuration	KSP yapılandırma dosyası henüz oluşturulmadı.	Önce signtool ksp install ve signtool ksp add komutlarını çalıştırın.
no such certificate code	Silinecek sertifika numarası mevcut değil.	Sertifika numarasını doğrulamak için signtool ksp list komutunu kullanın.

---

Güvenlik Notları

• signtool ksp install ve signtool ksp uninstall, Windows sistem dizinini ve CNG Provider kayıt defterini değiştirir; bu işlem genellikle yönetici ayrıcalıkları gerektirir.
• signtool ksp add, uzak sertifika arayüzüne erişir ve sertifika dosyaları ile şifreleme yapılandırmasını ProgramData/sslTrusKSP dizinine yazar.
• Access Secret, KSP yapılandırma dosyası ve yerel günlükler hassas bilgi olarak ele alınmalı; günlüklere veya sürüm deposuna yazılmamalıdır.