CI/CD และเครื่องมือบิลด์

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

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

GitHub Actions
Electron Builder
Advanced Installer

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

GitHub Actions

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

ssltrus-official/code-sign-action

ดูซอร์สโค้ดและคำอธิบายเวอร์ชันได้ที่ ssltrus-official/code-sign-action วิธีใช้งานที่เสถียรในปัจจุบันใช้แท็กเวอร์ชันหลัก @v1

สามารถลงนามโค้ดระยะไกลให้กับไฟล์ที่ได้จากการบิลด์ได้โดยตรงใน 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`	เซิร์ฟเวอร์ประทับเวลา RFC 3161; ส่งค่าว่างเพื่อปิดใช้งานการประทับเวลา
`description`	ไม่ใช่	-	เขียนคำอธิบายโปรแกรมลงในลายเซ็น Authenticode
`description-url`	ไม่ใช่	-	เขียน URL ของโปรแกรมลงในลายเซ็น Authenticode

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

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

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

สามารถส่งข้อมูลรับรองไปยังสคริปต์ 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 ดังนั้นแต่ละไฟล์จึงเรียกใช้หนึ่งครั้ง

ดำเนินการบิลด์

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

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

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

การ build 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
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

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

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

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

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

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

ดังนั้น:

一次构建 ≠ 一次签名

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

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

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

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

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

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

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

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

合计 = 3 次

เครื่องมือ build อย่าง Electron Builder และ Advanced Installer อาจสร้างและลงนามไฟล์ต่อไปนี้โดยอัตโนมัติ:

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

ดังนั้น ควรยืนยันจำนวนครั้งในการลงนามจากบันทึกการ build และไฟล์ที่ลงนามจริง ไม่ใช่ประมาณจากจำนวนครั้งที่ 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 ที่สอดคล้องกันเป็นลำดับแรก

GitHub Actions​

เตรียม GitHub Secrets​

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

การลงนามหลายไฟล์​

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

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

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

Dry Run​

Electron Builder​

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

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

กำหนดค่า Electron Builder​

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

ดำเนินการบิลด์​

Advanced Installer​

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

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

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

การกำหนดค่าการ build​

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

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

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

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

วิธีเลือก​

GitHub Actions

เตรียม GitHub Secrets

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

การลงนามหลายไฟล์

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

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

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

Dry Run

Electron Builder

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

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

กำหนดค่า Electron Builder

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

ดำเนินการบิลด์

Advanced Installer

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

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

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

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

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

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

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

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

วิธีเลือก