Hướng dẫn sử dụng CSP

Tổng quan

Hướng dẫn này dùng để định cấu hình sslTrus Cryptographic Service Provider (CSP) trên Windows và sử dụng Microsoft signtool.exe của Windows SDK để hoàn tất ký mã bằng HSM trên đám mây.

signtool csp của dự án này chịu trách nhiệm cài đặt, cấu hình và bảo trì Provider; khi ký thực tế, sử dụng signtool.exe của Windows SDK.Hai cái này không phải cùng một chương trình.

sslTrus Cryptographic Service Provider là CryptoAPI CSP truyền thống, phù hợp với quy trình ký Windows cần tích hợp qua /csp và /kc.Khóa riêng dùng để ký luôn được lưu giữ trong HSM trên đám mây; máy cục bộ chỉ lưu CSP DLL, chứng thư ký và cấu hình truy cập được bảo vệ bằng Windows DPAPI.

Chuẩn bị trước khi sử dụng

• Hệ điều hành Windows x64.
• Terminal chạy với quyền quản trị viên, dùng để cài đặt hoặc gỡ cài đặt Provider.
• CLI signtool của dự án này, trong đó có chứa lệnh con csp.
• Đã cài đặt Windows SDK và có thể sử dụng signtool.exe của Microsoft.
• Access Key, Access Secret và số chứng chỉ hợp lệ (CERT_CODE).
• Mạng có thể truy cập dịch vụ ký mã và dịch vụ tem thời gian đã chọn.

Xác nhận rằng hai công cụ đều có thể sử dụng riêng biệt:

REM 本项目 CLI
signtool csp --help

REM Windows SDK 工具；必要时请使用其完整路径
signtool.exe sign /?

Nếu có hai chương trình cùng tên tồn tại đồng thời trong thư mục hiện tại hoặc PATH, hãy chắc chắn xác nhận mục tiêu gọi thực tế thông qua đường dẫn đầy đủ hoặc where.

Bắt đầu nhanh

Trong terminal quản trị viên, lần lượt thực hiện:

signtool csp install
signtool csp add
signtool csp list

csp add sẽ yêu cầu nhập tương tác:

Please enter the access key: your-access-key
Please enter the access secret: your-access-secret
Please enter the certificate code: CERT_CODE

Sau khi cấu hình thành công, sử dụng Microsoft signtool.exe Signature của Windows SDK:

signtool.exe sign /v ^
  /csp "sslTrus Cryptographic Service Provider" ^
  /kc CERT_CODE ^
  /f "C:\ProgramData\sslTrusKSP\CERT_CODE.crt" ^
  /fd SHA256 ^
  /tr http://timestamp.acs.microsoft.com ^
  /td SHA256 ^
  ".\app.exe"

Thay thế CERT_CODE và app.exe trong ví dụ bằng số hiệu chứng chỉ thực tế và tệp cần ký.

Cài đặt Provider

Thực thi:

signtool csp install

Lệnh này sẽ:

• Ghi sslTrusCSP.dll vào %ProgramData%\sslTrusKSP và sao chép vào thư mục hệ thống.
• Đăng ký sslTrus Cryptographic Service Provider (loại Provider là PROV_RSA_AES).
• Cài đặt KSP DLL đi kèm và đăng ký alias CNG Provider cùng tên với CSP là sslTrus Key Storage Provider.
• Tạo hoặc lưu %ProgramData%\sslTrusKSP\config.dat; tệp được mã hóa bằng Windows DPAPI của máy cục bộ.

Quá trình cài đặt sẽ sửa đổi đăng ký Provider ở cấp hệ thống, thường phải được thực hiện trong terminal của quản trị viên.Nếu phiên bản CSP DLL trong thư mục hệ thống trùng khớp với phiên bản nhúng, CLI sẽ bỏ qua việc sao chép CSP DLL nhưng vẫn thực hiện quy trình đăng ký Provider.

Thêm cấu hình chứng chỉ

Thực thi:

signtool csp add

Để sử dụng địa chỉ dịch vụ NICSRS:

signtool csp add --address nicsrs

--address không phải là tham số truyền qua URL.Hiện tại, nicsrs sẽ sử dụng dịch vụ NICSRS; giá trị trống, racent hoặc các giá trị khác sẽ sử dụng dịch vụ mặc định.

Khi thêm, CLI sẽ lấy chứng chỉ từ dịch vụ từ xa và ghi vào:

%ProgramData%\sslTrusKSP\CERT_CODE.crt

Đồng thời ghi địa chỉ dịch vụ, thông tin xác thực, số chứng chỉ và đường dẫn chứng chỉ vào tệp cấu hình được mã hóa.CERT_CODE vừa là mã nhận dạng chứng chỉ từ xa, vừa là giá trị của /kc trong signtool.exe của Microsoft sau này.

Nếu thêm số chứng chỉ đã tồn tại, CLI sẽ hỏi có ghi đè hay không: nhập y để thay thế cấu hình cũ; nhấn Enter trực tiếp hoặc nhập giá trị khác thì giữ nguyên cấu hình ban đầu.

Xem và xóa cấu hình

Xem cấu hình hiện tại:

signtool csp list

Đầu ra bao gồm số chứng chỉ, loại dịch vụ, Access Key và Access Secret đã được che giấu.Vui lòng không tải lên công khai đầu ra lệnh, tệp cấu hình hoặc nhật ký.

Xóa một cấu hình:

signtool csp del

Nhập số chứng chỉ theo lời nhắc.Thao tác này chỉ xóa mục tương ứng trong cấu hình mã hóa, sẽ không xóa tệp chứng chỉ .crt cùng tên; khi không còn sử dụng, vui lòng tự dọn dẹp tệp đó.

Sử dụng chữ ký Microsoft signtool.exe

Chữ ký SHA-256

signtool.exe sign /v ^
  /csp "sslTrus Cryptographic Service Provider" ^
  /kc CERT_CODE ^
  /f "C:\ProgramData\sslTrusKSP\CERT_CODE.crt" ^
  /fd SHA256 ^
  /tr http://timestamp.acs.microsoft.com ^
  /td SHA256 ^
  ".\app.exe"

Mô tả tham số:

Tham số	Mô tả
/csp "sslTrus Cryptographic Service Provider"	Chỉ định CSP Provider.
/kc CERT_CODE	Chỉ định vùng chứa khóa tương ứng với số chứng chỉ.
/f <证书路径>	Chỉ định tệp chứng chỉ được tải xuống từ csp add.
/fd SHA256	Chỉ định thuật toán tóm tắt tệp.
/tr <URL>	Chỉ định dịch vụ tem thời gian RFC 3161.
/td SHA256	Chỉ định thuật toán tóm tắt tem thời gian.

CSP hiện hỗ trợ các thuật toán tóm tắt tệp SHA1, SHA256, SHA384 và SHA512; đối với chữ ký mới, thường khuyến nghị sử dụng SHA-256 hoặc phiên bản cao hơn.Địa chỉ timestamp nên được quyết định bởi chính sách chứng chỉ và khả năng tương thích với nền tảng mục tiêu của bạn.

Thêm chữ ký SHA-1

Khi thực sự có yêu cầu tương thích với hệ thống cũ, có thể thêm SHA-1 vào chữ ký hiện có:

signtool.exe sign /v ^
  /csp "sslTrus Cryptographic Service Provider" ^
  /kc CERT_CODE ^
  /f "C:\ProgramData\sslTrusKSP\CERT_CODE.crt" ^
  /fd SHA1 ^
  /tr http://timestamp.acs.microsoft.com ^
  /td SHA256 ^
  /as ^
  ".\app.exe"

/as có nghĩa là thêm chữ ký, tránh ghi đè chữ ký hiện có.Việc có cần SHA-1 hay không phải tuân theo hệ thống mục tiêu và chính sách chứng chỉ; không nên dùng nó làm lựa chọn mặc định cho các dự án mới.

Xác minh chữ ký

Sau khi ký, có thể sử dụng Microsoft signtool.exe để xác minh:

signtool.exe verify /pa /v ".\app.exe"

Để xác minh toàn bộ chữ ký, hãy chọn các tùy chọn xác minh tương ứng theo phiên bản và mô tả tham số của Windows SDK signtool.exe.

Gỡ cài đặt Provider

Trong terminal quản trị viên, thực thi:

signtool csp uninstall

Lệnh này sẽ hủy đăng ký CSP, cũng như CNG Provider alias cùng tên với CSP, và xóa bản sao ProgramData cũng như thư mục hệ thống của CSP DLL.Nó sẽ không xóa toàn bộ thư mục %ProgramData%\sslTrusKSP, cũng không tự động gỡ bỏ đăng ký và DLL đi kèm sslTrus Key Storage Provider; nếu KSP này chỉ được sử dụng trong quy trình cài đặt CSP, vui lòng kết hợp với trạng thái triển khai thực tế để dọn dẹp một cách thận trọng.

Sau khi gỡ cài đặt, nếu cần xóa dữ liệu nhạy cảm cục bộ, vui lòng xác nhận rằng dữ liệu không còn được KSP hoặc quy trình ký khác sử dụng, sau đó xóa thủ công cấu hình, chứng chỉ và nhật ký trong %ProgramData%\sslTrusKSP.

Câu hỏi thường gặp

Hiện tượng	Đề xuất xử lý
cryptographic service provider is only supported on windows	Thực thi lệnh quản trị CSP trên Windows.
Khi cài đặt báo lỗi quyền hoặc ghi vào thư mục hệ thống thất bại	Dùng terminal quản trị để thực thi signtool csp install.
no csp configuration	Thực thi signtool csp install trước, rồi thực thi signtool csp add.
no such certificate code	Trước tiên dùng signtool csp list để đối chiếu số hiệu chứng chỉ.
signtool.exe của Microsoft không tìm thấy Provider	Xác nhận lệnh cài đặt thành công, công cụ hiện tại và Provider đều là x64, đồng thời mở lại terminal rồi thử lại.
Khi ký không tìm thấy tệp chứng chỉ	Xác nhận đường dẫn /f khớp với CERT_CODE.crt đã tải từ csp add.
Gọi ký thất bại	Kiểm tra số hiệu chứng chỉ, thông tin xác thực dịch vụ và kết nối mạng; sau đó xem %ProgramData%\sslTrusKSP\sslTrusCSP.log.
Dùng địa chỉ dịch vụ tùy chỉnh nhưng yêu cầu bất thường	CSP cố định đường dẫn /v1/codesign/sign của dịch vụ yêu cầu; địa chỉ dịch vụ được cấu hình chỉ nên cung cấp http(s)://host[:port].

Hướng dẫn bảo mật

• Access Secret、config.dat、tệp chứng chỉ và nhật ký CSP đều phải được xử lý như dữ liệu nhạy cảm.
• config.dat được bảo vệ bởi DPAPI của profile người dùng Windows hiện tại đã tạo cấu hình, không nên sao chép trực tiếp sang người dùng hoặc máy khác để tái sử dụng.
• CSP không lưu khóa riêng tư; đừng cố nhập khóa riêng tư vào %ProgramData%\sslTrusKSP.
• Việc ký CSP cần truy cập dịch vụ từ xa, thời gian chờ mạng, việc máy chủ từ chối hoặc dịch vụ tem thời gian không khả dụng đều có thể dẫn đến lỗi ký.

Để tham khảo thêm các tham số CLI và lệnh ký, vui lòng xem Tham chiếu lệnh ký SignTool.