CSP Kullanım Talimatları

Genel Bakış

Bu talimat, Windows üzerinde sslTrus Cryptographic Service Provider (CSP) yapılandırmak ve Windows SDK'nın Microsoft signtool.exe aracılığıyla bulut HSM kullanarak kod imzalamayı tamamlamak içindir.

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

sslTrus Cryptographic Service Provider, /csp ve /kc üzerinden erişilmesi gereken Windows imzalama akışları için uygun olan geleneksel bir CryptoAPI CSP'sidir. İmza özel anahtarı her zaman bulut HSM'de tutulur; yerel makinede yalnızca CSP DLL'i, imza sertifikası ve Windows DPAPI ile korunan erişim yapılandırması saklanır.

Kullanım Öncesi Hazırlık

• Windows x64 sistemi.
• Provider'ı kurmak veya kaldırmak için yönetici olarak çalıştırılan terminal.
• Bu projenin signtool CLI aracı ve bu araçta csp alt komutu bulunur.
• Windows SDK kurulu olup Microsoft signtool.exe kullanılabilir durumdadır.
• Geçerli Access Key, Access Secret ve sertifika numarası (CERT_CODE) mevcuttur.
• Ağ üzerinden kod imzalama hizmetine ve seçilen zaman damgası hizmetine erişilebilir.

İki aracın ayrı ayrı kullanılabilir olduğunu doğrulayın:

REM 本项目 CLI
signtool csp --help

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

Aynı dizinde veya PATH içinde aynı ada sahip iki program aynı anda mevcutsa, mutlaka tam yol veya where aracılığıyla gerçek çağrı hedefini doğrulayın.

Hızlı Başlangıç

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

signtool csp install
signtool csp add
signtool csp list

csp add etkileşimli olarak şunları girmenizi 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, imzalamak için Windows SDK'nın Microsoft signtool.exe aracı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 ifadelerini gerçek sertifika numarası ve imzalanacak dosyayla değiştirin.

Sağlayıcıyı Yükleme

Çalıştırın:

signtool csp install

Bu komut şunları yapacaktır:

• sslTrusCSP.dll dosyasını %ProgramData%\sslTrusKSP içine yazıp sistem dizinine kopyalar.
• sslTrus Cryptographic Service Provider kaydını oluşturur (Provider türü PROV_RSA_AES).
• Eşlik eden KSP DLL'ini kurar ve CSP ile aynı ada sahip sslTrus Key Storage Provider CNG Provider alias'ını kaydeder.
• %ProgramData%\sslTrusKSP\config.dat oluşturur veya kaydeder; dosya yerel Windows DPAPI ile şifrelenir.

Kurulum sistem düzeyinde Provider kayıtlarını değiştirdiğinden 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 kopyalamayı atlar ancak Provider kayıt işlemini yine de gerçekleştirir.

Sertifika yapılandırması ekleme

Çalıştırın:

signtool csp add

如需使用 NICSRS 服务地址：

signtool csp add --address nicsrs

--address bir URL yönlendirme parametresi değildir. Mevcut 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ı zamanda servis adresini, kimlik bilgilerini, sertifika numarasını ve sertifika yolunu şifreli 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.

Zaten mevcut bir sertifika numarası eklenirse, CLI üzerine yazıp yazmayacağınızı sorar: eski yapılandırmayı değiştirmek için y girin; doğrudan Enter'a basar veya başka bir değer girerseniz mevcut yapılandırma korunur.

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

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

signtool csp list

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

Bir yapılandırmayı silin:

signtool csp del

İstendiğinde sertifika numarasını girin. Bu işlem yalnızca şifreleme yapılandırmasındaki ilgili girişi siler; aynı ada sahip .crt sertifika dosyasını silmez. Artık kullanılmadığında lütfen bu dosyayı manuel olarak temizleyin.

Microsoft signtool.exe imzalama kullanımı

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çıklaması:

Parametre	Açıklama
/csp "sslTrus Cryptographic Service Provider"	CSP Provider'ı belirtir.
/kc CERT_CODE	Sertifika numarasına karşılık gelen anahtar kapsayıcısını belirtir.
/f <证书路径>	csp add ile 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.

Şu anda CSP, SHA1, SHA256, SHA384 ve SHA512 dosya özet algoritmalarını destekler; yeni imzalar için genellikle SHA-256 veya daha üstünün kullanılması önerilir. Zaman damgası adresi, sertifika politikanıza ve hedef platform uyumluluğuna göre belirlenmelidir.

SHA-1 imzası ekleme

Eski sistem uyumluluğu gerçekten gerektiğinde, mevcut imzanın üzerine 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, mevcut imzaların üzerine yazılmasını önlemek için imza eklemeyi ifade eder. SHA-1'in gerekli olup olmadığı hedef sistem ve sertifika politikasına göre belirlenmelidir; yeni projelerde varsayılan seçenek olmamalıdır.

İmzayı Doğrulama

İmzaladıktan sonra Microsoft signtool.exe ile doğrulayabilirsiniz:

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

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

Provider'ı 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ı kayıttan kaldırır, ayrıca CSP DLL'inin ProgramData ve sistem dizini kopyalarını siler. %ProgramData%\sslTrusKSP dizininin tamamını silmez ve eşlik eden sslTrus Key Storage Provider kaydını ve DLL'i otomatik olarak kaldırmaz; bu KSP yalnızca CSP kurulum süreci tarafından kullanılıyorsa, lütfen gerçek dağıtım durumuna göre dikkatli bir şekilde temizleyin.

Kaldırma sonrasında yerel hassas verileri kaldırmanız gerekiyorsa, 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ırma, sertifika ve günlükleri elle silin.

SSS

Belirti	İşlem Önerisi
cryptographic service provider is only supported on windows	Windows üzerinde CSP yönetim komutunu çalıştırın.
Kurulum sırasında izin veya sistem dizinine yazma hatası oluşuyor	Yönetici terminali kullanarak signtool csp install komutunu çalıştırın.
no csp configuration	Önce signtool csp install komutunu, ardından signtool csp add komutunu ç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	Yükleme komutunun başarılı olduğunu, mevcut aracın ve Sağlayıcının her ikisinin de x64 olduğunu doğrulayın ve terminali yeniden açtıktan sonra tekrar deneyin.
İmzalama sırasında sertifika dosyası bulunamıyor	/f yolunun csp add ile indirilen CERT_CODE.crt ile eşleştiğini doğrulayın.
İmzalama çağrısı başarısız	Sertifika numarasını, hizmet kimlik bilgilerini ve ağ bağlantısını kontrol edin; ardından %ProgramData%\sslTrusKSP\sslTrusCSP.log öğesine bakın.
Özel hizmet adresi kullanıldığında istek hatası oluşuyor	CSP, istek hizmetinin /v1/codesign/sign yolunu sabitler; yapılandırılan hizmet adresi yalnızca http(s)://host[:port] sağlamalıdır.

Güvenlik notları

• Access Secret, config.dat, sertifika dosyaları ve CSP günlükleri hassas materyal olarak ele alınmalıdır.
• config.dat, yapılandırmayı oluşturan mevcut Windows kullanıcı profilinin DPAPI koruması altındadır; doğrudan başka bir kullanıcıya veya makineye kopyalanıp yeniden kullanılmamalıdır.
• CSP özel anahtarları saklamaz; özel anahtarı %ProgramData%\sslTrusKSP içine aktarmaya çalışmayın.
• CSP imzalama uzak hizmete erişim gerektirir; ağ zaman aşımı, sunucu tarafında reddetme veya zaman damgası hizmetinin kullanılamaması imza başarısızlığına neden olabilir.

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