Referanslar

Bu sayfada, sslTrus uzaktan kod imzalama hizmetinin farklı entegrasyon yöntemlerinde ortak olarak kullanılan referans bilgileri derlenmiştir:

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

İmzalama Sayısı Hesaplama

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

Basitçe anlamak gerekirse:

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

İ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 次签名

Bir derleme şunları üretirse:

app.exe
helper.dll
installer.msi

Ve üç dosyanın da ayrı ayrı imzalanması tamamlandığında:

签名次数 = 3 次

Temel Kurallar

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

1. Sonunda 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 imza çağrı yöntemlerinin mi kullanıldığı.
4. Derleme aracının otomatik olarak ek EXE, DLL, kaldırıcı veya kurulum paketi imzalayıp imzalamadığı.

Yaygın imza nesneleri şunlardır:

• .exe
• .dll
• .msi
• .msp
• .sys
• .cat
• .jar
• Kaldırıcı program, ö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ı Olanlar Sayılır

Yalnızca uzak kod imzalama hizmeti imzalamayı başarıyla tamamladığında imza 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 tarafı imza sonucunu başarıyla döndürmedi.
• Sertifika sorgulama.
• İmza kaydı sorgulama.
• İmza doğrulama.
• Mevcut imzayı kaldırma.
• Doğrulama dosyası oluşturma.

Uzak hizmet imza sonucunu başarıyla döndürdüyse ancak istemci ardından dosyayı yerel olarak yazarken, zaman damgası eklerken veya sonraki işlemleri gerçekleştirirken başarısız olduysa, tamamlanmış olan uzak imza yine başarılı imza 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 değildir.

Bu nedenle:

Kod imzalama       → İmzalama sayısı üretir
Zaman damgası ekleme     → Ek imzalama sayısı üretmez
İmzayı doğrulama       → İmzalama 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 yapıldığı 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

Üç dosya da başarıyla tamamlandı:

合计 = 3 次

SignTool CLI Çift İmzalama

Normal SignTool CLI kullanırken SHA-1 ve SHA-2'yi aynı anda etkinleştirirseniz:

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

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

GUI / SignTool CLI 双签 = 1 次

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

Windows KSP

KSP, Windows CNG Provider entegrasyon yöntemidir.

Microsoft SignTool, MSBuild, Visual Studio, Electron paketleme araçları veya diğer Windows yazılımları, KSP aracılığıyla uzak kod imzalamayı çağırdığında, imzalama 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 uygulayıp ardından SHA1 ekleme	2 kez
app.exe, helper.dll, uninstall.exe için ayrı ayrı imzalama	3 kez

Bu nedenle:

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

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ı belirlenirken, gerçekte gerçekleşen uzak özel anahtar imzalama işlemi esas alınmalıdır.

Araç birden fazla dosyayı veya aynı dosyayı birden fazla kez imzalarsa, bunlar 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 paketinin şunlar arasında ayrım yapması 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

ise:

合计 = 2 次

Başka dosyalar da varsa:

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

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

Önemli olan şudur:

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

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üncelleyici
• Kaldırıcı
• 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 ürün sayısına ve her ürün üzerinde gerçekleştirilen imzalama sayısına göre hesaplanmalıdır.

Electron KSP kullanıyorsa ve aynı dosya üzerinde çift imzalama gerçekleştiriyorsa, bu dosya için iki kez uzak imzalama da oluşabilir.

Hızlı değerlendirme

Bir derlemenin kaç imzalama üreteceği bilinmediğinde sırasıyla şunları doğrulayabilirsiniz:

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

Basitçe şöyle anlaşılabilir:

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

Özel Dikkat:

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

Zaman Damgası Sunucusu

Kod imzalama genellikle zaman damgası hizmetiyle birlikte kullanılır.

Zaman damgası, dijital imzanın belirli bir zamanda var olduğunu kanıtlayarak doğrulama tarafının imza sertifikası, zaman damgası sertifikası, iptal durumu ve doğrulama politikasıyla birlikte imzanın geçerliliğini değerlendirmesini sağlar.

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

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

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

RFC 3161

RFC 3161 zaman damgası isteği, orijinal dosya yerine zaman damgası eklenecek 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 hakkı 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 resmi 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ında kullanım gereksinimleri uygular; üretim sistemleri, mevcut resmi politikalarına göre çağrı sıklığını kontrol etmelidir.

DigiCert

http://timestamp.digicert.com

RFC 3161 desteklenir; Microsoft Authenticode gibi kod imzalama senaryolarında kullanılabilir.

Certum

http://time.certum.pl

Destekler:

• 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 güncel resmî kod imzalama belgelerinde yer almayan eski GlobalSign adreslerinin kullanılmaya devam edilmesi ö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”, ilgili sağlayıcının kamuya açık materyallerinde doğrulanan protokol yeteneğini ifade eder.

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

Genel 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, doğrudan üretim kod imzalama TSA'sı olarak 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 şu varsayımlarda bulunulamaz:

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

Varsayılan olarak sertifika zincirine güvenilir.

Üretim ortamında, hedef platformda imza ürünleri gerçekten doğrulanmalıdır.

Üretim Ortamı Kontrolleri

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

1. Hizmet sağlayıcının resmi belgelerinde bu uç nokta açıkça yayımlanmış olmalıdır.
2. Hizmet 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 tüm sertifika zincirini doğrulayabilmelidir.
5. DNS, proxy, güvenlik duvarı ve çıkış ağı TSA'ya istikrarlı ş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 imza ürünleriyle 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ızla bir zaman damgası isteği göndermeniz ve son üründe 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ı hizmetleri tercih edilir.

Örneğin:

Microsoft
Sectigo
DigiCert
Certum
GlobalSign

Nihai seçim kapsamlı olarak şunları dikkate almalıdır:

• Hedef işletim sistemi.
• İmzalama aracı.
• TSA sertifika zinciri.
• Ağ erişilebilirliği.
• Bölge kısıtlamaları.
• Çağrı sıklığı 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 araçları
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