Chuyển tới nội dung chính

Tham khảo lệnh signtool sign

Lưu ý

signtool trong bài viết này là 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, bài viết sẽ ghi rõ là Microsoft signtool.exe.

signtool sign Ký từ xa trực tiếp trên tệp cục bộ.CLI trích xuất dữ liệu cần ký 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 chứng chỉ​

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

Mục thông tin xác thựcTham sốBiến môi trườngMô tả
Access Key--access-key / -kACCESS_KEYTự động đọc biến môi trường khi tham số trống
Access Secret--access-secret / -sACCESS_SECRETTự động đọc biến môi trường khi tham số 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ế
nicsrshttps://ssl.face.nicsrs.com
Giá trị rỗng, racent hoặc giá trị tùy ý kháchttps://ssl.face.racent.com
Lưu ý
  • ACCESS_KEY và ACCESS_SECRET là tên biến môi trường thực sự được đọc, SIGNTOOL_ACCESS_KEY / SIGNTOOL_ACCESS_SECRET sẽ không được CLI hiện tại tự động đọc.
  • Không nên ghi Access Secret vào lịch sử shell hoặc kho lưu trữ script, hãy ưu tiên sử dụng biến môi trường được chèn vào lúc chạy hoặc biến CI an toàn.

Mô tả tham số​

Tham sốViết tắtGiá trị mặc địnhMô tả
--address-aTrốngĐịnh danh địa chỉ dịch vụ từ xa, không phải tham số truyền qua URL.
--access-key-kTrốngKhi để trống sẽ đọc ACCESS_KEY.
--access-secret-sTrốngKhi để trống sẽ đọc ACCESS_SECRET.
--cert-code-cTrốngBắt buộc. Số hiệu chứng chỉ.
--file-fTrốngBắt buộc. Đường dẫn tệp cần ký, không được là thư mục.
--out-oTrốngĐườ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—falseTệp đầu ra ghi đè tệp gốc.
--sha1-1falseBật ký SHA1.
--sha2-2trueBật ký SHA2.
--timestamp—autoĐịa chỉ tem thời gian SHA1 Authenticode. auto dùng địa chỉ mặc định, chuỗi trống sẽ tắt.
--timestamp-rfc3161—autoĐịa chỉ tem thời gian SHA2 RFC3161. auto dùng địa chỉ mặc định, chuỗi trống sẽ tắt.
--desc-nTrốngVăn bản mô tả chương trình ghi vào chữ ký.
--url-uTrốngURL thông tin chương trình ghi vào chữ ký.
--nest—trueGiữ chữ ký hiện có và thêm chữ ký lồng nhau; false sẽ xóa chữ ký hiện có.
--verify—falseKhi thêm chữ ký, nếu chứng chỉ không đáng tin cậy sẽ trả về lỗi.
--dry-run—falseDù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 sử 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 hiện, hệ thống sẽ kiểm tra các điều kiện sau; nếu bất kỳ điều kiện nào không được đáp ứng, sẽ 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 không chỉ định --out:

--overrideHà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}
trueGhi đè 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 đè tệp gốc, vui lòng xác nhận đã sao lưu trước khi thực thi. Khi ký không thành công, 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​

Chỉ bật SHA2 theo mặc định:

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 ư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 thực:

Tham sốauto giá trị thực tếMục đích
--timestamphttp://timestamp.sectigo.comDấu thời gian SHA1 Authenticode
--timestamp-rfc3161http://timestamp.sectigo.comDấ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 dấu 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=
Ghi chú
  • 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 nó không phải là địa chỉ HTTP, thì sẽ thử sử dụng --timestamp-rfc3161.
  • SHA2 sử dụng --timestamp-rfc3161.
  • Khi SHA2 thêm timestamp thất bại, nó sẽ tự động thử lại một lần giữa các địa chỉ mặc định của Microsoft và Sectigo.
  • Timestamp thất bại không nhất thiết dẫn đến ký thất bại, CLI sẽ ghi lại lỗi và giữ lại kết quả ký chưa có timestamp.

Ví dụ thường dùng​

Sử dụng biến môi trường để cung cấp thông tin xác thực, chữ 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ữ nguyên 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 sẽ đọ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 kiểm tra không rỗng đối với chứng thư và số chứng chỉ, vì vậy trong ví dụ sử dụng chứng thư giữ chỗ.

Tài liệu tham khảo khắc phục sự cố​

Thông báo lỗiNguyê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 dùng -k.
access secret is required...Chưa truyền --access-secret, cũng chưa đặt ACCESS_SECRET.Đặt biến môi trường hoặc dùng -s.
cert code is required...Chưa truyền số chứng chỉ.Dùng -c CERT_CODE.
sha1 or sha2 is required...Đồng thời tắt SHA1 và SHA2.Ít nhất bậ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 đến tệp cần ký.
Ký dấu thời gian thất bại nhưng tệp chữ ký đã được tạoDịch vụ dấu thời gian không khả dụng hoặc xác minh chuỗi chứng chỉ thất bại.Kiểm tra URL dấu thời gian, nếu cần thì thay --timestamp-rfc3161.
Cập nhật lần cuối vào