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

Chuẩn bị

Trước khi sử dụng, vui lòng chuẩn bị:

• JDK 8 trở lên.
• sslTrusJarsigner-<version>.jar.
• Access Key, Access Secret và số chứng chỉ.
• Tệp JAR hoặc tệp XML TIMS/1E cần ký.

Vui lòng thay <version>, thông tin xác thực, mã chứng chỉ và đường dẫn tệp trong bài viết này bằng các giá trị thực tế.

Tải xuống

Tải gói phát hành mới nhất qua trang sau:

Tải gói mới nhất

Sau khi tải xuống và giải nén tệp ZIP, bạn sẽ nhận được:

• sslTrusJarsigner-<version>.jar
• Tệp kiểm tra SHA-256

Bạn nên kiểm tra tính toàn vẹn của tệp JAR dựa trên tệp checksum trước khi sử dụng.

Kiểm tra môi trường hoạt động

Chạy lệnh sau để xác nhận Java, jarsigner và các tệp công cụ khả dụng:

java -version
jarsigner -help
java -jar sslTrusJarsigner-<version>.jar --version

Xem thông tin trợ giúp:

java -jar sslTrusJarsigner-<version>.jar --help

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

Linux và macOS

export SSLTRUS_JARSIGNER_ACCESS_KEY="YOUR_ACCESS_KEY"
export SSLTRUS_JARSIGNER_ACCESS_SECRET="YOUR_ACCESS_SECRET"
export SSLTRUS_JARSIGNER_CERT_CODE="YOUR_CERT_CODE"

Windows PowerShell

$env:SSLTRUS_JARSIGNER_ACCESS_KEY = "YOUR_ACCESS_KEY"
$env:SSLTRUS_JARSIGNER_ACCESS_SECRET = "YOUR_ACCESS_SECRET"
$env:SSLTRUS_JARSIGNER_CERT_CODE = "YOUR_CERT_CODE"

Nếu nhân viên dịch vụ đã cung cấp địa chỉ dịch vụ riêng, bạn cũng cần thiết lập:

Linux và macOS:

export SSLTRUS_JARSIGNER_URL="YOUR_SERVICE_URL"

Windows PowerShell：

$env:SSLTRUS_JARSIGNER_URL = "YOUR_SERVICE_URL"

Khi không cung cấp địa chỉ dịch vụ chuyên dụng, vui lòng không đặt biến này.

Chữ ký

Ví dụ sau ký app-unsigned.jar và lưu thành app-signed.jar.Vui lòng sử dụng các tham số cố định nguyên trạng theo ví dụ.

JDK 9 hoặc phiên bản mới hơn

Linux và macOS:

jarsigner \
  -keystore NONE \
  -storetype SSLTRUS \
  -storepass SSLTRUS \
  -providerPath "sslTrusJarsigner-<version>.jar" \
  -providerClass com.racent.codesign.SSLTrusProvider \
  -sigalg SHA256withRSA \
  -tsa http://timestamp.sectigo.com \
  -signedjar "app-signed.jar" \
  "app-unsigned.jar" \
  "$SSLTRUS_JARSIGNER_CERT_CODE"

Windows PowerShell：

jarsigner `
  -keystore NONE `
  -storetype SSLTRUS `
  -storepass SSLTRUS `
  -providerPath "sslTrusJarsigner-<version>.jar" `
  -providerClass com.racent.codesign.SSLTrusProvider `
  -sigalg SHA256withRSA `
  -tsa http://timestamp.sectigo.com `
  -signedjar "app-signed.jar" `
  "app-unsigned.jar" `
  "$env:SSLTRUS_JARSIGNER_CERT_CODE"

JDK 8

Trước tiên, hãy xác nhận rằng JAVA_HOME trỏ tới JDK 8 hoàn chỉnh.

Linux và macOS:

jarsigner \
  -J-cp \
  -J"$JAVA_HOME/lib/tools.jar:sslTrusJarsigner-<version>.jar" \
  -keystore NONE \
  -storetype SSLTRUS \
  -storepass SSLTRUS \
  -providerClass com.racent.codesign.SSLTrusProvider \
  -sigalg SHA256withRSA \
  -tsa http://timestamp.sectigo.com \
  -signedjar "app-signed.jar" \
  "app-unsigned.jar" \
  "$SSLTRUS_JARSIGNER_CERT_CODE"

Windows PowerShell：

jarsigner `
  -J-cp `
  "-J$env:JAVA_HOME\lib\tools.jar;sslTrusJarsigner-<version>.jar" `
  -keystore NONE `
  -storetype SSLTRUS `
  -storepass SSLTRUS `
  -providerClass com.racent.codesign.SSLTrusProvider `
  -sigalg SHA256withRSA `
  -tsa http://timestamp.sectigo.com `
  -signedjar "app-signed.jar" `
  "app-unsigned.jar" `
  "$env:SSLTRUS_JARSIGNER_CERT_CODE"

Lưu ý

• Mã chứng thư ở cuối lệnh phải khớp với SSLTRUS_JARSIGNER_CERT_CODE.
• Bạn nên luôn dùng -signedjar để tạo tệp mới, tránh ghi đè JAR gốc.
• Nếu không cần dấu thời gian, bạn có thể xóa -tsa và địa chỉ theo sau nó.

Ký XML (XMLDSig)

TIMS/1E XML sử dụng lệnh sign-xml để tạo chữ ký enveloped XML Digital Signature (XMLDSig).Khóa riêng vẫn chỉ được lưu giữ trong dịch vụ ký từ xa; công cụ sẽ tạo cục bộ phần tóm tắt và cấu trúc chữ ký mà XMLDSig yêu cầu, sau đó dịch vụ từ xa hoàn tất chữ ký RSA.

Linux và macOS:

java -jar sslTrusJarsigner-<version>.jar \
  sign-xml \
  "input.xml" \
  "signed.xml" \
  "$SSLTRUS_JARSIGNER_CERT_CODE"

Windows PowerShell：

java -jar sslTrusJarsigner-<version>.jar `
  sign-xml `
  "input.xml" `
  "signed.xml" `
  "$env:SSLTRUS_JARSIGNER_CERT_CODE"

Định dạng chữ ký

Chữ ký được tạo sử dụng không gian tên chuẩn XMLDSig http://www.w3.org/2000/09/xmldsig#, nút Signature được ghi vào tệp đầu ra như nút con cuối cùng của nút gốc.Chữ ký profile hiện tại được cố định như sau:

Hạng mục	Giá trị cố định
Loại chữ ký	Enveloped signature
Phạm vi chữ ký	Toàn bộ tài liệu XML, Reference URI=""
Reference Transform	Enveloped Signature Transform
Canonicalization	Inclusive Canonical XML 1.0
Thuật toán tóm tắt	SHA-256
Thuật toán chữ ký	RSA-SHA256
KeyInfo	X509Data, mặc định bao gồm chứng chỉ lá

Bên gọi không cần tự tính toán tóm tắt hoặc tạo SignatureValue.Công cụ sẽ sử dụng chứng chỉ lá từ xa để điền KeyInfo/X509Data, và ghi SignatureValue cuối cùng vào XML.

Bao gồm chuỗi chứng chỉ đầy đủ

Theo mặc định, đầu ra chỉ bao gồm chứng chỉ lá để giảm kích thước XML và nhất quán với các tệp TIMS/1E phổ biến.Nếu bên nhận yêu cầu XML phải kèm theo chuỗi chứng chỉ trung gian, vui lòng thêm --full-chain vào cuối lệnh:

java -jar sslTrusJarsigner-<version>.jar \
  sign-xml \
  "input.xml" \
  "signed.xml" \
  "$SSLTRUS_JARSIGNER_CERT_CODE" \
  --full-chain

--full-chain chỉ ảnh hưởng đến danh sách chứng chỉ trong KeyInfo/X509Data, không làm thay đổi phạm vi chữ ký, thuật toán tóm tắt hay thuật toán ký.Tùy chọn này có thể được đặt trước hoặc sau số hiệu chứng chỉ; khi không cung cấp số hiệu chứng chỉ, hãy sử dụng SSLTRUS_JARSIGNER_CERT_CODE.

Đầu vào và giới hạn sử dụng

• Đầu vào phải là XML có định dạng chính xác và chứa nút gốc.
• Tệp đầu vào không được chứa sẵn nút XMLDSig Signature; công cụ sẽ từ chối ký lặp lại để tránh tạo ra tệp không thể xác nhận phạm vi chữ ký.
• Hiện chỉ hỗ trợ chữ ký enveloped cho toàn bộ tài liệu; không hỗ trợ detached signature, ký theo ID phần tử hoặc cấu hình XMLDSig tùy chỉnh.
• Công cụ sẽ vô hiệu hóa việc tải thực thể ngoài XML và DTD ngoài, do đó không chấp nhận XML phụ thuộc vào việc mở rộng thực thể ngoài.
• Sau khi ký xong, không được sửa đổi cấu trúc, văn bản, thuộc tính hoặc không gian tên của XML; bất kỳ thay đổi nào như vậy đều khiến việc xác minh XMLDSig thất bại. Luôn giữ tệp đầu vào gốc và ghi kết quả ký vào tệp đầu ra mới.

Tạo tệp xác minh

Sau khi ký, bạn có thể tạo tệp JKS cần thiết để xác thực:

Linux và macOS:

java -jar sslTrusJarsigner-<version>.jar \
  generate-keystore \
  "$SSLTRUS_JARSIGNER_CERT_CODE" \
  "verify.jks" \
  "SSLTRUS"

Windows PowerShell：

java -jar sslTrusJarsigner-<version>.jar `
  generate-keystore `
  "$env:SSLTRUS_JARSIGNER_CERT_CODE" `
  "verify.jks" `
  "SSLTRUS"

verify.jks chỉ dùng để xác minh chữ ký, không thể dùng để thực hiện ký.

Xác minh chữ ký

Sử dụng verify.jks đã tạo để xác minh JAR đã ký:

jarsigner \
  -verify \
  -verbose \
  -certs \
  -keystore "verify.jks" \
  -storetype JKS \
  -storepass "SSLTRUS" \
  "app-signed.jar"

Nếu chỉ cần xem thông tin chữ ký của JAR:

jarsigner -verify -verbose -certs "app-signed.jar"

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

Nhắc thiếu Access Key, Access Secret hoặc số chứng chỉ

Vui lòng xác nhận rằng thiết bị đầu cuối hiện tại đã đặt các biến môi trường sau:

• SSLTRUS_JARSIGNER_ACCESS_KEY
• SSLTRUS_JARSIGNER_ACCESS_SECRET
• SSLTRUS_JARSIGNER_CERT_CODE

Sau khi thiết lập biến môi trường, bạn cần thực hiện lệnh ký trong cùng một cửa sổ terminal.

Lỗi Tùy chọn không hợp lệ: -providerPath

Hiện đang sử dụng JDK 8.Vui lòng sử dụng lệnh ký JDK 8 trong bài viết này.

Thông báo không thể tải com.racent.codesign.SSLTrusProvider

Vui lòng kiểm tra:

• Đường dẫn sslTrusJarsigner-<version>.jar có đúng không.
• Số phiên bản trong tên tệp có khớp với tệp thực tế không.
• JAVA_HOME của JDK 8 có trỏ đến JDK đầy đủ không.

Lời nhắc không tìm thấy chứng chỉ hoặc alias

Vui lòng kiểm tra:

• Mã số chứng chỉ có chính xác hay không.
• Mã số chứng chỉ ở cuối lệnh có khớp với biến môi trường hay không.
• Thông tin xác thực hiện tại có quyền sử dụng chứng chỉ đó hay không.

Yêu cầu ký thất bại

Vui lòng kiểm tra:

• Cài đặt kết nối mạng, proxy và tường lửa.
• Thông tin xác thực và số chứng chỉ có chính xác không.
• Địa chỉ dịch vụ riêng có được cấu hình theo nội dung do nhân viên dịch vụ cung cấp không.

Nếu vẫn không thể giải quyết, vui lòng giữ lại thông báo lỗi đầy đủ và liên hệ với bộ phận hỗ trợ kỹ thuật.Trước khi gửi thông báo lỗi, vui lòng xóa hoặc che đi thông tin xác thực.

Lỗi dấu thời gian

Vui lòng xác nhận rằng mạng hiện tại có thể truy cập địa chỉ timestamp trong lệnh.Nếu nghiệp vụ cho phép, bạn có thể tạm thời xóa -tsa và các địa chỉ phía sau, rồi thực hiện ký lại để xác định vấn đề.

Lưu ý an toàn

• Không lưu Access Secret thật trong mã nguồn, tài liệu, tập lệnh dùng chung hoặc image.
• Không chia sẻ dòng lệnh, lịch sử terminal hoặc nhật ký pipeline chứa thông tin xác thực ra bên ngoài.
• Môi trường tự động hóa nên sử dụng biến khóa được bảo vệ để chèn thông tin xác thực.
• Vui lòng tải công cụ từ kênh phát hành đáng tin cậy và kiểm tra tính toàn vẹn của tệp trước khi sử dụng.
• Khuyến nghị giữ lại tệp JAR gốc chưa ký.