Tích hợp Java

sslTrus cung cấp Java Provider sslTrusJarsigner, có thể phối hợp sử dụng với công cụ jarsigner đi kèm JDK để hoàn tất ký tệp Java JAR thông qua dịch vụ ký mã từ xa.

Trong quá trình ký, khóa riêng ký mã luôn được lưu trong HSM trên đám mây. Phía local chịu trách nhiệm tạo dữ liệu cần ký và cấu trúc chữ ký, đồng thời gọi dịch vụ từ xa thông qua sslTrusJarsigner Provider để hoàn tất việc ký bằng khóa riêng.

Ngoài ký JAR, sslTrusJarsigner còn cung cấp khả năng ký XMLDSig, có thể dùng cho các tình huống chữ ký số XML.

Chuẩn bị

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

• JDK 8 trở lên.
• sslTrusJarsigner-<version>.jar.
• Access Key.
• Access Secret.
• Số chứng chỉ (Cert Code).
• Tệp JAR hoặc tệp XML cần ký.

Trong ví dụ của bài viết này, <version>, thông tin xác thực truy cập, số chứng chỉ và đường dẫn tệp đều cần được thay thế bằng giá trị thực tế.

Tải xuống sslTrusJarsigner

Tải gói phát hành mới nhất từ trang phát hành sslTrusJarsigner và giải nén.

Gói phát hành bao gồm:

sslTrusJarsigner-<version>.jar
SHA-256 校验文件

Bạn nên xác minh tính toàn vẹn của tệp sslTrusJarsigner-<version>.jar bằng cách kiểm tra SHA-256 trước khi sử dụng.

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

Trước tiên, hãy xác nhận rằng Java và jarsigner đi kèm JDK có thể hoạt động bình thường:

java -version
jarsigner -help

Kiểm tra phiên bản sslTrusJarsigner:

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

Xem trợ giúp:

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

Nếu lệnh jarsigner không tồn tại, vui lòng xác nhận rằng bạn đang cài đặt JDK đầy đủ, không phải môi trường chạy chỉ bao gồm Java Runtime.

Cấu hình thông tin xác thực truy cập

sslTrusJarsigner đọc thông tin xác thực truy cập và số hiệu chứng chỉ của dịch vụ ký mã từ xa thông qua biến môi trường.

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ụ chuyên dụng, bạn cũng cần thiết lập SSLTRUS_JARSIGNER_URL.

Linux và macOS:

export SSLTRUS_JARSIGNER_URL="YOUR_SERVICE_URL"

Windows PowerShell：

$env:SSLTRUS_JARSIGNER_URL = "YOUR_SERVICE_URL"

Nếu không cung cấp địa chỉ dịch vụ riêng, bạn không cần đặt biến này.

Access Secret là thông tin xác thực nhạy cảm, không nên ghi vào mã nguồn, tệp cấu hình công khai hoặc nhật ký build. Trong môi trường tự động hóa, bạn nên đưa vào qua CI/CD Secret hoặc cơ chế quản lý thông tin xác thực khác.

Ký JAR

sslTrusJarsigner tích hợp với công cụ chuẩn jarsigner thông qua cơ chế Java Security Provider.

Ví dụ dưới đây sẽ:

app-unsigned.jar

Sau khi ký, đầu ra là:

app-signed.jar

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

Cách JDK 8 tải Provider khác với JDK 9 và các phiên bản cao hơn.

Trước tiên, hãy xác nhận:

JAVA_HOME

Trỏ đến thư mục cài đặt đầy đủ của JDK 8.

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"

Khi sử dụng cần lưu ý:

• Số chứng chỉ ở cuối lệnh phải khớp với SSLTRUS_JARSIGNER_CERT_CODE.
• Nên sử dụng -signedjar để xuất ra tệp mới, tránh ghi đè JAR gốc.
• Ví dụ sử dụng SHA256withRSA để hoàn tất ký mã.
• Khi không cần dấu thời gian, có thể xóa -tsa và địa chỉ dấu thời gian theo sau đó.

Dấu thời gian

Khuyến nghị thêm dấu thời gian tin cậy cho chữ ký của JAR phát hành chính thức.

Trong ví dụ sử dụng:

http://timestamp.sectigo.com

Tham số tương ứng:

-tsa http://timestamp.sectigo.com

Dấu thời gian được sử dụng để chứng minh thời điểm chữ ký được tạo ra, tệp JAR gốc sẽ không được tải lên máy chủ dấu thời gian.

Nếu cần sử dụng dịch vụ dấu thời gian khác, bạn có thể thay thế địa chỉ sau -tsa bằng địa chỉ TSA phù hợp với chính sách chữ ký thực tế.

Về các dịch vụ dấu thời gian khác nhau và lựa chọn cho môi trường production, vui lòng tham khảo Tài liệu tham khảo.

Chữ ký XML

sslTrusJarsigner còn cung cấp khả năng ký số XML.

Tệp XML có thể tạo XMLDSig Enveloped Signature thông qua lệnh sign-xml.

Trong quá trình ký, phía local chịu trách nhiệm tạo cấu trúc tóm tắt và chữ ký cần thiết cho XMLDSig, việc ký khóa riêng RSA thực tế do dịch vụ ký mã từ xa hoàn thành.

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"

The KeyInfo output by default only includes the leaf certificate. If the recipient requires the XML to contain the full certificate chain, you can add the --full-chain parameter at the end of the command.

After execution is complete:

input.xml

cho tệp XML gốc,

signed.xml

Đối với tệp đầu ra chứa chữ ký số XML.

Khóa riêng ký mã sẽ không được ghi vào tệp XML, cũng không được lưu vào máy tính cục bộ.

Tạo tệp xác minh

Sau khi ký xong, bạn có thể tạo tệp JKS dùng để xác minh chữ ký.

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"

Dịch:

verify.jks

Tệp này chỉ dùng để xác minh chữ ký, không thể dùng để thực hiện ký mã.

Khóa riêng ký mã vẫn được lưu trong HSM từ xa và sẽ không được ghi vào verify.jks.

Xác minh chữ ký JAR

Sử dụng verify.jks đã tạo để xác minh chữ 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ó trong JAR, bạn có thể thực thi:

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

Xác minh chữ ký chỉ kiểm tra chữ ký hiện có, sẽ không gọi lại khóa riêng từ xa để thực hiện ký.

Số lần ký

Số lần ký của Jarsigner được tính theo số lần ký từ xa thực sự hoàn tất thành công.

Thông thường:

Thao tác	Số lần ký
Ký thành công một JAR một lần	1 lần
Ký riêng lẻ 3 JAR	3 lần
Thực hiện ký lại cùng một JAR một lần nữa	tăng thêm 1 lần
jarsigner -verify xác minh chữ ký	0 lần
Tạo verify.jks	0 lần

Do đó, số lần ký chủ yếu phụ thuộc vào số lần thao tác ký thành công thực tế, chứ không phải số lượng tệp mã nguồn của dự án Java.

Quy tắc chi tiết vui lòng tham khảo tài liệu tham khảo.

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

Thiếu Access Key, Access Secret hoặc mã chứng chỉ

Xác nhận terminal hiện tại đã được thiết lập:

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 phiên terminal.

Invalid option: -providerPath

Nếu xuất hiện:

Invalid option: -providerPath

Thường có nghĩa là bạn đang sử dụng JDK 8.

JDK 8 không sử dụng tham số -providerPath trong các ví dụ của JDK 9 trở lên, vui lòng sử dụng lệnh JDK 8 được cung cấp trong bài viết này.

Không thể tải SSLTrusProvider

Nếu có 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 trong môi trường JDK 8 có trỏ đến JDK đầy đủ không.

Không tìm thấy chứng chỉ hoặc alias

Vui lòng kiểm tra:

• Số chứng chỉ có đúng không.
• Số chứng chỉ được chỉ định ở cuối lệnh có khớp với SSLTRUS_JARSIGNER_CERT_CODE không.
• Access Key và Access Secret hiện tại có quyền sử dụng chứng chỉ đó không.

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

Vui lòng kiểm tra:

• Mạng hiện tại có thể truy cập dịch vụ ký mã từ xa không.
• Cấu hình proxy, tường lửa và DNS có bình thường không.
• Access Key và Access Secret có đúng không.
• Số chứng chỉ có đúng không.
• Nếu sử dụng địa chỉ dịch vụ riêng, SSLTRUS_JARSIGNER_URL có được cấu hình theo thông tin bàn giao thực tế không.

Khi khắc phục sự cố, bạn có thể giữ lại thông tin lỗi đầy đủ, nhưng trước khi gửi nhật ký hoặc ảnh chụp lỗi, hãy xóa hoặc che đi Access Secret và các thông tin xác thực nhạy cảm khác.

Lỗi dấu thời gian

Xác nhận mạng hiện tại có thể truy cập máy chủ dấu thời gian được chỉ định bởi -tsa.

Nếu nghiệp vụ cho phép, bạn có thể tạm thời gỡ bỏ:

-tsa <URL>

Thực hiện ký lại để xác định sự cố xảy ra ở giai đoạn ký mã từ xa hay giai đoạn yêu cầu dấu thời gian.

Lưu ý bảo mật

Trong quá trình tích hợp Java, cần lưu ý:

• Access Secret phải được lưu trữ như thông tin xác thực nhạy cảm.
• Không commit thông tin xác thực truy cập vào kho lưu trữ Git.
• Không ghi Access Secret đầy đủ vào nhật ký.
• verify.jks chỉ dùng để xác minh, không chứa khóa riêng dùng cho ký mã từ xa.
• sslTrusJarsigner Provider cục bộ không lưu khóa riêng ký mã.
• Thao tác ký bằng khóa riêng luôn được hoàn tất bởi dịch vụ ký mã từ xa.
• Trong môi trường tự động hóa, nên sử dụng CI/CD Secret hoặc hệ thống quản lý thông tin xác thực chuyên dụng để đưa thông tin xác thực truy cập vào.

Các phương thức tích hợp liên quan

Nếu tệp cần ký không phải là tệp Java JAR hoặc XML, bạn có thể chọn phương thức tích hợp khác tùy theo tình huống thực tế:

Tình huống	Phương thức tích hợp
Ký trực tiếp các tệp EXE, DLL, MSI qua dòng lệnh	Công cụ máy khách
Các công cụ Windows như Microsoft SignTool, Visual Studio	Windows Provider
Các bản dựng tự động hóa như GitHub Actions, Electron Builder	CI/CD và công cụ xây dựng
Tự phát triển máy khách ký từ xa	Tích hợp API