CSP Kullanım Kılavuzu

Genel Bakış

Bu kılavuz, Windows üzerinde sslTrus Cryptographic Service Provider (CSP) yapılandırmak ve Windows SDK'nın Microsoft signtool.exe aracını kullanarak bulut HSM ile kod imzalama işlemini gerçekleştirmek içindir.

Bu projenin signtool csp bileşeni, Sağlayıcı'nın kurulumu, yapılandırılması ve bakımından sorumludur; gerçek imzalama işlemi sırasında Windows SDK'nın signtool.exe aracı kullanılır. Bunlar aynı program değildir.

sslTrus Cryptographic Service Provider, /csp ve /kc üzerinden bağlantı gerektiren Windows imzalama süreçleri için uygun olan geleneksel CryptoAPI CSP'dir. İmzalama özel anahtarı her zaman bulut HSM'de saklanır; yerel makinede yalnızca CSP DLL'i, imzalama sertifikası ve Windows DPAPI ile korunan erişim yapılandırması bulunur.

Kullanım Öncesi Hazırlık

• Windows x64 sistemi.
• Sağlayıcı'yı kurmak veya kaldırmak için yönetici olarak çalıştırılan bir terminal.
• Bu projenin signtool CLI'si ve bunun içinde yer alan csp alt komutu bulunmaktadır.
• Windows SDK kurulmuş olup, Microsoft signtool.exe kullanılabilmektedir.
• Geçerli bir Access Key, Access Secret ve sertifika numarası (CERT_CODE) mevcuttur.
• Ağ üzerinden kod imzalama hizmetine ve seçilen zaman damgası hizmetine erişim sağlanabilmektedir.

İki aracın ayrı ayrı çalıştığını doğrulayın:

REM 本项目 CLI
signtool csp --help

REM Windows SDK 工具；必要时请使用其完整路径
signtool.exe sign /?

Geçerli dizinde veya PATH içinde aynı ada sahip iki program varsa, gerçekten hangi programın çağrıldığını tam yolunu kullanarak veya where komutuyla doğrulayın.

Hızlı Başlangıç

Yönetici terminalinde sırayla şu komutları çalıştırın：

signtool csp install
signtool csp add
signtool csp list

csp add etkileşimli olarak şunları isteyecektir:

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

Yapılandırma başarılı olduktan sonra, Windows SDK'nın Microsoft signtool.exe imzasını kullanın:

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

Örnekteki CERT_CODE ve app.exe öğelerini gerçek sertifika numarası ve imzalanacak dosyayla değiştirin.

Provider Kurulumu

Şu komutu çalıştırın:

signtool csp install

Bu komut şunları yapar:

• sslTrusCSP.dll değerini %ProgramData%\sslTrusKSP öğesine yazar ve sistem dizinine kopyalar.
• sslTrus Cryptographic Service Provider komutunu kaydeder (Provider türü PROV_RSA_AES olarak).
• İlgili KSP DLL dosyasını kurar ve sslTrus Key Storage Provider ile CSP ile aynı adı taşıyan CNG Provider takma adını kaydeder.
• %ProgramData%\sslTrusKSP\config.dat öğesini oluşturur veya kaydeder; dosya yerel Windows DPAPI ile şifrelenir.

Kurulum, sistem düzeyindeki Provider kayıtlarını değiştirir, bu nedenle genellikle yönetici terminalinde çalıştırılmalıdır. Sistem dizinindeki CSP DLL sürümü, gömülü sürümle aynıysa, CLI, CSP DLL kopyalama adımını atlar ancak Provider kayıt işlemini yine de gerçekleştirir.

Sertifika Yapılandırması Ekleme

Şu komutu çalıştırın:

signtool csp add

NICSRS hizmet adresini kullanmanız gerekiyorsa:

signtool csp add --address nicsrs

--address bir URL iletim parametresi değildir. Güncel nicsrs NICSRS hizmetini kullanır; boş değer, racent veya diğer değerler varsayılan hizmeti kullanır.

Ekleme sırasında CLI, sertifikayı uzak hizmetten alır ve şuraya yazar:

%ProgramData%\sslTrusKSP\CERT_CODE.crt

Aynı anda hizmet adresini, kimlik bilgilerini, sertifika numarasını ve sertifika yolunu şifrelenmiş yapılandırma dosyasına yazın. CERT_CODE hem uzak sertifika tanımlayıcısıdır hem de sonraki Microsoft signtool.exe içindeki /kc değeridir.

Mevcut bir sertifika numarası eklenirse, CLI üzerine yazılıp yazılmayacağını sorar: eski yapılandırmayı değiştirmek için y girin; doğrudan Enter tuşuna basmak veya başka bir değer girmek mevcut yapılandırmayı korur.

Yapılandırmayı Görüntüleme ve Silme

Mevcut yapılandırmayı görüntüle:

signtool csp list

Çıktı, sertifika numarası, hizmet türü, Access Key ve maskelenmiş Access Secret içerir. Lütfen komut çıktısını, yapılandırma dosyalarını veya günlükleri herkese açık konumlara yüklemeyin.

Belirli bir yapılandırmayı silme:

signtool csp del

İstendiğinde sertifika numarasını girmeniz yeterlidir. Bu işlem yalnızca şifrelenmiş yapılandırmadaki ilgili girdiyi siler; aynı adlı .crt sertifika dosyasını silmez. Dosya artık kullanılmıyorsa elle temizleyin.

Microsoft signtool.exe ile imzalama

SHA-256 imzası

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

Parametre	Açıklama
/csp "sslTrus Cryptographic Service Provider"	CSP Sağlayıcısını belirtir.
/kc CERT_CODE	Sertifika numarasına karşılık gelen anahtar kapsayıcısını belirtir.
/f <证书路径>	csp add tarafından indirilen sertifika dosyasını belirtir.
/fd SHA256	Dosya özet algoritmasını belirtir.
/tr <URL>	RFC 3161 zaman damgası hizmetini belirtir.
/td SHA256	Zaman damgası özet algoritmasını belirtir.

Mevcut CSP, SHA1, SHA256, SHA384 ve SHA512 dosya özet algoritmalarını destekler; yeni imzalar için genellikle SHA-256 veya daha yüksek sürümler önerilir. Zaman damgası adresi, sertifika politikanız ve hedef platform uyumluluğunuz tarafından belirlenmelidir.

SHA-1 İmzası Ekleme

Gerçekten eski sistem uyumluluk gereksinimleri olduğunda, mevcut imzaya SHA-1 eklenebilir:

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

/as ek imzayı belirtir; mevcut imzanın üzerine yazılmasını önler. SHA-1 gerekip gerekmediği, hedef sistem ve sertifika politikalarına uygun olmalıdır; yeni projeler için varsayılan bir seçenek olmamalıdır.

İmzayı Doğrulama

İmzaladıktan sonra Microsoft signtool.exe ile doğrulama yapılabilir:

signtool.exe verify /pa /v ".\app.exe"

Tüm imzaları doğrulamak istiyorsanız, Windows SDK signtool.exe sürümüne ve parametre açıklamalarına göre ilgili doğrulama seçeneğini seçebilirsiniz.

Sağlayıcıyı Kaldırma

Yönetici terminalinde şunu çalıştırın:

signtool csp uninstall

Bu komut, CSP’yi ve CSP ile aynı ada sahip CNG Provider alias’ını kaydını siler ve CSP DLL’sinin ProgramData ile sistem dizini kopyalarını kaldırır. %ProgramData%\sslTrusKSP dizininin tamamını silmez ve eşlik eden sslTrus Key Storage Provider kaydını ve DLL’sini otomatik olarak kaldırmaz; eğer bu KSP yalnızca CSP kurulum süreci tarafından kullanılıyorsa, lütfen gerçek dağıtım durumunuza göre dikkatli bir şekilde temizleyin.

Kaldırma sonrasında yerel hassas verileri kaldırmak istiyorsanız, bunların artık KSP veya diğer imzalama süreçleri tarafından kullanılmadığını doğruladıktan sonra, %ProgramData%\sslTrusKSP içindeki yapılandırmaları, sertifikaları ve günlükleri elle silin.

Sıkça Sorulan Sorular

Olgu	İşlem Önerisi
cryptographic service provider is only supported on windows	Windows üzerinde CSP yönetim komutunu çalıştırın.
Kurulumda izin hatası veya sistem dizinine yazma başarısız	Yönetici terminali kullanarak signtool csp install komutunu çalıştırın.
no csp configuration	Önce signtool csp install çalıştırın, ardından signtool csp add çalıştırın.
no such certificate code	Önce signtool csp list ile sertifika numarasını doğrulayın.
Microsoft signtool.exe Sağlayıcı bulunamıyor	Kurulum komutunun başarılı olduğunu, mevcut aracın ve Sağlayıcı'nın x64 olduğunu doğrulayın ve terminali yeniden açarak tekrar deneyin.
İmzalama sırasında sertifika dosyası bulunamıyor	/f yolunun ve csp add ile indirilen CERT_CODE.crt dosyasının eşleştiğini doğrulayın.
İmzalama çağrısı başarısız	Sertifika numarasını, servis kimlik bilgilerini ve ağ bağlantısını kontrol edin; ardından %ProgramData%\sslTrusKSP\sslTrusCSP.log bölümünü inceleyin.
Özel hizmet adresi kullanılıyor ancak istek hatası	CSP, /v1/codesign/sign yoluna sabitlenmiş istek hizmetini kullanır; yapılandırılan hizmet adresi yalnızca http(s)://host[:port] sağlamalıdır.

Güvenlik Açıklamaları

• Access Secret, config.dat, sertifika dosyaları ve CSP günlükleri hassas veri olarak ele alınmalıdır.
• config.dat, yapılandırmayı oluşturan mevcut Windows kullanıcı profilinin DPAPI korumasına tabidir ve başka kullanıcılara veya makinelere kopyalanıp yeniden kullanılmamalıdır.
• CSP özel anahtarı saklamaz; özel anahtarı içe aktarmaya çalışmayın %ProgramData%\sslTrusKSP.
• CSP imzalama, uzak hizmete erişim gerektirir; ağ zaman aşımı, sunucu reddi veya zaman damgası hizmetinin kullanılamaması imzalama hatasına neden olabilir.

Daha fazla CLI parametresi ve imzalama komutu referansı için lütfen SignTool sign komut referansı bölümüne bakın.