CI/CD และเครื่องมือสร้าง

บริการลงนามโค้ดระยะไกลของ sslTrus สามารถผสานรวมเข้ากับกระบวนการ CI/CD การสร้างแอปพลิเคชัน และการจัดทำแพ็กเกจติดตั้ง เพื่อลงนามโค้ดให้กับไฟล์ที่เผยแพร่โดยอัตโนมัติหลังจากการคอมไพล์หรือแพ็กเกจเสร็จสิ้น

สถานการณ์การผสานรวมทั่วไปที่รองรับในปัจจุบัน ได้แก่:

• GitHub Actions
• Electron Builder
• Advanced Installer

คุณสามารถใช้ sslTrus GitHub Action โดยตรง เรียกใช้ SignTool CLI หรือผสานรวมผ่านอินเทอร์เฟซการลงนามแบบกำหนดเองที่เครื่องมือสร้างมีให้ ทั้งนี้ขึ้นอยู่กับความสามารถของเครื่องมือสร้าง

GitHub Actions

sslTrus มี GitHub Action อย่างเป็นทางการ:

ssltrus-official/code-sign-action

สามารถดำเนินการลงนามโค้ดระยะไกลบนไฟล์ผลลัพธ์จากการ build ได้โดยตรงใน GitHub Actions Workflow

Action จะเรียกใช้บริการลงนามโค้ดระยะไกลของ sslTrus เพื่อทำการลงนามให้เสร็จสมบูรณ์ และอัปเดตไฟล์ที่ระบุโดยตรง เหมาะสำหรับ Linux, macOS และ Windows Runner

การเตรียม GitHub Secrets

แนะนำให้บันทึกข้อมูลรับรองการลงนามโค้ดระยะไกลไว้ใน GitHub Actions Secrets:

SSLTRUS_ACCESS_KEY
SSLTRUS_ACCESS_SECRET
SSLTRUS_CERT_CODE

อย่าเขียน Access Secret ลงในไฟล์ Workflow โดยตรง

การกำหนดค่าพื้นฐาน

- 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/app.exe จะถูกแทนที่ด้วยไฟล์ที่เซ็นชื่อแล้วโดยตรง

การเซ็นชื่อหลายไฟล์

files รองรับการกำหนดค่าหลายไฟล์โดยใช้หลายบรรทัด:

- 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

นอกจากนี้ยังสามารถใช้เครื่องหมายจุลภาคคั่นเส้นทางไฟล์ได้

เส้นทางไฟล์ที่ซ้ำกันจะถูกประมวลผลเพียงครั้งเดียว

การกำหนดค่าแบบสมบูรณ์

- 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

พารามิเตอร์หลัก:

พารามิเตอร์	จำเป็น	ค่าเริ่มต้น	คำอธิบาย
access-key	ใช่	-	sslTrus Access Key
access-secret	ใช่	-	sslTrus Access Secret
cert-code	ใช่	-	หมายเลขใบรับรองการลงนามโค้ด
files	ใช่	-	พาธไฟล์ที่ต้องการลงนาม
nicsrs	ไม่ใช่	false	ใช้บริการ NICSRS หรือไม่
dry-run	ไม่ใช่	false	ใช้ใบรับรองทดสอบภายในเครื่องเพื่อทำการลงนามทดสอบ
timestamp-rfc3161	ไม่ใช่	auto	เซิร์ฟเวอร์ timestamp RFC 3161
description	ไม่ใช่	-	เขียนคำอธิบายโปรแกรมลงในลายเซ็น Authenticode
description-url	ไม่ใช่	-	เขียน URL ของโปรแกรมลงในลายเซ็น Authenticode

ตัวอย่าง Workflow แบบสมบูรณ์

ต่อไปนี้เป็นตัวอย่างการคอมไพล์ ลงลายเซ็น และอัปโหลด build artifact ใน 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

แนะนำให้วางขั้นตอนการลงนามไว้ที่:

คอมไพล์ → แพ็กเกจ → เซ็นโค้ด → เผยแพร่

ก่อนขั้นตอนเผยแพร่ในเวิร์กโฟลว์

Runner หลายแพลตฟอร์ม

GitHub Action สามารถเรียกใช้ใน Runner ที่แตกต่างกันได้:

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

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

ดังนั้น แม้ว่างาน build จะทำงานบน Linux หรือ macOS ก็สามารถใช้ Action เดียวกันเพื่อทำการเซ็นระยะไกลสำหรับไฟล์ที่รองรับได้

Dry Run

หากต้องการตรวจสอบ Workflow และตรรกะการประมวลผลไฟล์ สามารถเปิดใช้งานได้:

dry-run: true

โหมดนี้ใช้ใบรับรองทดสอบในเครื่อง โดยไม่เรียกใช้บริการลงนามโค้ดระยะไกล

ตัวอย่างเช่น:

- 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 ยังคงแก้ไขไฟล์ปลายทาง ดังนั้นอย่าเข้าใจผิดว่าเป็นโหมดพรีวิวที่ไม่แก้ไขไฟล์เด็ดขาด

Electron Builder

Electron Builder สามารถเรียก sslTrus SignTool CLI ผ่านฟังก์ชันการลงนามแบบกำหนดเอง เพื่อทำการลงนามไฟล์ปฏิบัติการ Windows และแพ็คเกจติดตั้งโดยอัตโนมัติในระหว่างกระบวนการ build แอปพลิเคชัน Electron

ขั้นตอนทั่วไป:

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

ข้อกำหนดเบื้องต้น

ก่อนเริ่มต้น จำเป็นต้องมี:

• มีบริการลงนามโค้ดระยะไกล sslTrus ที่พร้อมใช้งานแล้ว
• ได้รับ Access Key และ Access Secret แล้ว
• ได้รับหมายเลขใบรับรองการลงนามโค้ดแล้ว
• โปรเจกต์ Electron ใช้ electron-builder ในการ build
• สภาพแวดล้อมการ build สามารถรัน sslTrus SignTool CLI ได้ ซึ่งดาวน์โหลดได้จาก หน้าปล่อย sslTrus client

การกำหนดค่าข้อมูลรับรอง

สามารถส่งข้อมูลรับรองให้กับสคริปต์ build ผ่านตัวแปรสภาพแวดล้อม:

Linux และ 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"

ตัวแปรเหล่านี้จะถูกอ่านโดยสคริปต์ลงนามแบบกำหนดเองของ Electron จากนั้นจึงส่งต่อไปยัง SignTool CLI

กำหนดค่า Electron Builder

ใน:

electron-builder.mjs

หรือในไฟล์การกำหนดค่า Electron Builder ที่โปรเจกต์ใช้งานจริง ให้ตั้งค่าฟังก์ชันการเซ็นแบบกำหนดเองสำหรับ Windows:

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

โดยที่ win.sign เป็นจุดเข้าสำหรับการลงนามแบบกำหนดเองที่ให้บริการอย่างเป็นทางการโดย Electron Builder สำหรับรายละเอียดเพิ่มเติม โปรดดู เอกสารการลงนามโค้ด Windows ของ Electron Builder

customSign

รับผิดชอบในการเรียกใช้ sslTrus SignTool CLI

ฟังก์ชันการลงนามแบบกำหนดเอง

ตัวอย่าง:

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

ขอแนะนำให้ใช้พารามิเตอร์อาร์เรย์ในการเรียกใช้โปรเซสย่อย แทนการต่อคำสั่ง Shell แบบเต็ม เพื่อลดปัญหาการ escape พาธและการจัดการอักขระพิเศษ

Electron Builder จะเรียกใช้ฟังก์ชันลายเซ็นหนึ่งครั้งต่อหนึ่งอัลกอริทึมแฮชตาม signingHashAlgorithms ตัวอย่างด้านบนเปิดใช้งานเฉพาะ SHA-256 ดังนั้นจึงเรียกใช้หนึ่งครั้งต่อไฟล์

ดำเนินการ build

หลังการกำหนดค่าเสร็จสิ้น ให้รัน Electron Builder ตามปกติ:

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

เมื่อ Electron Builder จำเป็นต้องเซ็นชื่อไฟล์ จะเรียกใช้ customSign โดยอัตโนมัติ

การบิลด์ Electron หนึ่งครั้งอาจมีการเซ็นชื่อหลายไฟล์ เช่น:

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

ดังนั้น จึงไม่ควรเข้าใจง่ายๆ ว่า "การแพ็ก Electron หนึ่งครั้งจะมีการลงนามเพียงครั้งเดียว"

จำนวนครั้งในการลงนามจริงขึ้นอยู่กับว่ามีไฟล์จำนวนเท่าใดที่ดำเนินการลงนามระยะไกลในระหว่างกระบวนการ build

Advanced Installer

Advanced Installer เป็นเครื่องมือสร้างแพ็กเกจติดตั้งที่อิงตามเทคโนโลยี Windows Installer

สามารถเรียกใช้ sslTrus SignTool CLI ผ่านฟีเจอร์เครื่องมือลงนามแบบกำหนดเองของ Advanced Installer เพื่อให้ผลิตภัณฑ์ที่ได้จาก build เช่น MSI, EXE, CAB ดำเนินการลงนามโค้ดระยะไกลโดยอัตโนมัติในระหว่างกระบวนการแพ็ก

ข้อกำหนดเบื้องต้น

สิ่งที่ต้องเตรียม:

• sslTrus SignTool CLI สามารถดาวน์โหลดได้จาก หน้าเผยแพร่ sslTrus client
• Access Key
• Access Secret
• หมายเลขใบรับรอง
• โปรเจกต์ Advanced Installer ที่กำหนดค่าเสร็จแล้ว

การกำหนดค่าเครื่องมือลงนามแบบกำหนดเอง

เปิดโปรเจกต์ Advanced Installer ที่:

Digital Signature

หน้าการกำหนดค่า

หลังจากเปิดใช้งานการลงนามโค้ดแล้ว ให้เลือกเครื่องมือการลงนามเป็น:

Custom

ตั้งค่าเส้นทางเครื่องมือลงนามเป็นไฟล์ปฏิบัติการ sslTrus SignTool CLI

ตัวอย่างเช่น:

C:\Tools\sslTrus\signtool.exe

จำเป็นต้องเรียกใช้พารามิเตอร์ที่กำหนดเอง:

sign

คำสั่งย่อย และส่งต่อไปยังไคลเอนต์:

• Access Key
• Access Secret
• Cert Code
• การตั้งค่าลายเซ็น SHA-2
• เซิร์ฟเวอร์ Timestamp
• เส้นทางไฟล์

แนะนำให้ส่ง Access Key และ Access Secret ผ่านช่องทางที่ปลอดภัยเป็นลำดับแรก หลีกเลี่ยงการบันทึก Access Secret แบบข้อความธรรมดาที่มีอายุการใช้งานยาวนานลงในไฟล์โปรเจกต์ที่สามารถเข้าถึงได้แบบสาธารณะ

ตัวอย่างพารามิเตอร์ SignTool

ตรรกะการลงนามที่เกี่ยวข้องมีลักษณะคล้ายกับ:

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 พาธไฟล์จริงควรถูกส่งเข้ามาผ่านกลไกเครื่องมือลงนามแบบกำหนดเอง ไม่ควรกำหนดตายตัวเป็น app.exe ตามตัวอย่าง

การกำหนดค่าการ Build

หากใช้ Advanced Installer ลงนามไฟล์ภายในแพ็กเกจติดตั้งโดยอัตโนมัติ จำเป็นต้องตรวจสอบทั้งวิธีการ build และการบีบอัด

ตามการกำหนดค่าจริงของโปรเจกต์ วิธีการจัดเก็บแบบ CAB บางรูปแบบอาจส่งผลต่อกระบวนการลงนามแบบกำหนดเอง ควรยืนยันว่าไฟล์ที่ต้องลงนามในขั้นสุดท้ายสามารถถูกเรียกใช้ในขั้นตอนที่เกี่ยวข้องได้

หลังจากกำหนดค่าเสร็จแล้ว สามารถตรวจสอบได้ที่หน้าการลงนามดิจิทัลของ Advanced Installer:

Files configured for signing

เพื่อยืนยันว่าไฟล์ใดจะถูกดำเนินการลงนามในระหว่างกระบวนการ build

จำนวนครั้งในการลงนาม

Advanced Installer อาจดำเนินการลงนามไฟล์หลายไฟล์แยกกันในระหว่างการ build แพ็กเกจติดตั้งหนึ่งครั้ง

ตัวอย่างเช่น:

ไฟล์	การลงนาม
app.exe	1 ครั้ง
helper.dll	1 ครั้ง
uninstall.exe	1 ครั้ง
installer.msi	1 ครั้ง
รวม	4 ครั้ง

ดังนั้น:

一次构建 ≠ 一次签名

ควรคำนวณตามจำนวนไฟล์หรือการดำเนินการเซ็นชื่อที่ทำเสร็จจากระยะไกลจริง

จำนวนครั้งในการเซ็นชื่อ

เครื่องมือ CI/CD และเครื่องมือ build มักจะจัดการอาร์ติแฟกต์หลายรายการโดยอัตโนมัติ ดังนั้นจึงต้องให้ความสำคัญเป็นพิเศษกับจำนวนครั้งในการเซ็นชื่อ

หลักการพื้นฐาน:

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

ตัวอย่างเช่น:

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

หากไฟล์ทั้งสามไฟล์ลงนามสำเร็จ:

合计 = 3 次

Electron Builder และ Advanced Installer รวมถึงเครื่องมือสร้างอื่นๆ อาจสร้างและลงนามโดยอัตโนมัติ:

• โปรแกรมหลัก
• DLL
• โปรแกรมอัปเดต
• โปรแกรมถอนการติดตั้ง
• MSI
• แพ็กเกจติดตั้ง EXE
• ไฟล์ปฏิบัติการเสริมอื่นๆ

ดังนั้น ควรยืนยันจำนวนครั้งของการลงนามตามบันทึกการสร้างและไฟล์ที่ลงนามจริง ไม่ใช่ประมาณจากจำนวนครั้งที่เรียกใช้ Pipeline หรือ Build

สำหรับกฎเพิ่มเติม โปรดดู เอกสารอ้างอิง

การประทับเวลา

ซอฟต์แวร์ที่เผยแพร่อย่างเป็นทางการมักแนะนำให้เพิ่มการประทับเวลาที่เชื่อถือได้

การผสานรวม GitHub Actions, Electron Builder และ Advanced Installer สามารถใช้การประทับเวลา RFC 3161 ได้ เช่น:

http://timestamp.acs.microsoft.com

การประทับเวลาไม่ถือเป็นการดำเนินการลงนามโค้ดใหม่ และไม่เพิ่มจำนวนครั้งการลงนามโค้ดแยกต่างหาก

สำหรับการรองรับโปรโตคอลและข้อจำกัดการใช้งานของ TSA ต่างๆ โปรดดู เอกสารอ้างอิง

ความปลอดภัยของข้อมูลรับรอง

ในสภาพแวดล้อมอัตโนมัติ ควรให้ความสำคัญกับการปกป้อง:

Access Key
Access Secret
Cert Code

โดย Access Secret ควรได้รับการจัดการเป็น Secret และไม่ควร:

• คอมมิตไปยัง Git repository
• เขียนเป็นข้อความธรรมดาใน Workflow สาธารณะ
• แสดงผลในบันทึกการ build
• เขียนลงใน Docker image สาธารณะ
• ส่งต่อไปยังระบบ build ของบุคคลที่สามด้วยวิธีที่ไม่ปลอดภัย

สำหรับ GitHub Actions แนะนำให้ใช้:

GitHub Actions Secrets

ระบบ CI/CD อื่นๆ ควรใช้กลไกการจัดการ Secret, Credential หรือ Variable ที่เกี่ยวข้อง

วิธีเลือก

สถานการณ์	วิธีที่แนะนำ
GitHub Actions Workflow	GitHub Actions
การ build แอป Electron	Electron Builder
การสร้างแพ็กเกจติดตั้ง MSI / EXE	Advanced Installer
ระบบอัตโนมัติ Shell / PowerShell ทั่วไป	SignTool CLI
ซอฟต์แวร์ Windows รองรับ KSP แบบเนทีฟ	Windows Provider
พัฒนากระบวนการลงนามด้วยตนเอง	การผสานรวม API

หากระบบ build สามารถเรียกโปรแกรม command line ได้โดยตรง สามารถใช้ SignTool CLI ได้ หากเครื่องมือมีอินเทอร์เฟซ Windows KSP/CSP มาตรฐานอยู่แล้ว ควรใช้วิธีการผสานรวม Windows Provider ที่เกี่ยวข้องเป็นลำดับแรก