Công cụ khách hàng

sslTrus cung cấp client dòng lệnh và client desktop để kết nối với dịch vụ ký mã từ xa và hoàn tất việc ký tệp.

Trong đó, SignTool CLI phù hợp với các tình huống dòng lệnh, tập lệnh và tự động hóa; người dùng macOS cũng có thể cài đặt và cập nhật SignTool CLI hoặc client desktop thông qua Homebrew.

SignTool CLI

SignTool CLI là client dòng lệnh ký mã từ xa do sslTrus cung cấp, tên tệp thực thi sau khi cài đặt là signtool.

Nó chủ yếu cung cấp các khả năng sau:

Chức năng	Lệnh	Mô tả
Ký tệp	signtool sign	Thực hiện ký mã từ xa cho tệp cục bộ
Hạn mức ký	signtool quota	Truy vấn hạn mức ký còn lại và tổng hạn mức ký của chứng chỉ
Cập nhật client	signtool update	Truy vấn và cài đặt client mới nhất cho nền tảng hiện tại
Windows KSP	signtool ksp	Cài đặt và quản lý Windows Key Storage Provider
Windows CSP	signtool csp	Cài đặt và quản lý Windows Cryptographic Service Provider

KSP và CSP thuộc phương thức tích hợp Windows Provider. Để biết cách sử dụng cụ thể, vui lòng tham khảo Windows Provider.

Tải client

SignTool CLI có thể được tải xuống từ trang phát hành client sslTrus:

Trang phát hành client sslTrus

Trang phát hành cung cấp gói cài đặt client mới nhất cho từng nền tảng. Trong các kịch bản tự động hóa, bạn cũng có thể truy vấn thông tin phiên bản mới nhất hiện tại qua chỉ mục phiên bản latest.json.

Người dùng macOS cũng có thể cài đặt trực tiếp qua Homebrew, xem macOS Homebrew bên dưới.

Xem thông tin client

Sau khi cài đặt xong, bạn có thể chạy:

signtool --help

Xem trợ giúp lệnh.

Xem phiên bản máy khách hiện tại:

signtool --version

Thông tin phiên bản bao gồm phiên bản máy khách, bản sửa đổi build, nền tảng chạy và thời gian build.

Thông tin xác thực truy cập

Trước khi sử dụng dịch vụ ký mã từ xa, bạn cần chuẩn bị:

• Access Key
• Access Secret
• Số chứng chỉ (Cert Code)

Trong đó Access Key và Access Secret dùng để truy cập dịch vụ ký mã từ xa, số chứng chỉ dùng để chỉ định chứng chỉ ký mã thực tế thực hiện ký.

SignTool CLI có thể cung cấp thông tin xác thực qua tham số lệnh hoặc đọc qua biến môi trường:

export ACCESS_KEY="your-access-key"
export ACCESS_SECRET="your-access-secret"

Bạn nên ưu tiên cung cấp Access Secret thông qua biến môi trường, CI/CD Secret hoặc các phương thức quản lý thông tin xác thực an toàn khác.

Không được đưa Access Secret vào:

• Commit lên kho Git.
• Viết vào script công khai.
• Xuất ra nhật ký build.
• Gửi đến hệ thống bên thứ ba không tin cậy.

Địa chỉ dịch vụ từ xa

Theo mặc định, SignTool CLI sử dụng địa chỉ dịch vụ production của sslTrus, không cần cấu hình thêm.

Nếu sử dụng môi trường NICSRS (www.nicsrs.com), cần thêm --address nicsrs vào lệnh:

signtool sign \
  --address nicsrs \
  --cert-code CERT_CODE \
  --file app.exe

signtool quota và signtool update cũng hỗ trợ --address nicsrs.

Chữ ký tệp

Sử dụng signtool sign có thể trực tiếp thực hiện ký mã từ xa đối với tệp cục bộ.

Lệnh ký cơ bản nhất:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe

Nếu đã thiết lập:

ACCESS_KEY
ACCESS_SECRET

SignTool CLI sẽ tự động đọc thông tin xác thực truy cập tương ứng.

Theo mặc định, chữ ký được thực hiện bằng SHA-2.

Chỉ định tệp đầu ra

Theo mặc định, máy khách sẽ không trực tiếp ghi đè tệp gốc.

Có thể chỉ định tệp đầu ra sau khi ký thông qua --out:

signtool sign \
  --cert-code CERT_CODE \
  --file app-unsigned.exe \
  --out app-signed.exe

Ghi đè tệp gốc

Nếu cần sửa đổi trực tiếp tệp gốc, bạn có thể sử dụng:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --override=true

Sau khi bật --override, kết quả ký sẽ được ghi trực tiếp lại vào tệp đầu vào.

Khi sử dụng trong môi trường build tự động, cần xác nhận các bước tiếp theo cần tệp gốc hay tệp đã ký.

Chỉ định mô tả chương trình

Có thể ghi mô tả chương trình và URL vào chữ ký Authenticode:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --desc "Example Application" \
  --url "https://example.com"

SHA-1 và SHA-2

SHA-2 được bật theo mặc định:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe

Chỉ sử dụng SHA-1:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --sha1=true \
  --sha2=false

Đồng thời kích hoạt SHA-1 và SHA-2:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --sha1=true \
  --sha2=true

SHA-1 chủ yếu được dùng để tương thích với các hệ thống cũ; các dự án mới thường nên ưu tiên sử dụng SHA-2.

Dấu thời gian

Khi ký mã, thường khuyến nghị đồng thời thêm dấu thời gian tin cậy.

SignTool CLI theo mặc định sẽ tự động cấu hình dịch vụ dấu thời gian cho chữ ký, cũng có thể chỉ định máy chủ dấu thời gian qua tham số:

• --timestamp-rfc3161: máy chủ dấu thời gian RFC 3161 dùng cho chữ ký SHA-2.
• --timestamp: máy chủ dấu thời gian Authenticode dùng cho chữ ký SHA-1.

Chỉ định máy chủ dấu thời gian RFC 3161:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --timestamp-rfc3161=http://timestamp.acs.microsoft.com

Chỉ định máy chủ đóng dấu thời gian Authenticode:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --timestamp=http://timestamp.sectigo.com

Nếu cần tắt dấu thời gian tương ứng, bạn có thể đặt giá trị tham số thành trống:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --timestamp-rfc3161= \
  --timestamp=

Về giao thức dấu thời gian, địa chỉ máy chủ và gợi ý lựa chọn, vui lòng tham khảo Tài liệu tham khảo.

Truy vấn hạn mức ký

Sử dụng:

signtool quota

Có thể truy vấn hạn mức chứng chỉ ký mã hiển thị đối với thông tin xác thực truy cập hiện tại.

Nội dung xuất ra bao gồm:

• Số hiệu chứng chỉ.
• Thông tin chứng chỉ.
• Số lần ký còn lại.
• Tổng số lần ký.

Nếu cần xuất ra định dạng JSON:

signtool quota --json

Cũng có thể sử dụng cách viết tắt:

signtool quota -j

Số lần ký cụ thể có thể khác nhau tùy theo cách gọi CLI, KSP, Jarsigner hoặc công cụ build, vui lòng tham khảo Giải thích cách tính số lần ký để biết quy tắc chi tiết.

Cập nhật client

SignTool CLI hỗ trợ truy vấn và cài đặt phiên bản mới nhất cho nền tảng hiện tại:

signtool update

Trong quá trình cập nhật, kích thước tệp tải xuống và SHA-256 sẽ được xác minh để đảm bảo tính toàn vẹn của tệp máy khách.

Nếu SignTool CLI được cài đặt qua Homebrew, bạn nên tiếp tục quản lý phiên bản qua Homebrew thay vì trộn lẫn hai phương thức cập nhật.

macOS Homebrew

Người dùng macOS có thể cài đặt SignTool CLI hoặc máy khách desktop qua Homebrew Tap chính thức của sslTrus.

Cài đặt Homebrew Tap

Thực thi:

brew tap ssltrus-official/tap
brew trust ssltrus-official/tap

Sau khi hoàn tất, bạn có thể cài đặt client tương ứng.

Cài đặt SignTool CLI

Thực thi:

brew install ssltrus-official/tap/code-sign-cli

Sau khi cài đặt hoàn tất, bạn có thể thực thi:

signtool --version

Xác nhận rằng máy khách đã được cài đặt đúng cách.

Tên gói phần mềm trong Homebrew là:

code-sign-cli

Tên chương trình dòng lệnh được cài đặt thực tế là:

signtool

Cài đặt ứng dụng máy tính

Cài đặt ứng dụng máy tính ký mã sslTrus:

brew install --cask ssltrus-official/tap/code-sign-gui

Tên Cask Homebrew tương ứng là:

code-sign-gui

Cập nhật client

Nếu client được cài đặt qua Homebrew, bạn nên sử dụng Homebrew để nâng cấp.

Trước tiên, hãy cập nhật thông tin gói phần mềm Homebrew:

brew update

Nâng cấp SignTool CLI:

brew upgrade ssltrus-official/tap/code-sign-cli

Nâng cấp ứng dụng máy tính:

brew upgrade --cask ssltrus-official/tap/code-sign-gui

Điều này giúp bản cài đặt cục bộ đồng nhất với siêu dữ liệu gói Homebrew.

Windows Provider

Nếu kịch bản của bạn không phải là gọi trực tiếp SignTool CLI mà muốn Microsoft SignTool, Visual Studio, MSBuild, Advanced Installer hoặc các phần mềm Windows khác sử dụng trực tiếp khóa riêng ký mã từ xa, bạn nên sử dụng Windows Provider.

sslTrus cung cấp:

• KSP (Key Storage Provider) : dành cho Windows CNG.
• CSP (Cryptographic Service Provider) : dành cho Windows CryptoAPI truyền thống.

Vui lòng tham khảo Windows Provider.

Ký tự động CI/CD

Nếu cần thực hiện ký trong quá trình tích hợp liên tục hoặc xây dựng tự động, không nhất thiết phải cài đặt và gọi SignTool CLI thủ công.

Ví dụ GitHub Actions có thể sử dụng trực tiếp sslTrus Code Sign Action:

- 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

GitHub Action hỗ trợ Linux, macOS và Windows Runner, đồng thời có thể hoàn tất ký mã từ xa cho các tệp được chỉ định trực tiếp trong quy trình build.

Để biết cấu hình đầy đủ, vui lòng tham khảo CI/CD & công cụ build.

Cách lựa chọn

Bạn có thể chọn client hoặc phương thức tích hợp phù hợp dựa trên cách sử dụng thực tế:

Tình huống	Phương thức được khuyến nghị
Ký tệp thủ công trong terminal	SignTool CLI
Dùng script để gọi ký hàng loạt	SignTool CLI
Tra cứu hạn mức ký mã	SignTool CLI
Cài đặt và cập nhật CLI trên macOS	Homebrew
Dùng desktop client trên macOS	Homebrew
Phần mềm Windows như Microsoft SignTool gọi trực tiếp khóa riêng từ xa	KSP
Phần mềm CryptoAPI truyền thống	CSP
Ký tự động bằng GitHub Actions	GitHub Actions
Tự phát triển client ký mã	API ký mã từ xa

Nếu ứng dụng của bạn đã hỗ trợ Windows KSP, CSP hoặc các Provider chuẩn khác, thông thường nên ưu tiên sử dụng phương thức tích hợp chuẩn tương ứng; nếu cần kiểm soát trực tiếp quy trình ký, bạn có thể dùng SignTool CLI hoặc API ký mã từ xa.