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

Công tác chuẩn bị

Trước khi sử dụng, hãy chuẩn bị:

• JDK 8 hoặc phiên bản cao hơ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 thế <version>, thông tin xác thực, số chứng chỉ và đường dẫn tệp trong bài viết này bằng giá trị thực tế.

Tải xuống

Tải xuống 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 đối chiếu tính toàn vẹn của tệp JAR với tệp kiểm tra trước khi sử dụng.

Kiểm tra môi trường chạy

Thực hiện 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 hỗ trợ đã cung cấp địa chỉ dịch vụ chuyên dụ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 rồi lưu thành app-signed.jar. Các tham số cố định vui lòng sử dụng nguyên dạng như trong ví dụ.

JDK 9 trở lê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

Vui lòng xác nhận JAVA_HOME trỏ đến JDK 8 đầy đủ.

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 ý

• Số chứng chỉ ở cuối lệnh phải khớp với SSLTRUS_JARSIGNER_CERT_CODE.
• Khuyến nghị 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, có thể xóa -tsa và địa chỉ phía sau nó.

Ký XML (XMLDSig)

XML TIMS/1E dùng lệnh sign-xml để tạo chữ ký XML Digital Signature (XMLDSig) dạng enveloped. Khóa riêng vẫn chỉ nằm 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 cần, 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 dưới dạng nút con cuối cùng của nút gốc. Profile chữ ký 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 xây dựng SignatureValue. Công cụ sẽ sử dụng chứng chỉ lá của chứng chỉ từ xa để điền KeyInfo/X509Data, và ghi SignatureValue cuối cùng vào trong 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 chứa 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 thay đổi phạm vi ký, thuật toán tóm tắt hoặc thuật toán ký. Tùy chọn này có thể đặt trước hoặc sau số hiệu chứng chỉ; khi không cung cấp số hiệu chứng chỉ, sử dụng SSLTRUS_JARSIGNER_CERT_CODE.

Giới hạn đầu vào và sử dụng

• Đầu vào phải là XML đúng định dạng và có 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 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 XMLDSig profile tùy chỉnh.
• Công cụ sẽ vô hiệu hóa việc tải XML external entity và external DTD, do đó không chấp nhận XML phụ thuộc vào việc mở rộng external entity.
• Sau khi ký xong, không 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 cho việc xác minh:

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ỉ được 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

Cảnh báo thiếu Access Key, Access Secret hoặc số chứng chỉ

Vui lòng xác nhận terminal hiện tại đã thiết lập 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, cần thực thi lệnh ký trong cùng một cửa sổ terminal.

Cảnh báo tùy chọn bất hợp pháp: -providerPath

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

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

Vui lòng kiểm tra:

• Đường dẫn sslTrusJarsigner-<version>.jar có chính xác 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.

Cảnh báo không tìm thấy chứng chỉ hoặc alias

Vui lòng kiểm tra:

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

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

Vui lòng kiểm tra:

• Kết nối mạng, proxy và cài đặt 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 đúng nội dung 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ệ 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.

Xác thực dấu thời gian thất bại

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

Lưu ý bảo mật

• 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ẻ ra ngoài dòng lệnh, lịch sử terminal hoặc nhật ký pipeline có chứa thông tin xác thực.
• Môi trường tự động hóa nên sử dụng biến khóa được bảo vệ để tiêm thông tin xác thực.
• Vui lòng tải công cụ từ các 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ý.