CI/CD và Công cụ Build

Dịch vụ ký mã từ xa sslTrus có thể được tích hợp vào quy trình CI/CD, xây dựng ứng dụng và tạo gói cài đặt, tự động thực hiện ký mã cho sản phẩm phát hành sau khi biên dịch hoặc đóng gói hoàn tất.

Các tình huống tích hợp điển hình hiện được hỗ trợ bao gồm:

• GitHub Actions
• Electron Builder
• Advanced Installer

Tùy theo khả năng của công cụ xây dựng, bạn có thể trực tiếp sử dụng sslTrus GitHub Action, gọi SignTool CLI, hoặc hoàn tất tích hợp thông qua giao diện ký tùy chỉnh do công cụ xây dựng cung cấp.

GitHub Actions

sslTrus cung cấp GitHub Action chính thức:

ssltrus-official/code-sign-action

Bạn có thể thực hiện ký mã từ xa trực tiếp trên các artifact build trong GitHub Actions Workflow.

Action sẽ gọi dịch vụ ký mã từ xa sslTrus để hoàn tất việc ký và trực tiếp cập nhật các tệp được chỉ định, tương thích với Linux, macOS và Windows Runner.

Chuẩn bị GitHub Secrets

Bạn nên lưu thông tin xác thực ký mã từ xa vào GitHub Actions Secrets:

SSLTRUS_ACCESS_KEY
SSLTRUS_ACCESS_SECRET
SSLTRUS_CERT_CODE

Không ghi trực tiếp Access Secret vào tệp Workflow.

Cấu hình cơ bản

- 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

Sau khi ký thành công, build/app.exe sẽ được thay thế trực tiếp bằng tệp đã ký.

Ký nhiều tệp

files hỗ trợ cấu hình nhiều tệp bằng nhiều dòng:

- 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

Bạn cũng có thể sử dụng dấu phẩy để phân tách các đường dẫn tệp.

Các đường dẫn tệp trùng lặp sẽ chỉ được xử lý một lần.

Cấu hình đầy đủ

- 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

Các tham số chính:

Tham số	Bắt buộc	Giá trị mặc định	Mô tả
access-key	Có	-	sslTrus Access Key
access-secret	Có	-	sslTrus Access Secret
cert-code	Có	-	Số chứng chỉ ký mã
files	Có	-	Đường dẫn tệp cần ký
nicsrs	Không	false	Có sử dụng dịch vụ NICSRS hay không
dry-run	Không	false	Sử dụng chứng chỉ kiểm thử cục bộ để thực hiện ký kiểm thử
timestamp-rfc3161	Không	auto	Máy chủ dấu thời gian RFC 3161
description	Không	-	Ghi mô tả chương trình của chữ ký Authenticode
description-url	Không	-	Ghi URL chương trình của chữ ký Authenticode

Ví dụ Workflow đầy đủ

Dưới đây là ví dụ biên dịch, ký và tải lên sản phẩm build trong Windows Runner:

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

Khuyến nghị đặt bước ký tại:

Biên dịch → Đóng gói → Ký mã → Phát hành

trước bước phát hành trong quy trình.

Runner đa nền tảng

GitHub Action có thể được gọi trong các Runner khác nhau:

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

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

Do đó, ngay cả khi tác vụ build chạy trên Linux hoặc macOS, bạn vẫn có thể sử dụng cùng một Action để hoàn tất việc ký từ xa các tệp được hỗ trợ.

Dry Run

Nếu cần xác minh Workflow và logic xử lý tệp, bạn có thể bật:

dry-run: true

Chế độ này sử dụng chứng chỉ kiểm thử cục bộ và không gọi dịch vụ ký mã từ xa.

Ví dụ:

- 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 vẫn sẽ sửa đổi tệp đích, vì vậy đừng hiểu đây là chế độ xem trước hoàn toàn không sửa đổi tệp.

Electron Builder

Electron Builder có thể gọi sslTrus SignTool CLI thông qua hàm ký tùy chỉnh, nhờ đó tự động hoàn tất việc ký tệp thực thi Windows và gói cài đặt trong quá trình build ứng dụng Electron.

Quy trình điển hình:

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

Điều kiện tiên quyết

Trước khi bắt đầu, bạn cần:

• Đã có sẵn dịch vụ ký code từ xa sslTrus.
• Đã nhận được Access Key và Access Secret.
• Đã nhận được số chứng chỉ ký code.
• Dự án Electron sử dụng electron-builder để build.
• Môi trường build có thể thực thi sslTrus SignTool CLI, có thể tải từ trang phát hành sslTrus client.

Cấu hình thông tin xác thực

Bạn có thể truyền thông tin xác thực vào script build thông qua biến môi trường:

Linux và 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"

Các biến này được đọc bởi script ký tùy chỉnh Electron, sau đó được truyền cho SignTool CLI.

Cấu hình Electron Builder

Tại:

electron-builder.mjs

Hoặc trong tệp cấu hình Electron Builder mà dự án thực tế sử dụng, hãy thiết lập hàm ký tùy chỉnh cho Windows:

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

Trong đó, win.sign là điểm vào ký mã tùy chỉnh chính thức do Electron Builder cung cấp. Để biết thêm chi tiết, vui lòng tham khảo Tài liệu ký mã Windows của Electron Builder.

customSign

Chịu trách nhiệm gọi sslTrus SignTool CLI.

Hàm ký tùy chỉnh

Ví dụ:

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',
    },
  );
}

Nên sử dụng mảng tham số để gọi tiến trình con thay vì nối chuỗi lệnh Shell hoàn chỉnh, nhằm giảm thiểu các vấn đề về escape đường dẫn và xử lý ký tự đặc biệt.

Electron Builder sẽ gọi hàm ký một lần cho mỗi thuật toán băm trong signingHashAlgorithms. Ví dụ trên chỉ bật SHA-256, do đó mỗi tệp được gọi một lần.

Thực hiện build

Sau khi hoàn tất cấu hình, thực thi Electron Builder như bình thường:

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

Khi Electron Builder cần ký một tệp, nó sẽ tự động gọi customSign.

Một lần build Electron có thể ký nhiều tệp, ví dụ:

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

Do đó, không nên hiểu đơn giản rằng "một lần đóng gói Electron chỉ tạo ra một lần ký".

Số lần ký thực tế phụ thuộc vào số lượng tệp thực hiện ký từ xa trong quá trình build.

Advanced Installer

Advanced Installer là công cụ tạo gói cài đặt dựa trên công nghệ Windows Installer.

Có thể gọi sslTrus SignTool CLI thông qua tính năng công cụ ký tùy chỉnh của Advanced Installer, để các sản phẩm build như MSI, EXE, CAB tự động hoàn tất ký mã từ xa trong quá trình đóng gói.

Điều kiện tiên quyết

Cần chuẩn bị:

• sslTrus SignTool CLI, có thể tải xuống từ trang phát hành sslTrus client.
• Access Key.
• Access Secret.
• Số chứng chỉ.
• Dự án Advanced Installer đã được cấu hình hoàn tất.

Cấu hình công cụ ký tùy chỉnh

Mở dự án Advanced Installer:

Digital Signature

Trang cấu hình.

Sau khi bật ký mã, hãy chọn công cụ ký là:

Custom

Đường dẫn công cụ ký được đặt thành tệp thực thi sslTrus SignTool CLI.

Ví dụ:

C:\Tools\sslTrus\signtool.exe

Cần gọi tham số tùy chỉnh:

sign

Các lệnh con và truyền cho máy khách:

• Access Key
• Access Secret
• Cert Code
• Cài đặt chữ ký SHA-2
• Máy chủ dấu thời gian
• Đường dẫn tệp

Bạn nên ưu tiên cung cấp Access Key và Access Secret qua phương thức an toàn, tránh lưu Access Secret có thời hạn dài dưới dạng văn bản thuần túy trong các tệp dự án có thể truy cập công khai.

Ví dụ tham số SignTool

Logic ký tương ứng tương tự như:

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"

Trong Advanced Installer, đường dẫn tệp thực tế phải được truyền vào bởi cơ chế công cụ ký tùy chỉnh của nó, không được cố định thành app.exe như trong ví dụ.

Cấu hình Build

Nếu sử dụng Advanced Installer để tự động ký các tệp bên trong gói cài đặt, cần kiểm tra đồng thời phương thức build và nén.

Tùy theo cấu hình thực tế của dự án, một số phương thức lưu trữ CAB có thể ảnh hưởng đến quy trình ký tùy chỉnh, cần xác nhận rằng tệp cuối cùng cần ký có thể được gọi trong giai đoạn tương ứng.

Sau khi hoàn tất cấu hình, có thể kiểm tra tại trang Digital Signature của Advanced Installer:

Files configured for signing

Nhờ đó, bạn có thể xác nhận những tệp nào sẽ được ký trong quá trình build.

Số lần ký

Advanced Installer có thể ký riêng nhiều tệp trong một lần build gói cài đặt.

Ví dụ:

Tệp	Ký
app.exe	1 lần
helper.dll	1 lần
uninstall.exe	1 lần
installer.msi	1 lần
Tổng cộng	4 lần

Do đó:

一次构建 ≠ 一次签名

Nên tính toán dựa trên số lượng tệp hoặc hành động ký từ xa thực tế đã hoàn thành.

Số lần ký

Các công cụ CI/CD và build thường tự động xử lý nhiều sản phẩm đầu ra, vì vậy số lần ký cần được đặc biệt chú ý.

Nguyên tắc cơ bản:

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

Ví dụ:

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

Nếu cả ba tệp đều được ký thành công:

合计 = 3 次

Các công cụ build như Electron Builder và Advanced Installer cũng có thể tự động tạo và ký:

• Chương trình chính.
• DLL.
• Chương trình cập nhật.
• Chương trình gỡ cài đặt.
• MSI.
• Gói cài đặt EXE.
• Các tệp thực thi phụ trợ khác.

Do đó, nên xác nhận số lần ký dựa trên nhật ký build và sản phẩm ký thực tế, thay vì ước tính theo số lần thực thi của Pipeline hoặc Build.

Để biết thêm quy tắc, vui lòng tham khảo tài liệu tham khảo.

Dấu thời gian

Phần mềm phát hành chính thức thường được khuyến nghị thêm dấu thời gian tin cậy.

Tích hợp GitHub Actions, Electron Builder và Advanced Installer đều có thể sử dụng dấu thời gian RFC 3161, ví dụ:

http://timestamp.acs.microsoft.com

Dấu thời gian không thuộc thao tác ký mã mới và không làm tăng số lần ký mã riêng biệt.

Vui lòng tham khảo Tài liệu tham khảo để biết hỗ trợ giao thức và hạn chế sử dụng của các TSA khác nhau.

Bảo mật thông tin xác thực

Trong môi trường tự động hóa, cần đặc biệt bảo vệ:

Access Key
Access Secret
Cert Code

Trong đó Access Secret nên được quản lý như một Secret, không nên:

• Commit vào kho lưu trữ Git.
• Ghi dưới dạng văn bản thuần túy vào Workflow công khai.
• Xuất ra nhật ký build.
• Ghi vào Docker image công khai.
• Truyền cho hệ thống build bên thứ ba theo cách không an toàn.

GitHub Actions khuyến nghị sử dụng:

GitHub Actions Secrets

Các hệ thống CI/CD khác nên sử dụng cơ chế quản lý Secret, Credential hoặc Variable tương ứng của chúng.

Cách lựa chọn

Tình huống	Cách được khuyến nghị
GitHub Actions Workflow	GitHub Actions
Xây dựng ứng dụng Electron	Electron Builder
Tạo gói cài đặt MSI / EXE	Advanced Installer
Tự động hóa Shell / PowerShell thông thường	SignTool CLI
Phần mềm Windows hỗ trợ KSP nguyên bản	Windows Provider
Tự phát triển quy trình ký	Tích hợp API

Nếu hệ thống xây dựng có thể gọi trực tiếp chương trình dòng lệnh, bạn có thể sử dụng SignTool CLI; nếu công cụ đã cung cấp giao diện Windows KSP/CSP tiêu chuẩn, hãy ưu tiên sử dụng phương thức tích hợp Windows Provider tương ứng.