İstemci Araçları

sslTrus, uzak kod imzalama hizmetine bağlanmak ve dosya imzalamak için komut satırı istemcisi ve masaüstü istemcisi sunar.

Bunlardan SignTool CLI komut satırı, betik ve otomasyon senaryoları için uygundur; macOS kullanıcıları ayrıca Homebrew aracılığıyla SignTool CLI veya masaüstü istemcisini yükleyip güncelleyebilir.

SignTool CLI

SignTool CLI, sslTrus tarafından sağlanan uzak kod imzalama komut satırı istemcisidir; kurulumdan sonra yürütülebilir dosya adı signtool şeklindedir.

Başlıca şu yetenekleri sunar:

İşlev	Komut	Açıklama
Dosya imzalama	signtool sign	Yerel dosyalarda uzak kod imzalama gerçekleştirir
İmza kotası	signtool quota	Sertifikanın kalan ve toplam imza kotasını sorgular
İstemci güncelleme	signtool update	Geçerli platform için en son istemciyi sorgular ve yükler
Windows KSP	signtool ksp	Windows Key Storage Provider'ı yükler ve yönetir
Windows CSP	signtool csp	Windows Cryptographic Service Provider'ı yükler ve yönetir

KSP ve CSP, Windows Provider entegrasyon yöntemleridir; kullanım yöntemleri için lütfen Windows Provider bölümüne bakın.

İstemciyi indirme

SignTool CLI, sslTrus istemci yayın sayfasından indirilebilir:

sslTrus istemci yayın sayfası

Yayın sayfası, her platform için en yeni istemci kurulum paketlerini sağlar. Otomasyon senaryolarında, sürüm dizini latest.json aracılığıyla güncel en son sürüm bilgisi sorgulanabilir.

macOS kullanıcıları ayrıca doğrudan Homebrew üzerinden de kurabilir; aşağıdaki macOS Homebrew bölümüne bakın.

İstemci Bilgilerini Görüntüleme

Kurulum tamamlandıktan sonra şunu çalıştırabilirsiniz:

signtool --help

Komut yardımını görüntüleyin.

Geçerli istemci sürümünü görüntüleyin:

signtool --version

Sürüm bilgileri; istemci sürümü, derleme revizyonu, çalışma platformu ve derleme zamanı gibi bilgileri içerir.

Erişim Kimlik Bilgileri

Uzaktan kod imzalama hizmetini kullanmadan önce şunları hazırlamanız gerekir:

• Access Key
• Access Secret
• Sertifika Numarası (Cert Code)

Access Key ve Access Secret, uzaktan kod imzalama hizmetine erişmek için kullanılır; sertifika numarası ise imzayı fiilen gerçekleştirecek kod imzalama sertifikasını belirtmek için kullanılır.

SignTool CLI, kimlik bilgilerini komut parametreleriyle sağlayabileceği gibi ortam değişkenleri aracılığıyla da okuyabilir:

export ACCESS_KEY="your-access-key"
export ACCESS_SECRET="your-access-secret"

Access Secret'i öncelikle ortam değişkenleri, CI/CD Secret veya diğer güvenli kimlik bilgisi yönetimi yöntemleriyle sağlamanız önerilir.

Access Secret'i şunları yapmayın:

• Git deposuna commit etmeyin.
• Herkese açık komut dosyalarına yazmayın.
• Derleme günlüklerine çıktı olarak vermeyin.
• Güvenilmeyen üçüncü taraf sistemlere göndermeyin.

Uzak Hizmet Adresi

Varsayılan olarak SignTool CLI, sslTrus üretim hizmet adresini kullanır; ek yapılandırma gerekmez.

NICSRS (www.nicsrs.com) ortamı kullanılıyorsa, komuta --address nicsrs eklenmesi gerekir:

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

signtool quota ve signtool update aynı zamanda --address nicsrs destekler.

Dosya İmzalama

signtool sign kullanarak yerel dosyalar üzerinde doğrudan uzaktan kod imzalama gerçekleştirebilirsiniz.

En temel imzalama komutu:

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

如果已经设置：

ACCESS_KEY
ACCESS_SECRET

SignTool CLI, ilgili erişim kimlik bilgilerini otomatik olarak okur.

Varsayılan olarak imzalama için SHA-2 kullanılır.

Çıktı Dosyasını Belirleme

Varsayılan olarak, istemci orijinal dosyanın üzerine doğrudan yazmaz.

İmzalanmış çıktı dosyasını --out ile belirtebilirsiniz:

signtool sign \
  --cert-code CERT_CODE \
  --file app-unsigned.exe \
  --out app-signed.exe

Orijinal Dosyanın Üzerine Yazma

Orijinal dosyayı doğrudan değiştirmeniz gerekiyorsa şunu kullanabilirsiniz:

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

--override etkinleştirildiğinde, imza sonucu doğrudan girdi dosyasına geri yazılır.

Otomatik derleme ortamında kullanırken, sonraki adımların orijinal dosyayı mı yoksa imzalı dosyayı mı gerektirdiğini doğrulamanız gerekir.

Program açıklamasını belirtme

Program açıklaması ve URL, Authenticode imzasına yazılabilir:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --desc "Example Application" \
  --url "https://example.com"

SHA-1 ve SHA-2

Varsayılan olarak SHA-2 etkindir:

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

Yalnızca SHA-1 kullanın:

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

SHA-1 ve SHA-2'yi aynı anda etkinleştirin:

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

SHA-1 esas olarak eski sistemlerle uyumluluk için kullanılır; yeni projelerde genellikle SHA-2 tercih edilmelidir.

Zaman Damgası

Kod imzalamada genellikle güvenilir bir zaman damgası eklenmesi önerilir.

SignTool CLI varsayılan olarak imza için zaman damgası hizmetini otomatik yapılandırır; zaman damgası sunucusu parametre ile de belirtilebilir:

• --timestamp-rfc3161: SHA-2 imzalarında kullanılan RFC 3161 zaman damgası sunucusu.
• --timestamp: SHA-1 imzalarında kullanılan Authenticode zaman damgası sunucusu.

RFC 3161 zaman damgası sunucusunu belirtme:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --timestamp-rfc3161=http://timestamp.acs.microsoft.com

Belirtilen Authenticode zaman damgası sunucusu:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --timestamp=http://timestamp.sectigo.com

İlgili zaman damgasını kapatmanız gerekiyorsa parametre değerini boş bırakabilirsiniz:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --timestamp-rfc3161= \
  --timestamp=

Zaman damgası protokolü, sunucu adresi ve seçim önerileri hakkında bilgi için Referans Materyalleri bölümüne bakın.

İmza kotasını sorgulama

Kullanım:

signtool quota

Geçerli erişim belirtecinin görebildiği kod imzalama sertifikası kotasını sorgulayabilirsiniz.

Çıktı içeriği şunları kapsar:

• Sertifika numarası.
• Sertifika bilgileri.
• Kalan imzalama sayısı.
• Toplam imzalama sayısı.

JSON biçiminde çıktı gerekiyorsa:

signtool quota --json

Kısaltma da kullanılabilir:

signtool quota -j

Spesifik imza sayısı hesaplama yöntemi; CLI, KSP, Jarsigner veya derleme aracının çağrılma biçimine göre farklılık gösterebilir. Ayrıntılı kurallar için lütfen İmza Sayısı Hesaplama Açıklaması bölümüne bakın.

İstemciyi Güncelleme

SignTool CLI, mevcut platform için en son sürümün sorgulanmasını ve yüklenmesini destekler:

signtool update

Güncelleme sırasında indirilen dosyanın boyutu ve SHA-256 değeri doğrulanarak istemci dosyasının bütünlüğü kontrol edilir.

SignTool CLI Homebrew aracılığıyla yüklendiyse, iki güncelleme yöntemini aynı anda karıştırmak yerine sürümü Homebrew üzerinden yönetmeye devam etmeniz önerilir.

macOS Homebrew

macOS kullanıcıları, sslTrus resmi Homebrew Tap'ı aracılığıyla SignTool CLI'yı veya masaüstü istemcisini yükleyebilir.

Homebrew Tap'ı Yükleme

Çalıştırın:

brew tap ssltrus-official/tap
brew trust ssltrus-official/tap

Kurulum tamamlandıktan sonra ilgili istemciyi yükleyebilirsiniz.

SignTool CLI'yı Yükleme

Çalıştırın:

brew install ssltrus-official/tap/code-sign-cli

Kurulum tamamlandıktan sonra şunu çalıştırabilirsiniz:

signtool --version

İstemcinin düzgün kurulup kurulmadığını doğrulayın.

Homebrew içindeki yazılım paketi adı:

code-sign-cli

Gerçekte yüklenen komut satırı programının adı:

signtool

Masaüstü İstemcisini Kurma

sslTrus kod imzalama masaüstü istemcisini kurun:

brew install --cask ssltrus-official/tap/code-sign-gui

İlgili Homebrew Cask adı:

code-sign-gui

İstemciyi Güncelleme

İstemci Homebrew ile kurulduysa, yükseltmek için Homebrew kullanılması önerilir.

Önce Homebrew paket bilgilerini güncelleyin:

brew update

SignTool CLI'yi yükseltin:

brew upgrade ssltrus-official/tap/code-sign-cli

Masaüstü istemcisini yükseltin:

brew upgrade --cask ssltrus-official/tap/code-sign-gui

Böylece yerel kurulum sürümü, Homebrew paket meta verileriyle tutarlı kalır.

Windows Provider

Senaryonuz doğrudan SignTool CLI çağırmak değil de; Microsoft SignTool, Visual Studio, MSBuild, Advanced Installer veya diğer Windows yazılımlarının uzak kod imzalama özel anahtarını doğrudan kullanmasını istiyorsanız Windows Provider kullanmalısınız.

sslTrus şunları sağlar:

• KSP (Key Storage Provider) : Windows CNG için.
• CSP (Cryptographic Service Provider) : Geleneksel Windows CryptoAPI için.

Windows Provider bölümüne bakın.

CI/CD Otomatik İmzalama

Sürekli entegrasyon veya otomatik derleme sürecinde imzalama yapmanız gerekiyorsa SignTool CLI'yi elle kurup çağırmanız şart değildir.

Örneğin GitHub Actions, doğrudan sslTrus Code Sign Action kullanabilir:

- name: Sign files
  uses: ssltrus-official/code-sign-action@v1
  with:
    access-key: ${{ secrets.SSLTRUS_ACCESS_KEY }}
    access-secret: ${{ secrets.SSLTRUS_ACCESS_SECRET }}
    cert-code: ${{ secrets.SSLTRUS_CERT_CODE }}
    files: build/app.exe

GitHub Action; Linux, macOS ve Windows Runner'ları destekler ve derleme sürecinde belirtilen dosyalar için doğrudan uzak kod imzalama gerçekleştirebilir.

Tam yapılandırma için CI/CD ve Derleme Araçları bölümüne bakın.

Nasıl Seçilir

Gerçek kullanım şeklinize göre uygun istemciyi veya entegrasyon yöntemini seçebilirsiniz:

Senaryo	Önerilen Yöntem
Terminalde dosyaları manuel imzalama	SignTool CLI
Komut dosyalarıyla toplu imzalama çağırma	SignTool CLI
Kod imzalama kullanım limitini sorgulama	SignTool CLI
macOS'ta CLI kurulumu ve güncelleme	Homebrew
macOS'ta masaüstü istemcisi kullanma	Homebrew
Microsoft SignTool gibi Windows yazılımlarının uzak özel anahtarı doğrudan çağırması	KSP
Geleneksel CryptoAPI yazılımları	CSP
GitHub Actions ile otomatik imzalama	GitHub Actions
Kendi imzalama istemcinizi geliştirme	Uzak Kod İmzalama API'si

Uygulamanız zaten Windows KSP, CSP veya diğer standart Provider'ları destekliyorsa, genellikle ilgili standart entegrasyon yöntemine öncelik verilmelidir; imzalama sürecini doğrudan kontrol etmeniz gerekiyorsa SignTool CLI veya Uzak Kod İmzalama API'sini kullanabilirsiniz.