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 kịch bản 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ụ build, 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 mà công cụ build cung cấp.

GitHub Actions

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

ssltrus-official/code-sign-action

Mã nguồn và thông tin phiên bản xem tại ssltrus-official/code-sign-action.Cách sử dụng ổn định hiện tại dùng thẻ phiên bản chính @v1.

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

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

Chuẩn bị GitHub Secrets

Khuyến nghị lưu chứng chỉ 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ố hiệu 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	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ủ tem thời gian RFC 3161; truyền giá trị rỗng có thể tắt tem thời gian
description	Không	-	Mô tả chương trình được ghi vào chữ ký Authenticode
description-url	Không	-	URL chương trình được ghi vào chữ ký Authenticode

Ví dụ về Workflow hoàn chỉnh

Dưới đây là ví dụ về việc 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 cho các tệp được hỗ trợ.

Chạy thử

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, từ đó tự động hoàn tất ký các 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ý mã từ xa sslTrus.
• Đã lấy được Access Key và Access Secret.
• Đã lấy được số hiệu chứng chỉ ký mã.
• 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 máy khách sslTrus.

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

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 của Electron, sau đó được truyền cho SignTool CLI.

Cấu hình Electron Builder

在：

electron-builder.mjs

hoặc trong tệp cấu hình Electron Builder thực tế mà dự án 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 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ì ghép nối lệnh Shell hoàn chỉnh, nhằm giảm thiểu các vấn đề về thoát đườ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 cấu hình xong, hãy chạy Electron Builder bình thường:

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

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

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ể sử dụng tính năng công cụ ký tùy chỉnh của Advanced Installer để gọi sslTrus SignTool CLI, giúp 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 ứng dụng sslTrus.
• Access Key.
• Access Secret.
• Số hiệu chứng chỉ.
• Dự án Advanced Installer đã được cấu hình hoàn tất.

Định 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ã, chọn công cụ ký là:

Custom

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

Ví dụ:

C:\Tools\sslTrus\signtool.exe

Các tham số tùy chỉnh cần được gọi:

sign

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

Nên ưu tiên cung cấp Access Key và Access Secret qua các phương thức an toàn, tránh lưu Access Secret có hiệu lực dài hạn 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 chữ ký tương ứng tương tự như sau:

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ế nên được truyền vào bởi cơ chế công cụ ký tùy chỉnh của nó, không cố định thành app.exe 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, bạn cần đồng thời kiểm tra 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 ở giai đoạn tương ứng.

Sau khi cấu hình xong, bạn có thể kiểm tra trên trang chữ ký số của Advanced Installer:

Files configured for signing

Nhờ đó 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 từng tệp trong một lần xây dựng gói cài đặt.

Ví dụ:

Tệp	Chữ 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 artifact, vì vậy số lần ký cần được đặc biệt lưu ý.

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òn 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 đó, số lần ký cần được xác nhận dựa trên nhật ký build và các sản phẩm ký thực tế, thay vì ước tính theo số lần thực thi 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 được phát hành chính thức thường được khuyến nghị thêm tem thời gian tin cậy.

GitHub Actions, Electron Builder và tích hợp Advanced Installer đều có thể sử dụng tem 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ã một cách 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à giới hạn 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 phải được quản lý dưới dạng 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 nên 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	Phương pháp 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 gốc	Windows Provider
Tự phát triển quy trình ký	Tích hợp API

Nếu hệ thống build 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, thì ưu tiên sử dụng phương thức tích hợp Windows Provider tương ứng.