Tham khảo lệnh signtool sign

Giải thích

signtool trong bài viết này dùng để chỉ CLI máy khách ký mã từ xa của sslTrus, không phải signtool.exe đi kèm Microsoft Windows SDK. Khi sử dụng công cụ Windows SDK, sẽ được viết rõ là Microsoft signtool.exe.

signtool sign trực tiếp thực hiện ký từ xa đối với tệp cục bộ. CLI trích xuất dữ liệu cần ký tại máy cục bộ, gọi dịch vụ từ xa để hoàn tất ký bằng khóa riêng, sau đó ghi chữ ký, dấu thời gian và thông tin chứng chỉ trở lại tệp đầu ra.

signtool sign [flags]

Xem trợ giúp và phiên bản:

signtool --help
signtool --version

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

Lệnh sign đọc thông tin xác thực truy cập theo các cách sau:

Mục thông tin xác thực	Tham số	Biến môi trường	Mô tả
Access Key	`--access-key` / `-k`	`ACCESS_KEY`	Khi tham số để trống sẽ tự động đọc biến môi trường
Access Secret	`--access-secret` / `-s`	`ACCESS_SECRET`	Khi tham số để trống sẽ tự động đọc biến môi trường

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

Địa chỉ dịch vụ từ xa được kiểm soát bởi tham số --address, hỗ trợ các giá trị sau:

Giá trị tham số	Địa chỉ dịch vụ thực tế
`nicsrs`	`https://ssl.face.nicsrs.com`
Giá trị trống, `racent` hoặc bất kỳ giá trị nào khác	`https://ssl.face.racent.com`

Lưu ý

ACCESS_KEY và ACCESS_SECRET là tên biến môi trường được đọc thực tế, SIGNTOOL_ACCESS_KEY / SIGNTOOL_ACCESS_SECRET sẽ không được CLI hiện tại tự động đọc.
Không khuyến nghị ghi Access Secret vào lịch sử shell hoặc kho lưu trữ script, ưu tiên sử dụng biến môi trường được tiêm vào lúc chạy hoặc biến CI an toàn.

Giải thích tham số

Tham số	Viết tắt	Giá trị mặc định	Mô tả
`--address`	`-a`	Trống	Định danh địa chỉ dịch vụ từ xa, không phải tham số truyền URL.
`--access-key`	`-k`	trống	Khi trống, đọc `ACCESS_KEY`.
`--access-secret`	`-s`	trống	Khi trống, đọc `ACCESS_SECRET`.
`--cert-code`	`-c`	trống	Bắt buộc. Số chứng chỉ.
`--file`	`-f`	空	Bắt buộc. Đường dẫn tệp cần ký, không được là thư mục.
`--out`	`-o`	空	Đường dẫn tệp đầu ra; khi để trống và chưa bật ghi đè thì tự động tạo tên tệp mặc định.
`--override`	—	`false`	Tệp đầu ra ghi đè lên tệp gốc.
`--sha1`	`-1`	`false`	Bật ký SHA1.
`--sha2`	`-2`	`true`	Bật ký SHA2.
`--timestamp`	—	`auto`	Địa chỉ tem thời gian SHA1 Authenticode. `auto` sử dụng địa chỉ mặc định, chuỗi trống sẽ vô hiệu hóa.
`--timestamp-rfc3161`	—	`auto`	Địa chỉ tem thời gian SHA2 RFC3161. `auto` sử dụng địa chỉ mặc định, chuỗi trống sẽ vô hiệu hóa.
`--desc`	`-n`	Trống	Văn bản mô tả chương trình được ghi vào chữ ký.
`--url`	`-u`	Trống	Ghi URL thông tin chương trình của chữ ký.
`--nest`	—	`true`	Giữ chữ ký hiện có và nối thêm chữ ký lồng nhau; khi `false` thì xóa chữ ký hiện có.
`--verify`	—	`false`	Khi nối thêm chữ ký, nếu chứng chỉ không đáng tin cậy thì trả về lỗi.
`--dry-run`	—	`false`	Sử dụng chứng chỉ kiểm thử cục bộ để tạo chữ ký, không gọi giao diện ký từ xa.

Định dạng tham số boolean

Tham số boolean phải dùng định dạng 参数=值, không hỗ trợ phân tách bằng dấu cách:

Đúng: --sha1=true --sha2=false
Sai: --sha1 true --sha2 false

Quy tắc bắt buộc

Trước khi thực thi sẽ kiểm tra các điều kiện sau, nếu bất kỳ điều kiện nào không thỏa mãn thì báo lỗi và thoát:

--access-key hoặc ACCESS_KEY phải tồn tại.
--access-secret hoặc ACCESS_SECRET phải tồn tại.
--cert-code phải tồn tại.
--file phải tồn tại và không được là thư mục.
--sha1 và --sha2 phải bật ít nhất một.

Quy tắc tệp đầu ra

Khi chưa chỉ định --out:

`--override`	Hành vi đầu ra
`false`（mặc định）	Xuất ra cùng thư mục với tệp đầu vào, tên tệp là `${name}.signed.${yyyyMMdd.HHmmss}${ext}`
`true`	Ghi đè trực tiếp tệp đầu vào

Ví dụ:

app.exe    → app.signed.20260611.153000.exe
driver.sys → driver.signed.20260611.153000.sys

Lưu ý

--override=true sẽ ghi đè lên tệp gốc, vui lòng xác nhận đã sao lưu trước khi thực thi. Khi ký thất bại, CLI sẽ cố gắng xóa tệp đầu ra chưa hoàn tất.

Lựa chọn thuật toán

Mặc định chỉ bật SHA2:

signtool sign -c CERT_CODE -f app.exe

Chỉ ký SHA1:

signtool sign -c CERT_CODE -f app.exe --sha1=true --sha2=false

Ký đồng thời SHA1 và SHA2:

signtool sign -c CERT_CODE -f app.exe --sha1=true --sha2=true

Ghi chú

Khi bật đồng thời SHA1 và SHA2, quy trình sẽ xử lý SHA1 trước, sau đó xử lý SHA2. SHA1 hiện vẫn được hỗ trợ, nhưng các tình huống ký mới nên ưu tiên sử dụng SHA2.

Cấu hình dấu thời gian

Giá trị auto của --timestamp và --timestamp-rfc3161 sẽ được thay thế bằng địa chỉ mặc định trong giai đoạn xác minh:

Tham số	Giá trị thực tế của `auto`	Mục đích
`--timestamp`	`http://timestamp.sectigo.com`	Dấu thời gian SHA1 Authenticode
`--timestamp-rfc3161`	`http://timestamp.sectigo.com`	Dấu thời gian SHA2 RFC3161

Dịch vụ dấu thời gian SHA2 tùy chỉnh:

signtool sign \
  -c CERT_CODE \
  -f app.exe \
  --timestamp-rfc3161=http://timestamp.acs.microsoft.com

Tắt tem thời gian SHA2:

signtool sign -c CERT_CODE -f app.exe --timestamp-rfc3161=

Tắt tất cả dấu thời gian:

signtool sign -c CERT_CODE -f app.exe --timestamp= --timestamp-rfc3161=

Hướng dẫn

Chỉ những địa chỉ timestamp bắt đầu bằng http mới được sử dụng.
SHA1 ưu tiên sử dụng --timestamp; nếu đây không phải là địa chỉ HTTP, hệ thống sẽ thử sử dụng --timestamp-rfc3161.
SHA2 sử dụng --timestamp-rfc3161.
Khi thêm timestamp cho SHA2 thất bại, hệ thống sẽ tự động thử lại một lần giữa địa chỉ mặc định của Microsoft và Sectigo.
Lỗi timestamp không nhất thiết dẫn đến lỗi ký; CLI sẽ ghi lại lỗi và giữ kết quả ký chưa có timestamp.

Ví dụ thường gặp

Sử dụng biến môi trường để cung cấp thông tin xác thực, ký SHA2 mặc định:

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

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

Cung cấp thông tin xác thực trực tiếp bằng tham số:

signtool sign \
  --access-key "your-access-key" \
  --access-secret "your-access-secret" \
  --cert-code CERT_CODE \
  --file app-unsigned.exe \
  --out app-signed.exe

Sử dụng địa chỉ NICSRS:

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

Viết mô tả chương trình và URL trang web chính thức:

signtool sign \
  -c CERT_CODE \
  -f app-unsigned.exe \
  -o app-signed.exe \
  --desc "Example Application" \
  --url "https://example.com"

Thêm chữ ký lồng nhau (giữ lại chữ ký hiện có):

signtool sign -c CERT_CODE -f app.exe --nest=true

Ghi đè tệp gốc:

signtool sign -c CERT_CODE -f app.exe --override=true

dry-run ký thử cục bộ (không gọi giao diện từ xa):

signtool sign \
  -k dummy \
  -s dummy \
  -c CERT_CODE \
  -f app.exe \
  --dry-run=true

Ghi chú

--dry-run không gọi giao diện ký từ xa, nhưng vẫn đọc/ghi tệp cục bộ và gọi chứng chỉ tự ký cục bộ. Hiện tại vẫn trải qua bước kiểm tra không rỗng đối với thông tin xác thực và số chứng chỉ, vì vậy trong ví dụ đã sử dụng thông tin xác thực giữ chỗ.

Tham khảo khắc phục sự cố

Thông báo lỗi	Nguyên nhân có thể	Đề xuất xử lý
`access key is required...`	Chưa truyền `--access-key`, cũng chưa đặt `ACCESS_KEY`.	Đặt biến môi trường hoặc sử dụng `-k`.
`access secret is required...`	Không truyền `--access-secret`, cũng không đặt `ACCESS_SECRET`.	Đặt biến môi trường hoặc sử dụng `-s`.
`cert code is required...`	Không truyền số chứng chỉ.	Sử dụng `-c CERT_CODE`.
`sha1 or sha2 is required...`	Đã tắt cả SHA1 và SHA2 cùng lúc.	Ít nhất kích hoạt một thuật toán.
`file <path> is a directory`	`--file` trỏ đến thư mục thay vì tệp.	Đổi thành đường dẫn của tệp cần ký.
Ký timestamp thất bại nhưng tệp chữ ký đã được tạo	Dịch vụ timestamp không khả dụng hoặc kiểm tra chuỗi chứng chỉ thất bại.	Kiểm tra URL timestamp, nếu cần thì thay `--timestamp-rfc3161`.

Cấu hình thông tin xác thực​

Giải thích tham số​

Quy tắc bắt buộc​

Quy tắc tệp đầu ra​

Lựa chọn thuật toán​

Cấu hình dấu thời gian​

Ví dụ thường gặp​

Tham khảo khắc phục sự cố​