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

Tổng quan

Hướng dẫn này dùng để cấu hình sslTrus Cryptographic Service Provider (CSP) trên Windows, và sử dụng signtool.exe của Microsoft trong Windows SDK để hoàn tất ký mã bằng HSM đá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 chương trình này không phải là cùng một chương trình.

sslTrus Cryptographic Service Provider là CSP CryptoAPI truyền thống, phù hợp với quy trình ký trên Windows cần tích hợp qua /csp và /kc. Khóa riêng để ký luôn được giữ trong HSM đám mây, máy cục bộ chỉ lưu CSP DLL, chứng chỉ ký và cấu hình truy cập được bảo vệ bởi 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ó lệnh con csp.
• Đã cài đặt Windows SDK và có thể sử dụng Microsoft signtool.exe.
• 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 hai công cụ riêng biệt khả dụng:

REM 本项目 CLI
signtool csp --help

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

Nếu cả thư mục hiện tại và PATH đều có hai chương trình cùng tên, hãy xác nhận mục tiêu thực sự được gọi bằng đường dẫn đầy đủ hoặc where.

Bắt đầu nhanh

Thực hiện lần lượt trong terminal quản trị:

signtool csp install
signtool csp add
signtool csp list

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

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 của Windows SDK để ký:

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 sslTrus Key Storage Provider cùng tên với CSP.
• Tạo hoặc lưu %ProgramData%\sslTrusKSP\config.dat; tệp được mã hóa bằng Windows DPAPI của máy.

Việc cài đặt sẽ sửa đổi đăng ký Provider cấp hệ thống, thường phải thực thi trong terminal quản trị. Nếu phiên bản CSP DLL trong thư mục hệ thống trùng 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

Nếu cần 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ị rỗ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ố hiệu 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 ở các bước tiếp theo.

Nếu thêm số hiệu 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 hiện tại.

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

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

signtool csp list

Kết quả đầu ra bao gồm số chứng chỉ, loại dịch vụ, Access Key và Access Secret đã được che dấu. Vui lòng không tải lên các vị trí 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 nào đó:

signtool csp del

Nhập số hiệu 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, không xóa tệp chứng chỉ .crt cùng tên; vui lòng tự dọn dẹp tệp đó khi không còn sử dụng.

Sử dụng signtool.exe của Microsoft để ký

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"

Tham số:

Tham số	Mô tả
/csp "sslTrus Cryptographic Service Provider"	Chỉ định CSP Provider.
/kc CERT_CODE	Chỉ định key container 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ụ timestamp RFC 3161.
/td SHA256	Chỉ định thuật toán tóm tắt timestamp.

Hiện tại CSP 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 nên sử dụng SHA-256 hoặc phiên bản cao hơn. Địa chỉ timestamp phải được xác định theo chính sách chứng chỉ và khả năng tương thích của nền tảng mục tiêu.

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ũ, bạn 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à chữ ký bổ sung, tránh ghi đè chữ ký hiện có. Việc có cần SHA-1 hay không nên 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ể dùng Microsoft signtool.exe để xác minh:

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

Để xác minh tất cả chữ ký, bạn có thể chọn các tùy chọn xác minh tương ứng theo phiên bản và tham số của Windows SDK signtool.exe.

Gỡ cài đặt Provider

Thực thi trong terminal với quyền quản trị viên:

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, đồng thời xóa bản sao CSP DLL trong ProgramData và thư mục hệ thống. Lệnh 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 của sslTrus Key Storage Provider đi kèm; nếu KSP này chỉ được sử dụng trong quy trình cài đặt CSP, vui lòng cân nhắc dọn dẹp cẩn thận dựa trên trạng thái triển khai thực tế.

Nếu sau khi gỡ cài đặt cần xóa dữ liệu nhạy cảm cục bộ, vui lòng xác nhận 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.
Báo lỗi quyền hoặc ghi vào thư mục hệ thống không thành công khi cài đặt	Sử dụng terminal quản trị viên để thực thi signtool csp install.
no csp configuration	Trước tiên thực thi signtool csp install, sau đó thực thi signtool csp add.
no such certificate code	Trước tiên hãy dùng signtool csp list để đối chiếu số hiệu chứng chỉ.
Không tìm thấy Provider signtool.exe của Microsoft	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.
Không tìm thấy tệp chứng chỉ khi ký	Xác nhận đường dẫn /f khớp với CERT_CODE.crt được tải xuống 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.
Sử 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].

Lưu ý bảo mật

• Access Secret, config.dat, tệp chứng chỉ và nhật ký CSP đều nên được xử lý như tài 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 khi 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.
• Ký CSP cần truy cập dịch vụ từ xa; hết thời gian chờ mạng, máy chủ từ chối hoặc dịch vụ dấu thời gian không khả dụng đều có thể khiến ký thất bại.

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