CI/CD ve Derleme Araçları

sslTrus uzaktan kod imzalama hizmeti, CI/CD, uygulama derleme ve kurulum paketi oluşturma süreçlerine entegre edilebilir; derleme veya paketleme tamamlandıktan sonra yayınlanan ürünler üzerinde otomatik olarak kod imzalama işlemi gerçekleştirir.

Şu anda desteklenen tipik entegrasyon senaryoları şunlardır:

GitHub Actions
Electron Builder
Advanced Installer

Derleme aracının yeteneklerine bağlı olarak, sslTrus GitHub Action'ını doğrudan kullanabilir, SignTool CLI'yı çağırabilir veya derleme aracının sağladığı özel imzalama arayüzü aracılığıyla entegrasyonu tamamlayabilirsiniz.

GitHub Actions

sslTrus resmi GitHub Action'ını sunar:

ssltrus-official/code-sign-action

Kaynak kod ve sürüm notları için ssltrus-official/code-sign-action adresine bakın. Şu anki kararlı kullanım, ana sürüm etiketi @v1 kullanır.

GitHub Actions Workflow içinde derlenen ürünler üzerinde doğrudan uzaktan kod imzalama işlemi gerçekleştirebilirsiniz.

Action, sslTrus uzaktan kod imzalama hizmetini çağırarak imzalamayı tamamlar ve belirtilen dosyaları doğrudan günceller; Linux, macOS ve Windows Runner için uygundur.

GitHub Secrets Hazırlama

Uzaktan kod imzalama kimlik bilgilerini GitHub Actions Secrets içinde saklamanız önerilir:

SSLTRUS_ACCESS_KEY
SSLTRUS_ACCESS_SECRET
SSLTRUS_CERT_CODE

Access Secret'i doğrudan Workflow dosyasına yazmayın.

Temel Yapılandırma

- 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

İmza başarılı olduğunda, build/app.exe imzalanan dosyanın kendisiyle doğrudan değiştirilir.

Birden Fazla Dosyayı İmzalama

files birden fazla dosyayı yapılandırmak için çok satırlı kullanımı destekler:

- 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
      build/library.dll
      build/installer.msi

Dosya yolları virgülle de ayrılabilir.

Tekrarlanan dosya yolları yalnızca bir kez işlenir.

Tam Yapılandırma

- 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
      build/library.dll
      build/installer.msi
    dry-run: false
    timestamp-rfc3161: http://timestamp.acs.microsoft.com
    description: Example Application
    description-url: https://example.com

Ana Parametreler:

Parametre	Zorunlu	Varsayılan Değer	Açıklama
`access-key`	Evet	-	sslTrus Access Key
`access-secret`	Evet	-	sslTrus Access Secret
`cert-code`	Evet	-	Kod imzalama sertifika numarası
`files`	Evet	-	İmzalanacak dosya yolu
`nicsrs`	Hayır	`false`	NICSRS hizmetinin kullanılıp kullanılmayacağı
`dry-run`	Hayır	`false`	Yerel test sertifikası ile test imzalama işlemi gerçekleştir
`timestamp-rfc3161`	Hayır	`auto`	RFC 3161 zaman damgası sunucusu; boş değer girilmesi zaman damgasını devre dışı bırakır
`description`	Hayır	-	Authenticode imzasına yazılacak program açıklaması
`description-url`	Hayır	-	Authenticode imzasına yazılacak program URL'si

Tam Workflow Örneği

Aşağıda, Windows Runner'da derleme, imzalama ve derleme çıktısını yükleme işlemlerini gerçekleştiren örnek verilmiştir:

name: Build and Sign

on:
  workflow_dispatch:

permissions:
  contents: read

jobs:
  build:
    runs-on: windows-latest

    steps:
      - name: Check out repository
        uses: actions/checkout@v7

      - name: Build
        run: |
          # 在这里执行实际构建命令

      - 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
            build/library.dll
          timestamp-rfc3161: http://timestamp.acs.microsoft.com

      - name: Upload signed files
        uses: actions/upload-artifact@v7
        with:
          name: signed-files
          path: |
            build/app.exe
            build/library.dll

Önerilen imza adımı yeri:

Derleme → Paketleme → Kod İmzalama → Yayınlama

Süreçteki yayın adımından önce.

Çok Platformlu Runner

GitHub Action farklı Runner’larda çağrılabilir:

strategy:
  matrix:
    os:
      - ubuntu-latest
      - macos-latest
      - windows-latest

runs-on: ${{ matrix.os }}

Bu nedenle, derleme görevi Linux veya macOS üzerinde çalışsa bile, desteklenen dosyaların uzaktan imzalanması için aynı Action kullanılabilir.

Dry Run

Workflow ve dosya işleme mantığını doğrulamak gerekiyorsa, şu özellik etkinleştirilebilir:

dry-run: true

Bu mod, yerel test sertifikalarını kullanır ve uzak kod imzalama hizmetini çağırmaz.

Örneğin:

- name: Test signing
  uses: ssltrus-official/code-sign-action@v1
  with:
    access-key: dummy
    access-secret: dummy
    cert-code: dummy
    files: build/app.exe
    dry-run: true

dry-run yine de hedef dosyayı değiştirecektir, bu nedenle bunu dosyayı hiç değiştirmeyen bir önizleme modu olarak anlamayın.

Electron Builder

Electron Builder, özel imzalama işlevi aracılığıyla sslTrus SignTool CLI’yı çağırabilir, böylece Electron uygulaması derleme sürecinde Windows yürütülebilir dosyalarının ve yükleyici paketlerinin imzalanmasını otomatik olarak tamamlayabilir.

Tipik akış:

Electron Builder
      ↓
customSign
      ↓
SignTool CLI
      ↓
sslTrus 远程代码签名服务
      ↓
云端 HSM

Ön Koşullar

Başlamadan önce:

Kullanılabilir bir sslTrus uzaktan kod imzalama hizmetinizin olması gerekir.
Access Key ve Access Secret almış olmanız gerekir.
Kod imzalama sertifika numaranızı almış olmanız gerekir.
Electron projesi electron-builder ile derlenir.
Derleme ortamı sslTrus SignTool CLI'yi çalıştırabilmelidir; sslTrus istemci sürüm sayfasından indirilebilir.

Kimlik Bilgilerini Yapılandırma

Kimlik bilgileri, ortam değişkenleri aracılığıyla derleme betiğine aktarılabilir:

Linux ve macOS:

export SIGNTOOL_ACCESS_KEY="YOUR_ACCESS_KEY"
export SIGNTOOL_ACCESS_SECRET="YOUR_ACCESS_SECRET"
export SIGNTOOL_CERT_CODE="YOUR_CERT_CODE"

Windows PowerShell：

$env:SIGNTOOL_ACCESS_KEY = "YOUR_ACCESS_KEY"
$env:SIGNTOOL_ACCESS_SECRET = "YOUR_ACCESS_SECRET"
$env:SIGNTOOL_CERT_CODE = "YOUR_CERT_CODE"

Bu değişkenler, Electron özel imza betiği tarafından okunur ve ardından SignTool CLI'ye iletilir.

Electron Builder'ı Yapılandırma

Şurada:

electron-builder.mjs

veya projenin fiilen kullandığı Electron Builder yapılandırma dosyasında, Windows için özel imza işlevini ayarlayın:

export default {
  win: {
    target: [
      {
        target: 'nsis',
        arch: ['x64'],
      },
    ],
    sign: customSign,
    signingHashAlgorithms: ['sha256'],
  },
};

win.sign ifadesi, Electron Builder resmi olarak sağlanan özel imza giriş noktasıdır, ayrıntılı açıklama için lütfen Electron Builder Windows kod imzalama belgelerine bakın.

customSign

sslTrus SignTool CLI'yi çağırmaktan sorumludur.

Özel imzalama işlevi

Örnek:

import { execFileSync } from 'node:child_process';

async function customSign(configuration) {
  const {
    SIGNTOOL_ACCESS_KEY,
    SIGNTOOL_ACCESS_SECRET,
    SIGNTOOL_CERT_CODE,
  } = process.env;

  if (
    !SIGNTOOL_ACCESS_KEY ||
    !SIGNTOOL_ACCESS_SECRET ||
    !SIGNTOOL_CERT_CODE
  ) {
    throw new Error('Missing sslTrus signing credentials');
  }

  execFileSync(
    './signtool',
    [
      'sign',
      '--access-key',
      SIGNTOOL_ACCESS_KEY,
      '--access-secret',
      SIGNTOOL_ACCESS_SECRET,
      '--cert-code',
      SIGNTOOL_CERT_CODE,
      '--file',
      configuration.path,
      '--override=true',
      '--sha1=false',
      '--sha2=true',
      '--timestamp-rfc3161=http://timestamp.acs.microsoft.com',
    ],
    {
      stdio: 'inherit',
    },
  );
}

Alt süreçleri çağırmak için tam Shell komutu birleştirmek yerine parametre dizisi kullanmanız önerilir; bu, yol kaçışı ve özel karakter işleme sorunlarını azaltır.

Electron Builder, signingHashAlgorithms içindeki her hash algoritması için imza fonksiyonunu ayrı ayrı çağırır. Yukarıdaki örnek yalnızca SHA-256'yı etkinleştirir, bu yüzden her dosya için bir kez çağrılır.

Yapıyı Çalıştırma

Yapılandırma tamamlandıktan sonra, Electron Builder'ı normal şekilde çalıştırın:

npx electron-builder build \
  --config electron-builder.mjs \
  --win \
  --x64

Electron Builder, dosyalar üzerinde imzalama işlemi yapması gerektiğinde otomatik olarak customSign öğesini çağırır.

Tek bir Electron derlemesi birden fazla dosyayı imzalayabilir, örneğin:

MyApp.exe
helper.dll
update.exe
uninstall.exe
MyApp Setup.exe

Bu nedenle, bunu basitçe "bir Electron paketlemesi yalnızca bir kez imza üretir" olarak anlamamak gerekir.

Gerçek imza sayısı, derleme sürecinde kaç dosyanın uzaktan imzalandığına bağlıdır.

Advanced Installer

Advanced Installer, Windows Installer teknolojisine dayalı bir kurulum paketi oluşturma aracıdır.

Advanced Installer'ın özel imza aracı özelliği aracılığıyla sslTrus SignTool CLI çağrılabilir; böylece MSI, EXE, CAB gibi derleme çıktıları paketleme sırasında otomatik olarak uzaktan kod imzalama işlemini tamamlar.

Ön Koşullar

Aşağıdakilerin hazırlanması gerekir:

sslTrus SignTool CLI, sslTrus istemci yayın sayfasından indirilebilir.
Access Key.
Access Secret.
Sertifika numarası.
Yapılandırması tamamlanmış Advanced Installer projesi.

Özel İmza Aracını Yapılandırma

Advanced Installer projesinin şu bölümünü açın:

Digital Signature

Yapılandırma sayfası.

Kod imzalamayı etkinleştirdikten sonra, imzalama aracını şu şekilde seçin:

Custom

İmza aracı yolu, sslTrus SignTool CLI çalıştırılabilir dosyası olarak ayarlanır.

Örneğin:

C:\Tools\sslTrus\signtool.exe

Özel parametrelerin çağrılması gerekir:

sign

Alt komut olarak istemciye şunlar iletilir:

Access Key
Access Secret
Cert Code
SHA-2 imza ayarı
Zaman damgası sunucusu
Dosya yolu

Access Key ve Access Secret'ın güvenli bir yolla sağlanması önerilir; uzun süre geçerli olan Access Secret'ın açık metin olarak herkese açık proje dosyalarında saklanmasından kaçınılmalıdır.

SignTool Parametre Örneği

Karşılık gelen imza mantığı şuna benzer:

signtool.exe sign ^
  --access-key="YOUR_ACCESS_KEY" ^
  --access-secret="YOUR_ACCESS_SECRET" ^
  --cert-code="YOUR_CERT_CODE" ^
  --nest=true ^
  --sha1=false ^
  --sha2=true ^
  --timestamp-rfc3161=http://timestamp.acs.microsoft.com ^
  --desc="Example Application" ^
  --override=true ^
  --file "app.exe"

Advanced Installer'de, gerçek dosya yolu, özel imza aracı mekanizması tarafından iletilmelidir; örnekteki app.exe değerine sabitlenmemelidir.

Yapılandırma

Advanced Installer kullanarak paket içindeki dosyaları otomatik imzalıyorsanız, hem derleme hem de sıkıştırma yöntemini kontrol etmeniz gerekir.

Projenin gerçek yapılandırmasına bağlı olarak, bazı CAB arşivleme yöntemleri özel imzalama sürecini etkileyebilir. İmzalanması gereken dosyaların ilgili aşamada çağrılabildiğini doğrulamanız gerekir.

Yapılandırmayı tamamladıktan sonra Advanced Installer'ın dijital imza sayfasında kontrol edebilirsiniz:

Files configured for signing

Böylece, derleme işlemi sırasında hangi dosyaların imzalanacağını doğrulayabilirsiniz.

İmza Sayısı

Advanced Installer, tek bir kurulum paketi derlemesi sırasında birden fazla dosyayı ayrı ayrı imzalayabilir.

Örneğin:

Dosya	İmza
`app.exe`	1 kez
`helper.dll`	1 kez
`uninstall.exe`	1 kez
`installer.msi`	1 kez
Toplam	4 kez

Dolayısıyla:

一次构建 ≠ 一次签名

Hesaplama, uzaktan imzalanan dosyaların veya gerçekleştirilen imzalama işlemlerinin fiili sayısına göre yapılmalıdır.

İmza Sayısı

CI/CD ve derleme araçları genellikle birden fazla ürünü otomatik olarak işler; bu nedenle imza sayısına özellikle dikkat edilmesi gerekir.

Temel ilkeler:

签名次数 = 实际成功完成的签名动作数量

app.exe        → 1 次
library.dll    → 1 次
installer.msi  → 1 次

Üç dosyanın da başarıyla imzalanması durumunda:

合计 = 3 次

Electron Builder ve Advanced Installer gibi derleme araçları ayrıca otomatik olarak oluşturup imzalayabilir:

Ana program.
DLL.
Güncelleyici.
Kaldırıcı.
MSI.
EXE kurulum paketi.
Diğer yardımcı çalıştırılabilir dosyalar.

Bu nedenle, imza sayısı Pipeline veya Build yürütme sayısına göre tahmin edilmemeli, derleme günlükleri ve gerçek imza çıktıları doğrulanarak onaylanmalıdır.

Daha fazla kural için referans materyallere bakın.

Zaman Damgası

Resmi olarak yayınlanan yazılımların genellikle güvenilir bir zaman damgası eklenmesi önerilir.

GitHub Actions, Electron Builder ve Advanced Installer entegrasyonları RFC 3161 zaman damgasını kullanabilir, örneğin:

http://timestamp.acs.microsoft.com

Zaman damgası yeni bir kod imzalama işlemi olarak sayılmaz ve kod imzalama sayısını ayrıca artırmaz.

Farklı TSA protokollerinin destekleri ve kullanım sınırlamaları için lütfen referans materyallerine bakın.

Kimlik Bilgisi Güvenliği

Otomatik ortamlarda özellikle korunması gerekenler:

Access Key
Access Secret
Cert Code

Access Secret, Secret olarak yönetilmeli ve şu şekilde yapılmamalıdır:

Git deposuna gönderilmemeli.
Açık Workflow içine düz metin olarak yazılmamalı.
Derleme günlüklerine çıktı olarak verilmemeli.
Açık Docker imajlarına yazılmamalı.
Güvenli olmayan yollarla üçüncü taraf derleme sistemlerine iletilmemeli.

GitHub Actions için önerilen kullanım şu şekildedir:

GitHub Actions Secrets

Diğer CI/CD sistemleri, kendi Secret, Credential veya Variable yönetim mekanizmalarını kullanmalıdır.

Nasıl Seçilir

Senaryo	Önerilen Yöntem
GitHub Actions Workflow	GitHub Actions
Electron uygulama derlemesi	Electron Builder
MSI / EXE kurulum paketi oluşturma	Advanced Installer
Normal Shell / PowerShell otomasyonu	SignTool CLI
Windows yazılımının KSP'yi yerel olarak desteklemesi	Windows Provider
Kendi imzalama sürecini geliştirme	API entegrasyonu

Derleme sistemi komut satırı programını doğrudan çağırabiliyorsa SignTool CLI kullanılabilir; araç zaten standart bir Windows KSP/CSP arayüzü sağlıyorsa, öncelikle ilgili Windows Provider entegrasyon yöntemi kullanılmalıdır.

GitHub Actions​

GitHub Secrets Hazırlama​

Temel Yapılandırma​

Birden Fazla Dosyayı İmzalama​

Tam Yapılandırma​

Tam Workflow Örneği​

Çok Platformlu Runner​

Dry Run​

Electron Builder​

Ön Koşullar​

Kimlik Bilgilerini Yapılandırma​

Electron Builder'ı Yapılandırma​

Özel imzalama işlevi​

Yapıyı Çalıştırma​

Advanced Installer​

Ön Koşullar​

Özel İmza Aracını Yapılandırma​

SignTool Parametre Örneği​

Yapılandırma​

İmza Sayısı​

İmza Sayısı​

Zaman Damgası​

Kimlik Bilgisi Güvenliği​

Nasıl Seçilir​

GitHub Actions

GitHub Secrets Hazırlama

Temel Yapılandırma

Birden Fazla Dosyayı İmzalama

Tam Yapılandırma

Tam Workflow Örneği

Çok Platformlu Runner

Dry Run

Electron Builder

Ön Koşullar

Kimlik Bilgilerini Yapılandırma

Electron Builder'ı Yapılandırma

Özel imzalama işlevi

Yapıyı Çalıştırma

Advanced Installer

Ön Koşullar

Özel İmza Aracını Yapılandırma

SignTool Parametre Örneği

Yapılandırma

İmza Sayısı

İmza Sayısı

Zaman Damgası

Kimlik Bilgisi Güvenliği

Nasıl Seçilir