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ı gerçekleştirmek için kullanılır.

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

sslTrus Cryptographic Service Provider, /csp ve /kc üzerinden entegre edilmesi gereken Windows imzalama süreçleri için uygun olan geleneksel bir CryptoAPI CSP'dir. İmzalama özel anahtarı her zaman bulut HSM'de tutulur; yerel makinede yalnızca CSP DLL'i, imzalama 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'si ve bunun içinde csp alt komutu bulunur.
• Windows SDK yüklüdür ve Microsoft signtool.exe kullanılabilir.
• Geçerli Access Key, Access Secret ve sertifika numarası (CERT_CODE).
• Ağ, kod imzalama hizmetine ve seçilen zaman damgası hizmetine erişebilir.

İki aracın ayrı ayrı kullanılabilir olduğunu 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 aynı anda bulunuyorsa, 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 şunları çalıştırın:

signtool csp install
signtool csp add
signtool csp list

csp add etkileşimli olarak şunları girmenizi ister:

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 değerlerini gerçek sertifika numarası ve imzalanacak dosyayla değiştirin.

Provider'ı Yükleme

Çalıştırın:

signtool csp install

该命令会：

• 将 sslTrusCSP.dll 写入 %ProgramData%\sslTrusKSP 并复制到系统目录。
• 注册 sslTrus Cryptographic Service Provider（Provider 类型为 PROV_RSA_AES）。
• 安装配套 KSP DLL，并注册 sslTrus Key Storage Provider 与 CSP 同名的 CNG Provider alias。
• 创建或保存 %ProgramData%\sslTrusKSP\config.dat；文件使用本机 Windows DPAPI 加密。

安装会修改系统级 Provider 注册，通常必须在管理员终端执行。若系统目录内的 CSP DLL 版本与内嵌版本一致，CLI 会跳过 CSP DLL 复制，但仍会执行 Provider 注册流程。

添加证书配置

执行：

signtool csp add

NICSRS hizmet adresini kullanmanız gerekiyorsa:

signtool csp add --address nicsrs

--address bir URL geçiş parametresi değildir. Mevcut nicsrs, NICSRS hizmetini kullanır; boş değer, racent veya diğer değerler varsayılan hizmeti kullanır.

Eklerken, 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 ş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.

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

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

Geçerli yapılandırmayı görüntüleyin:

signtool csp list

Çıktı; sertifika numarasını, hizmet türünü, Access Key'i ve gizlenmiş Access Secret'i içerir. Lütfen komut çıktıları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ı girin. Bu işlem yalnızca şifreleme yapılandırmasındaki ilgili girdiyi siler; aynı ada sahip .crt sertifika dosyasını silmez. Artık kullanılmadığında lütfen bu dosyayı manuel olarak temizleyin.

Microsoft signtool.exe imzalamayı kullanma

SHA-256 imzalama

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.

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

SHA-1 İmzası 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 imzanın üzerine yazılmasını önlemek için imzanın eklenmesini ifade eder. SHA-1'in gerekip gerekmediği hedef sistem ve sertifika politikasına göre belirlenmelidir; yeni projelerde varsayılan seçim olarak kullanılmamalı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ğrulamanız gerekirse Windows SDK signtool.exe sürüm ve parametre açıklamalarına göre ilgili doğrulama seçeneğini seçebilirsiniz.

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ı 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'ini otomatik olarak kaldırmaz; bu KSP yalnızca CSP kurulum süreci tarafından kullanılıyorsa, gerçek dağıtım durumuna göre dikkatli bir şekilde temizleyin.

Kaldırma sonrasında yerel hassas verileri silmeniz gerekirse, 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ırmayı, sertifikaları ve günlükleri elle silin.

Sık Sorulan Sorular

Belirti	Önerilen Çözüm
cryptographic service provider is only supported on windows	Windows üzerinde CSP yönetim komutunu çalıştırın.
Kurulumda yetki veya sistem dizinine yazma hatası	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 Provider bulunamadı	Kurulum komutunun başarılı olduğunu, mevcut aracın ve Provider'ın x64 olduğunu doğrulayın ve terminali yeniden açıp tekrar deneyin.
İmzalama sırasında sertifika dosyası bulunamadı	/f yolunun, csp add ile indirilen CERT_CODE.crt ile aynı olduğunu doğrulayın.
İmzalama çağrısı başarısız oldu	Sertifika numarasını, hizmet kimlik bilgilerini ve ağ bağlantısını kontrol edin; ardından %ProgramData%\sslTrusKSP\sslTrusCSP.log öğesini görüntüleyin.
Özel hizmet adresi kullanılıyor ancak istek hatası oluşuyor	CSP, istek hizmetini sabit /v1/codesign/sign yolunda tutar; yapılandırılan hizmet adresinde yalnızca http(s)://host[:port] sağlanmalıdır.

Güvenlik Açıklamaları

• 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 geçerli Windows kullanıcı profilinin DPAPI koruması altındadır; doğrudan başka bir kullanıcıya veya makineye kopyalanarak 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 reddi veya zaman damgası hizmetinin kullanılamaması imza hatasına neden olabilir.

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