CI/CD ve Derleme Araçları

sslTrus uzak 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 gerçekleştirilir.

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

GitHub Actions
Electron Builder
Advanced Installer

Derleme aracının yeteneklerine bağlı olarak, doğrudan sslTrus GitHub Action kullanılabilir, SignTool CLI çağrılabilir veya derleme aracının sağladığı özel imzalama arayüzü aracılığıyla entegrasyon tamamlanabilir.

GitHub Actions

sslTrus resmi GitHub Action sağlar:

ssltrus-official/code-sign-action

GitHub Actions Workflow'da derleme çıktıları üzerinde doğrudan uzaktan kod imzalama gerçekleştirebilirsiniz.

Action, imzalamayı tamamlamak için sslTrus uzaktan kod imzalama hizmetini çağırır 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

İmzalama başarılı olduktan sonra, build/app.exe doğrudan imzalanan dosyayla değiştirilecektir.

Birden fazla dosyayı imzalama

files birden fazla dosyayı çok satırlı olarak yapılandırmayı 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

Yolları virgülle ayırarak da belirtebilirsiniz.

Yinelenen 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 sertifikası 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ı kullanarak test imzası gerçekleştir
`timestamp-rfc3161`	Hayır	`auto`	RFC 3161 zaman damgası sunucusu
`description`	Hayır	-	Authenticode imzasına yazılacak program açıklaması
`description-url`	Hayır	-	Authenticode imzasına yazılacak program URL'si

Eksiksiz Workflow Örneği

Aşağıda, Windows Runner'da derleyen, imzalayan ve derleme çıktılarını yükleyen bir örnek yer almaktadır:

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

İmzalama adımının şuraya yerleştirilmesi önerilir:

Derleme → Paketleme → Kod imzalama → Yayınlama

Akıştaki yayımlama 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ğrulamanız gerekiyorsa şunu etkinleştirebilirsiniz:

dry-run: true

Bu mod, yerel test sertifikası 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ştirir, bu nedenle bunu dosyaları hiç değiştirmeyen bir önizleme modu olarak anlamayın.

Electron Builder

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

Tipik akış:

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

Ön Koşullar

Başlamadan önce aşağıdakilere ihtiyacınız vardır:

Kullanılabilir bir sslTrus uzaktan kod imzalama hizmetiniz olmalıdır.
Access Key ve Access Secret edinilmiş olmalıdır.
Kod imzalama sertifika numarası edinilmiş olmalıdır.
Electron projesi electron-builder ile derlenmiş olmalıdır.
Derleme ortamı sslTrus SignTool CLI'yi çalıştırabilmeli; bu araç 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 imzalama betiği tarafından okunur ve ardından SignTool CLI'ye aktarılır.

Electron Builder'ı Yapılandırma

Şurada:

electron-builder.mjs

Veya projenin gerçekte kullandığı Electron Builder yapılandırma dosyasında, Windows için özel bir imzalama fonksiyonu ayarlayın:

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

Burada win.sign, Electron Builder'ın resmi olarak sağladığı özel imzalama giriş noktasıdır; ayrıntılı açıklama için Electron Builder Windows kod imzalama belgelerine bakın.

customSign

sslTrus SignTool CLI'sini ç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çlerin tam Shell komutunu birleştirmek yerine parametre dizisi kullanılarak çağrılması önerilir; bu, yol kaçış karakterleri ve özel karakter işleme sorunlarını azaltır.

Electron Builder, signingHashAlgorithms içindeki her karma algoritması için imzalama işlevini ayrı ayrı çağırır. Yukarıdaki örnekte yalnızca SHA-256 etkinleştirildiğinden her dosya için bir kez çağrılır.

Derlemeyi Ç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ı imzalaması gerektiğinde customSign'i otomatik olarak ç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, "bir Electron paketlemesi yalnızca bir imzalama üretir" şeklinde basitçe anlaşılmamalıdır.

Gerçek imzalama sayısı, yapı sürecinde kaç dosyanın uzak imzalama gerçekleştirdiğine bağlıdır.

Advanced Installer

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

Advanced Installer'ın özel imzalama aracı işlevi aracılığıyla sslTrus SignTool CLI çağrılarak MSI, EXE, CAB gibi yapı çıktılarının paketleme sürecinde otomatik olarak uzak kod imzalama tamamlaması sağlanabilir.

Ö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 İmzalama Aracını Yapılandırma

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

Digital Signature

Yapılandırma sayfası.

Kod imzalama etkinleştirildikten sonra imzalama aracını şu şekilde seçin:

Custom

SSL imzalama aracı yolunu sslTrus SignTool CLI yürütülebilir dosyası olarak ayarlayın.

Örneğin:

C:\Tools\sslTrus\signtool.exe

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

sign

Alt komut ve istemciye şunları iletin:

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

Access Key ve Access Secret bilgilerini öncelikle güvenli bir yöntemle sağlamanız ve uzun süre geçerli Access Secret değerini herkese açık proje dosyalarında düz metin olarak saklamaktan kaçınmanız önerilir.

SignTool parametre örneği

İlgili imzalama 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'da, gerçek dosya yolu kendi özel imzalama aracı mekanizması tarafından iletilmelidir; örnekteki app.exe olarak sabitlenmemelidir.

Derleme Yapılandırması

Advanced Installer ile kurulum paketi içindeki dosyaları otomatik olarak imzalıyorsanız, derleme ve sıkıştırma yöntemini de kontrol etmeniz gerekir.

Projenin gerçek yapılandırmasına bağlı olarak, bazı CAB arşivleme yöntemleri özel imzalama sürecini etkileyebilir; son olarak imzalanması gereken dosyaların ilgili aşamada çağrılabildiğinden emin olunmalıdır.

Yapılandırma tamamlandıktan sonra, Advanced Installer'ın dijital imza sayfasında kontrol edebilirsiniz:

Files configured for signing

Böylece, derleme sürecinde hangi dosyaların imzalanacağı doğrulanır.

İmzalama Sayısı

Advanced Installer, tek bir kurulum paketi derleme sürecinde 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

Bu nedenle:

一次构建 ≠ 一次签名

Gerçek uzaktan imzalanan dosya veya imza eylemi sayısına göre hesaplanmalıdır.

İmza sayısı

CI/CD ve derleme araçları genellikle birden fazla çıktıyı otomatik olarak işlediğinden, imza sayısına özellikle dikkat edilmelidir.

Temel ilkeler:

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

Örneğin:

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

Üç dosya da başarıyla imzalanırsa:

合计 = 3 次

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

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

Bu nedenle imza sayısı, Pipeline veya Build yürütme sayısına göre tahmin edilmek yerine derleme günlüklerine ve gerçek imzalı ürünlere göre doğrulanmalıdır.

Daha fazla kural için Referanslara bakın.

Zaman Damgası

Resmi olarak yayımlanan yazılımlar için genellikle güvenilir zaman damgası eklenmesi önerilir.

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

http://timestamp.acs.microsoft.com

Zaman damgası yeni bir kod imzalama işlemi değildir ve kod imzalama sayısını ayrıca artırmaz.

Farklı TSA'ların protokol desteği ve kullanım kısıtlamaları için lütfen referans materyallerine bakın.

Kimlik Bilgisi Güvenliği

Otomasyon ortamında özellikle korunması gerekenler:

Access Key
Access Secret
Cert Code

Access Secret gizli anahtar olarak yönetilmelidir ve şunlar yapılmamalıdır:

Git deposuna gönderilmemelidir.
Herkese açık Workflow içinde düz metin olarak yazılmamalıdır.
Derleme günlüklerine çıktı olarak verilmemelidir.
Herkese açık Docker imajlarına yazılmamalıdır.
Güvenli olmayan yollarla üçüncü taraf derleme sistemlerine aktarılmamalıdır.

GitHub Actions için önerilenler:

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
Genel Shell / PowerShell otomasyonu	SignTool CLI
Windows yazılımı yerel KSP desteği	Windows Provider
Kendi imzalama sürecinizi geliştirme	API entegrasyonu

Derleme sistemi komut satırı programlarını doğrudan çağırabiliyorsa SignTool CLI kullanılabilir; araç zaten standart Windows KSP/CSP arayüzü sağlıyorsa, ilgili Windows Provider entegrasyon yöntemi öncelikli olarak tercih edilir.

GitHub Actions​

GitHub Secrets'ı Hazırlama​

Temel Yapılandırma​

Birden fazla dosyayı imzalama​

Tam yapılandırma​

Eksiksiz 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​

Derlemeyi Çalıştırma​

Advanced Installer​

Ön Koşullar​

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

SignTool parametre örneği​

Derleme Yapılandırması​

İmzalama 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ı imzalama

Tam yapılandırma

Eksiksiz 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

Derlemeyi Çalıştırma

Advanced Installer

Ön Koşullar

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

SignTool parametre örneği

Derleme Yapılandırması

İmzalama Sayısı

İmza sayısı

Zaman Damgası

Kimlik Bilgisi Güvenliği

Nasıl seçilir