Referans Materyalleri

Bu sayfa, sslTrus uzaktan kod imzalama hizmetinin farklı entegrasyon yöntemlerinde ortak olarak kullanılan referans bilgilerini derler:

• Kod imzalama sayısı hesaplama kuralları.
• Authenticode ve RFC 3161 zaman damgası protokolleri.
• Yaygın kod imzalama zaman damgası sunucuları.
• Üretim ortamında zaman damgası hizmeti seçerken dikkat edilmesi gerekenler.

İmzalama Sayısı Hesaplama

İmzalama sayısı, fiilen tamamlanan imzalama işlemine göre hesaplanır.

Basit anlatımla:

一个文件成功完成一次签名 = 一次签名次数

İmza sayısı, kaynak kod dosyası sayısına göre hesaplanmaz; ayrıca tek bir derleme, tek bir paketleme veya tek bir CI/CD Pipeline'a göre de hesaplanmaz.

Örneğin:

100 个源代码文件
        ↓
编译生成 1 个 app.exe
        ↓
app.exe 成功签名一次
        ↓
1 次签名

Tek bir derleme şunları üretiyorsa:

app.exe
helper.dll
installer.msi

并且 üç dosya da ayrı ayrı imzalanmışsa:

签名次数 = 3 次

Temel Kurallar

İmzalama sayısı esas olarak şunlara bağlıdır:

1. Son olarak hangi dosya veya nesnelerin imzalandığı.
2. Her nesnenin fiilen kaç kez imzalandığı.
3. Normal istemci imzasının mı, yoksa KSP, Jarsigner gibi alt düzey imzalama çağrı yöntemlerinin mi kullanıldığı.
4. Derleme aracının ek EXE, DLL, kaldırıcı veya kurulum paketini otomatik olarak imzalayıp imzalamadığı.

Yaygın imzalama nesneleri şunlardır:

• .exe
• .dll
• .msi
• .msp
• .sys
• .cat
• .jar
• Kaldırıcı, örneğin uninstall.exe

Bir nesne fiilen başarıyla bir kez imzalandığı sürece, ilgili sayım kuralına göre hesaplanır.

Yalnızca Başarılı İşlemler Sayılır

Yalnızca uzak kod imzalama hizmeti imzalamayı başarıyla tamamladığında imzalama sayısı oluşur.

Aşağıdaki durumlar genellikle sayılmaz:

• Kimlik doğrulama hatası.
• Parametre hatası.
• Sertifika kullanılamıyor.
• Ağ isteği başarısız.
• Sunucu imzalama sonucunu başarıyla döndürmedi.
• Sertifika sorgulama.
• İmzalama kaydı sorgulama.
• İmza doğrulama.
• Mevcut imzayı kaldırma.
• Doğrulama dosyası oluşturma.

Uzak hizmet imzalama sonucunu başarıyla döndürdükten sonra, istemci daha sonra yerel dosya yazma, zaman damgası ekleme veya sonraki işlemleri gerçekleştirme sırasında hata alırsa, zaten tamamlanmış olan uzak imzalama yine başarılı imzalama olarak hesaplanır.

Zaman Damgası Ayrıca Sayılmaz

Zaman damgası, imzanın belirli bir zamanda zaten var olduğunu kanıtlamak için kullanılır ve yeni bir kod imzalama işlemi sayılmaz.

Bu nedenle:

Kod imzalama   → imzalama sayısı üretir
Zaman damgası ekleme → ek imzalama sayısı üretmez
İmza doğrulama → imzalama sayısı üretmez

Zaman damgası hizmetinin başarılı olup olmaması yalnızca nihai imza dosyasının zaman damgası sonucunu etkiler; ek bir kod imzalama işlemi gerçekleştirildiği anlamına gelmez.

SignTool CLI

sslTrus SignTool CLI kullanın:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe

İmza başarılı olursa:

1 个文件 × 1 次成功签名 = 1 次

Örneğin:

signtool sign --cert-code CERT_CODE --file app.exe
signtool sign --cert-code CERT_CODE --file helper.dll
signtool sign --cert-code CERT_CODE --file installer.msi

Üç dosyanın tamamı başarılı:

合计 = 3 次

SignTool CLI ile Çift İmzalama

SHA-1 ve SHA-2'yi aynı anda etkinleştirmek için normal SignTool CLI kullanılıyorsa:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --sha1=true \
  --sha2=true

Normal CLI çift imza, bir istemci imzalama görevi olarak hesaplanır:

GUI / SignTool CLI 双签 = 1 次

İşte normal istemci imzalama akışı ile KSP alt düzey imzalama çağrısının en kolay karıştırıldığı nokta burasıdır.

Windows KSP

KSP, Windows CNG Provider tümleştirme yöntemidir.

Microsoft SignTool, MSBuild, Visual Studio, Electron paketleme araçları veya diğer Windows yazılımları KSP aracılığıyla uzak kod imzalama çağrısı yaptığında, kullanım sayımı şuna daha yakındır:

底层远程私钥签名调用次数

Örneğin:

İşlem	İmza sayısı
app.exe için bir kez SHA256 imzası gerçekleştirme	1 kez
Önce SHA256, ardından SHA1 ekleme	2 kez
app.exe, helper.dll, uninstall.exe ayrı ayrı imzalama	3 kez

Bu nedenle:

SignTool CLI 双签 = 1 次
KSP 双签          = 2 次

Eğer araç aynı dosya üzerinde birden fazla alt düzey imzalama işlemi gerçekleştirirse, her başarılı uzak imzalama ayrı ayrı sayılır.

CSP

CSP, geleneksel Windows CryptoAPI Provider'ıdır.

CSP de Microsoft SignTool veya diğer Windows uygulamaları tarafından Provider aracılığıyla uzak imzalama hizmetini çağırır.

İmza sayısını belirlerken, gerçekte gerçekleşen uzak özel anahtar imzalama işlemi esas alınmalıdır.

Eğer araç birden fazla dosyayı veya aynı dosyayı birden fazla kez imzalarsa, her biri ayrı ayrı sayılmalıdır.

Jarsigner

sslTrusJarsigner Provider kullanıldığında, standart jarsigner imzalama sürecinde uzak kod imzalama hizmetini çağırır.

Genellikle:

İşlem	İmza Sayısı
app.jar imzalama	1 kez
3 JAR'ı ayrı ayrı imzalama	3 kez
Aynı JAR'ı tekrar imzalama	1 kez daha eklenir
jarsigner -verify	0 kez
Doğrulama için keystore oluşturma	0 kez

Bu nedenle:

每个 JAR 每次成功完成签名 = 1 次

Kurulum paketi

Kurulum paketinde şunları ayırt etmek gerekir:

1. Kurulum paketinin içindeki yürütülebilir dosya.
2. Kurulum paketinin kendisi.

Örneğin:

app.exe       → 1 kez imzalanır
installer.msi → 1 kez imzalanır

Bu durumda:

合计 = 2 次

Başka dosyalar varsa:

Dosya	İmzalı mı	İmza sayısı
app.exe	Evet	1
helper.dll	Evet	1
driver.sys	Evet	1
installer.msi	Evet	1
Toplam		4

Kurulum paketinin içinde kaç kaynak kod, kaynak dosyası, görsel veya yapılandırma dosyası bulunduğu imza sayısını doğrudan etkilemez.

Önemli olan:

最终到底有哪些产物被实际签名

Electron

Electron Builder, Electron Forge gibi masaüstü uygulama derleme araçları, tek bir paketleme sürecinde birden fazla dosyayı otomatik olarak imzalayabilir.

Yaygın nesneler şunlardır:

• Ana program .exe
• DLL
• Güncelleme programı
• Kaldırma programı
• Kurulum paketi .exe
• MSI
• Diğer yardımcı yürütülebilir dosyalar

Örneğin:

Ürün	İmzalama sayısı
MyApp.exe	1
ffmpeg.dll	1
update.exe	1
uninstall.exe	1
MyApp Setup.exe	1
Toplam	5

Bu nedenle:

一次 Electron Build ≠ 一次签名

İmzalanan gerçek yapıt sayısına ve her yapıt üzerinde gerçekleştirilen imzalama işlemi sayısına göre hesaplanmalıdır.

Electron KSP kullanıyorsa ve aynı dosyaya çift imza uygulanıyorsa, bu dosya için iki kez uzak imzalama da gerçekleşebilir.

Hızlı değerlendirme

Bir derlemenin kaç imzalama işlemi üreteceği bilinmiyorsa sırasıyla şunları doğrulayın:

1. 最终有哪些文件被签名？
2. 每个文件签了几次？
3. 使用的是 SignTool CLI 还是 KSP / Jarsigner？
4. 构建工具有没有自动签额外文件？

Basitçe şöyle anlaşılabilir:

签名次数 = 成功完成的签名动作数量之和

Özellikle dikkat edilmesi gerekenler:

GUI / SignTool CLI 双签                = 1 次
KSP 对同一个文件执行两次底层签名       = 2 次
Jarsigner 每个 JAR 每次成功签名         = 1 次
时间戳                               = 0 次
验证签名                             = 0 次

Zaman Damgası Sunucusu

Kod imzalama genellikle zaman damgası hizmetini de kullanır.

Zaman damgası, dijital imzanın belirli bir zamanda zaten var olduğunu kanıtlayabilir; böylece doğrulama tarafı, imza sertifikası, zaman damgası sertifikası, iptal durumu ve doğrulama politikasıyla birlikte imzanın geçerliliğini değerlendirebilir.

Kod imzalamada yaygın olarak iki zaman damgası protokolü kullanılır:

Protokol	Açıklama
Authenticode	Microsoft geleneksel zaman damgası protokolüdür, esas olarak eski Windows kod imzalama akışlarıyla uyumluluk için kullanılır
RFC 3161	Genel zaman damgası protokolüdür, modern kod imzalama senaryoları için uygundur

Modern kod imzalama senaryolarında genellikle öncelikle RFC 3161 tercih edilir.

RFC 3161

RFC 3161 zaman damgası isteği, orijinal dosya yerine zaman damgası uygulanacak verinin özetini gönderir.

Temel akış:

代码签名
   ↓
计算待时间戳数据摘要
   ↓
发送摘要到 TSA
   ↓
TSA 返回时间戳令牌
   ↓
写入最终签名

Zaman damgası belirteci genellikle şunları içerir:

• Veri özeti.
• Zaman damgası düzenleme zamanı.
• TSA ilkesi.
• TSA dijital imzası.

Zaman damgası sunucusu, zaman damgası eklenmesi nedeniyle ek sslTrus kod imzalama kullanımı tüketmez.

Yaygın zaman damgası sunucuları

Aşağıdaki uç noktalar, yaygın kod imzalama senaryoları için geçerlidir.

Üretimde kullanmadan önce ilgili sağlayıcının en güncel resmî belgelerini, hizmet ilkelerini ve kullanılabilirliğini yeniden doğrulayın.

Microsoft

http://timestamp.acs.microsoft.com

Öncelikle RFC 3161 zaman damgası için kullanılır.

Windows modern kod imzalama senaryolarında zaman damgası adayı olarak uygundur.

Örnek:

--timestamp-rfc3161=http://timestamp.acs.microsoft.com

Microsoft SignTool：

/tr http://timestamp.acs.microsoft.com
/td SHA256

Sectigo

http://timestamp.sectigo.com

Desteklenenler:

• Authenticode
• RFC 3161

Windows ve ilgili protokolleri destekleyen diğer kod imzalama araçlarında kullanılabilir.

Sectigo, toplu çağrılar için hizmet tarafı kullanım gereksinimleri uygular; üretim sistemleri, çağrı sıklığını mevcut resmi politikasına göre kontrol etmelidir.

DigiCert

http://timestamp.digicert.com

RFC 3161'i destekler; Microsoft Authenticode gibi kod imzalama senaryolarında kullanılabilir.

Certum

http://time.certum.pl

Desteklenenler:

• Authenticode
• RFC 3161

Certum resmi kod imzalama materyalleri, Windows ve Java JAR imzalama senaryolarını kapsar.

GlobalSign

http://timestamp.globalsign.com/tsa/r45standard

Şu anda GlobalSign kod imzalama materyalleri bu RFC 3161 zaman damgası adresini kullanmaktadır.

Artık mevcut resmî kod imzalama belgelerinde yer almayan geçmiş GlobalSign adreslerini kullanmaya devam etmeniz önerilmez.

SSL.com

http://ts.ssl.com

RFC 3161 desteklenir; geleneksel Authenticode zaman damgası protokolü desteklenmez.

Hedef imzalama aracı veya eski sistem, TSA tarafından kullanılan anahtar algoritması konusunda uyumluluk kısıtlamalarına sahipse, üretim entegrasyonundan önce gerçek doğrulama yapılmalıdır.

Zaman damgası sunucusu karşılaştırması

Sağlayıcı	Adres	Authenticode	RFC 3161
Microsoft	http://timestamp.acs.microsoft.com	Doğrulanmadı	Destekleniyor
Sectigo	http://timestamp.sectigo.com	Destekleniyor	Destekleniyor
DigiCert	http://timestamp.digicert.com	Doğrulanmadı	Destekleniyor
Certum	http://time.certum.pl	Destekleniyor	Destekleniyor
GlobalSign	http://timestamp.globalsign.com/tsa/r45standard	Doğrulanmadı	Destekleniyor
SSL.com	http://ts.ssl.com	Desteklenmiyor	Destekleniyor

Tablodaki "Destekleniyor" ifadesi, ilgili sağlayıcının kamuya açık materyalleriyle doğrulanan protokol yeteneğini tanımlar.

Zaman damgası hizmeti politikaları değişebilir; üretim yapılandırmasından önce sağlayıcının güncel resmi materyalleri yeniden kontrol edilmelidir.

Kısıtlı zaman damgası hizmetleri

Bazı zaman damgası sunucuları RFC 3161 hizmeti sunsa da doğrudan anonim genel TSA olarak kullanılamaz.

QuoVadis

Kamuya açık RFC 3161 adresleri şunlardır:

http://ts.quovadisglobal.com/eu
http://ts.quovadisglobal.com/ch

Bu hizmet, çağrı yapan tarafın çıkış IP'sinin önceden kaydedilmesini gerektirir; bu nedenle entegrasyondan önce ilgili yetkilendirmenin tamamlanması gerekir.

Apple

http://timestamp.apple.com/ts01

Apple kod imzalama ekosisteminde kullanılan bir zaman damgası hizmetidir.

Doğrudan Windows Authenticode için genel amaçlı bir zaman damgası sunucusu olarak kullanılmamalıdır.

Test amaçlı zaman damgası hizmeti

Bazı genel RFC 3161 hizmetleri, üretim kodu imzalama TSA'sı olarak doğrudan kullanılmaktan çok protokol testi için uygundur.

Örneğin:

https://freetsa.org/tsr

Bu tür hizmetler kendi CA ve TSA sertifikalarını kullanabilir.

Bu nedenle varsayılamaz:

Windows
macOS
Java
其他代码签名验证器

Varsayılan olarak sertifika zincirine güvenilir.

Üretim ortamında, imzalama ürününü hedef platformda gerçekten doğrulamalısınız.

Üretim Ortamı Kontrolü

Bir zaman damgası sunucusunu üretim yapılandırmasına eklemeden önce en azından şunları doğrulamanız önerilir:

1. Sağlayıcının resmi belgeleri bu uç noktayı açıkça yayımlamış olmalıdır.
2. Sağlayıcı gerekli zaman damgası protokolünü açıkça desteklemelidir.
3. SHA-256 veya daha güçlü bir zaman damgası özet algoritması kullanılmalıdır.
4. Hedef sistem, TSA'nın eksiksiz sertifika zincirini doğrulayabilmelidir.
5. DNS, proxy, güvenlik duvarı ve çıkış ağı TSA'ya kararlı şekilde erişebilmelidir.
6. Kimlik doğrulama yöntemi, hız sınırları, bölge kısıtlamaları ve hizmet koşulları doğrulanmış olmalıdır.
7. Gerçek imzalama ürünüyle doğrulama testi tamamlanmış olmalıdır.

Yalnızca şunlara güvenmeyin:

浏览器可以打开
HTTP 返回 200

Bir zaman damgası sunucusunun kod imzalama için uygun olup olmadığını belirleyin.

Gerçek imzalama aracını kullanarak bir zaman damgası isteği göndermeniz ve nihai ürün üzerinde doğrulama yapmanız gerekir.

Zaman Damgası Seçim Önerileri

Modern Windows SHA-2 kod imzalama için genellikle RFC 3161'i destekleyen zaman damgası hizmetlerini önceliklendirin.

Örneğin:

Microsoft
Sectigo
DigiCert
Certum
GlobalSign

Nihai seçimde kapsamlı olarak şunlar dikkate alınmalıdır:

• Hedef işletim sistemi.
• İmzalama aracı.
• TSA sertifika zinciri.
• Ağ erişilebilirliği.
• Bölge kısıtlamaları.
• Çağrı frekansı sınırlamaları.
• Hizmet koşulları.
• Hizmet düzeyi sözleşmesi.
• Gerçek imza ürünü doğrulama sonuçları.

Sertifika sağlayıcısının zaman damgası hizmetiyle ilgili açık gereksinimleri varsa, ilgili sertifika politikalarına ve sağlayıcı gereksinimlerine öncelikle uyulmalıdır.

İlgili entegrasyon yöntemleri

Farklı entegrasyon yöntemleri bu sayfadaki imza sayısı ve zaman damgası kurallarını kullanır:

Kullanım senaryosu	Dokümantasyon
SignTool CLI	İstemci Aracı
Windows KSP / CSP	Windows Provider
Jarsigner	Java Entegrasyonu
GitHub Actions, Electron Builder, Advanced Installer	CI/CD ve Derleme Araçları
Uzak imzalama arayüzünü doğrudan çağırma	API Entegrasyonu