İstemci Araçları

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

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

SignTool CLI

SignTool CLI, sslTrus tarafından sağlanan uzak kod imzalama komut satırı istemcisidir. Kurulum sonrası çalıştırılabilir dosya adı signtool şeklindedir.

Başlıca şu yetenekleri sunar:

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

KSP ve CSP, Windows Provider entegrasyon yöntemlerine aittir. Ayrıntılı kullanım için lütfen Windows Provider bölümüne bakın.

İstemciyi İndirme

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

sslTrus İstemci Yayın Sayfası

Yayın sayfası, tüm platformlar için en son istemci kurulum paketlerini sunar. Otomasyon senaryoları ayrıca sürüm dizini latest.json üzerinden güncel en son sürüm bilgilerini sorgulayabilir.

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

İstemci Bilgilerini Görüntüleme

Kurulum tamamlandıktan sonra şu komutu çalıştırabilirsiniz:

signtool --help

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

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

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 aşağıdakilerin hazırlanması 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 imzalamayı fiilen gerçekleştirecek kod imzalama sertifikasını belirtmek için kullanılır.

SignTool CLI, kimlik bilgilerini komut parametreleriyle sağlayabilir veya ortam değişkenlerinden okuyabilir:

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

Access Secret'in, ortam değişkenleri, CI/CD Secret'ları veya diğer güvenli kimlik bilgisi yönetim yöntemleri aracılığıyla sağlanması önerilir.

Access Secret'i şu durumlarda kullanmayın:

• Git deposuna gönderme.
• Açık betiklere yazma.
• Derleme günlüklerine çıktı verme.
• Güvenilmeyen üçüncü taraf sistemlere gönderme.

Uzaktan Hizmet Adresi

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

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 ayrıca --address nicsrs destekler.

Dosya İmzalama

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

En temel imzalama komutu:

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

Eğer zaten ayarlanmışsa:

ACCESS_KEY
ACCESS_SECRET

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

İmzalama varsayılan olarak SHA-2 kullanılarak gerçekleştirilir.

Çıktı dosyasını belirtme

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

İmzalanan çıktı dosyası --out ile belirtilebilir:

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

Orijinal dosyanın üzerine yazma

Eğer orijinal dosyayı doğrudan değiştirmek istiyorsanız, şunları 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 ortamlarında kullanırken, sonraki adımların orijinal dosyayı mı yoksa imzalanmış dosyayı mı gerektirdiğini doğrulamalısınız.

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

Aynı anda SHA-1 ve SHA-2’yi etkinleştir:

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

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

Zaman Damgası

Kod imzalama işlemlerinde genellikle güvenilir bir zaman damgasının da eklenmesi önerilir.

SignTool CLI, imzalama için varsayılan olarak otomatik bir zaman damgası hizmeti yapılandırır; ayrıca parametreler aracılığıyla zaman damgası sunucusu da belirtilebilir:

• --timestamp-rfc3161: SHA-2 imzaları için kullanılan RFC 3161 zaman damgası sunucusu.
• --timestamp: SHA-1 imzaları için 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

Authenticode zaman damgası sunucusunu belirtin:

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

Gerekli zaman damgasını kapatmak istiyorsanız, parametre değerini boş bırakabilirsiniz:

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

Zaman damgası protokolü, sunucu adresleri ve seçim önerileri hakkında bilgi için lütfen Referanslara bakınız.

İmza Kotasını Sorgulama

Kullanım:

signtool quota

Geçerli erişim kimlik bilgisiyle görülebilen kod imzalama sertifikalarının kotasını sorgulayabilirsiniz.

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

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

JSON formatında çıktı gerekiyorsa:

signtool quota --json

Ayrıca kısaltma da kullanabilirsiniz:

signtool quota -j

İmza sayısının hesaplanma yöntemi CLI, KSP, Jarsigner veya derleme aracının çağrı biçimine göre değişebilir. Ayrıntılı kurallar için İmza sayısının hesaplanması bölümüne bakın.

İstemciyi güncelleme

SignTool CLI, geçerli platformun en son sürümünü sorgulamayı ve yüklemeyi 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 üzerinden kurulduysa, iki güncelleme yöntemini aynı anda karıştırmak yerine sürüm yönetiminin Homebrew üzerinden devam ettirilmesi önerilir.

macOS Homebrew

macOS kullanıcıları, SignTool CLI veya masaüstü istemcisini sslTrus resmi Homebrew Tap deposu üzerinden kurabilir.

Genel depo: ssltrus-official/homebrew-tap

Homebrew Tap Kurulumu

Çalıştırın:

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

Tamamlandıktan sonra ilgili istemci kurulabilir.

SignTool CLI'yi Kurun

Şunu çalıştırın:

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

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

signtool --version

İstemcinin doğru şekilde kurulduğunu doğrulayın.

Homebrew paketinin adı:

code-sign-cli

Kurulan komut satırı programının adı:

signtool

Masaüstü istemcisini kurma

sslTrus kod imzalama masaüstü istemcisini kurun:

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

İlgili Homebrew Cask adı şu şekildedir:

code-sign-gui

İstemciyi güncelleme

İstemci Homebrew üzerinden kurulduysa Homebrew kullanarak yükseltmeniz önerilir.

Önce Homebrew yazılım paketi 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

Bu şekilde, yerel kurulum sürümü ile Homebrew paket meta verileri tutarlı kalır.

Windows Provider

Senaryonuz doğrudan SignTool CLI'yi çağırmak değilse, ancak 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ı sunar:

• 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 manuel olarak kurup çağırmanız her zaman gerekmez.

Örneğin GitHub Actions, sslTrus Code Sign Action'ı doğrudan 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 doğrudan belirtilen dosyalar üzerinde uzaktan kod imzalama işlemini gerçekleştirebilir.

Genel depo: ssltrus-official/code-sign-action

Tam yapılandırma için bkz. CI/CD ve Derleme Araçları.

Nasıl Seçilir

Gerçek kullanım şekline göre uygun istemci veya entegrasyon yöntemi seçilebilir:

Senaryo	Önerilen Yöntem
Terminalde dosyaları elle imzalamak	SignTool CLI
Komut dosyalarıyla toplu imzalama çağrısı yapmak	SignTool CLI
Kod imzalama kotasını sorgulamak	SignTool CLI
macOS'ta CLI kurulumu ve güncellemesi	Homebrew
macOS'ta masaüstü istemcisi kullanmak	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 otomatik imzalama	GitHub Actions
Kendi imzalama istemcinizi geliştirmek	Uzaktan Kod İmzalama API'si

Uygulamanız Windows KSP, CSP veya diğer standart Provider'ları zaten destekliyorsa, genellikle ilgili standart entegrasyon yöntemi öncelikli olarak kullanılmalıdır; imzalama sürecini doğrudan kontrol etmeniz gerekiyorsa SignTool CLI veya Uzaktan Kod İmzalama API'sini kullanabilirsiniz.