Công cụ máy khách

sslTrus cung cấp ứng dụng khách dòng lệnh và ứng dụng khách máy tính để kết nối dịch vụ ký mã từ xa và hoàn tất việc ký tệp tin.

Trong đó, SignTool CLI phù hợp cho các tình huống dòng lệnh, script 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 ứng dụng desktop qua Homebrew.

SignTool CLI

SignTool CLI là ứng dụng khách 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 chữ ký	signtool quota	Tra cứu số lượt ký còn lại và tổng hạn mức của chứng chỉ
Cập nhật máy khách	signtool update	Kiểm tra và cài đặt phiên bản máy khách 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, cách sử dụng cụ thể vui lòng tham khảo Windows Provider.

Tải xuống ứng dụng khách

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

sslTrus trình khách hàng

Trang phát hành cung cấp các gói cài đặt ứng dụng khách mới nhất cho từng nền tảng.Kịch bản tự động hóa cũng có thể truy vấn thông tin phiên bản mới nhất hiện tại thông 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 thêm phần macOS Homebrew bên dưới.

Xem thông tin máy khách

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

signtool --help

Xem trợ giúp về lệnh.

Xem phiên bản client hiện tại:

signtool --version

Thông tin phiên bản bao gồm phiên bản client, bản revision build, nền tảng chạy và thời gian build, v.v.

Thông tin truy cập

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

• Access Key
• Access Secret
• Mã chứng chỉ (Cert Code)

Trong đó Access Key và Access Secret được sử 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 hiện ký trên thực tế.

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

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

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 tiết lộ Access Secret：

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

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

Mặc định, SignTool CLI sử dụng địa chỉ dịch vụ sản xuất 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.

Ký tên tệp

Sử dụng signtool sign có thể trực tiếp thực hiện ký mã từ xa cho các 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 truy cập tương ứng.

Mặc định sử dụng SHA-2 để thực hiện chữ ký.

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

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

Bạn có thể chỉ định tệp đầu ra sau khi ký bằng --out:

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

Ghi đè tệp gốc

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

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

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

Trong môi trường tự động hóa xây dựng, cần xác nhận rằng bước tiếp theo yêu cầu 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

Mặc định bật SHA-2:

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 sử 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

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

SignTool CLI mặc định sẽ tự động cấu hình dịch vụ timestamp cho chữ ký, cũng có thể chỉ định máy chủ timestamp 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ủ timestamp RFC 3161:

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

Chỉ định máy chủ 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, có thể đặt giá trị tham số thành rỗng:

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

Để biết thêm 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 chữ ký

Sử dụng:

signtool quota

Có thể truy vấn hạn mức chứng chỉ ký mã hiện có của thông tin xác thực truy cập.

Thông tin đầu ra bao gồm:

• Mã số chứng thư.
• Thông tin chứng thư.
• Số lần ký còn lại.
• Tổng số lần ký.

Nếu cần đầu ra ở định dạng JSON:

signtool quota --json

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

signtool quota -j

Cách tính số lần ký cụ thể có thể khác nhau tùy thuộc vào cách gọi CLI, KSP, Jarsigner hoặc công cụ xây dựng, vui lòng tham khảo Hướng dẫn tính số lần ký để biết chi tiết.

Cập nhật máy khách

SignTool CLI hỗ trợ truy vấn và cài đặt phiên bản mới nhất của 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 cả hai cách cập nhật cùng lúc.

macOS Homebrew

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

Kho lưu trữ công khai: ssltrus-official/homebrew-tap

Cài đặt Homebrew Tap

Thực hiện:

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

Sau khi hoàn tất, bạn có thể cài đặt ứng dụng khách tương ứng.

Cài đặt SignTool CLI

Thực hiện:

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

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

signtool --version

Xác nhận rằng ứng dụng 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 thực tế được cài đặt là:

signtool

Cài đặt ứng dụng khách trên máy tính để bàn

Cài đặt ứng dụng desktop ký mã sslTrus:

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

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

code-sign-gui

Cập nhật máy khách

Nếu khách hàng cài đặt qua Homebrew, nên sử dụng Homebrew để nâng cấp.

Trước tiên, 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 desktop:

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

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

Windows Provider

Nếu tình huống của bạn không phải gọi trực tiếp SignTool CLI, mà muốn Microsoft SignTool, Visual Studio, MSBuild, Advanced Installer hoặc phần mềm Windows khác trực tiếp sử dụng 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.

CI/CD tự động ký số

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

Ví dụ: GitHub Actions có thể trực tiếp sử dụng 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ể thực hiện ký mã từ xa trực tiếp trên các tệp tin cụ thể trong quy trình xây dựng.

Kho lưu trữ công khai: ssltrus-official/code-sign-action

Để biết cấu hình đầy đủ, vui lòng tham khảo CI/CD và công cụ xây dựng.

Cách lựa chọn

Bạn có thể lựa chọn ứng dụng khách 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	Cách đề xuất
Ký tệp thủ công trong terminal	SignTool CLI
Sử dụng tập lệnh để gọi ký hàng loạt	SignTool CLI
Truy vấn hạn mức ký mã	SignTool CLI
Cài đặt và cập nhật CLI trên macOS	Homebrew
Sử dụng ứng dụng khách trên máy tính để bà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 trong GitHub Actions	GitHub Actions
Tự phát triển ứng dụng khách ký	API ký mã từ xa

Nếu ứng dụng của bạn đã hỗ trợ Windows KSP, CSP hoặc các Provider tiêu chuẩn khác, thông thường bạn nên ưu tiên sử dụng phương thức tích hợp tiêu 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ể sử dụng SignTool CLI hoặc API ký mã từ xa.