Tích hợp Java

sslTrus cung cấp sslTrusJarsigner Java Provider, có thể kết hợp sử dụng với công cụ jarsigner đi kèm JDK, để hoàn tất ký JAR file Java 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 đá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 qua sslTrusJarsigner Provider để hoàn tất 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 hoặc phiên bản cao hơn.
• sslTrusJarsigner-<version>.jar.
• Access Key.
• Access Secret.
• Mã chứng chỉ (Cert Code).
• File JAR hoặc file 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, mã chứng chỉ và đường dẫn file đều cần thay 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 sslTrusJarsigner-<version>.jar bằng cách kiểm tra tệp theo 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 jarsigner đi kèm với Java và 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 đủ, chứ 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 có địa chỉ dịch vụ chuyên dụng được cung cấp, 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, nên đưa vào thông 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ụ jarsigner tiêu chuẩn thông qua cơ chế Java Security Provider.

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

app-unsigned.jar

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

app-signed.jar

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

Cách JDK 8 tải Provider khác với JDK 9 và các phiên bản mới 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 dùng -signedjar để xuất ra tệp mới, tránh ghi đè lên 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 phía sau nó.

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 và 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 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 sản xuất, vui lòng tham khảo Tài liệu tham khảo.

Chữ ký XML

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

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

Trong quá trình ký, phía cục bộ chịu trách nhiệm tạo cấu trúc tóm tắt và chữ ký mà XMLDSig yêu cầu, còn việc ký bằng 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"

Theo mặc định, kết quả KeyInfo chỉ bao gồm chứng chỉ lá. Nếu bên nhận yêu cầu XML phải chứa chuỗi chứng chỉ đầy đủ, bạn có thể thêm tham số --full-chain vào cuối lệnh.

Sau khi thực thi xong:

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 dùng để ký mã sẽ không được ghi vào tệp XML và 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"

Tạo:

verify.jks

Tệp này chỉ được sử 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ý hiện có trong JAR, bạn có thể thực hiện:

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

Việc xác minh chữ ký chỉ kiểm tra chữ ký hiện có và 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 3 JAR	3 lần
Ký lại cùng một JAR thêm 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ố thao tác ký thành công thực sự được thực hiện, chứ không phải số 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 số chứng chỉ

Xác nhận terminal hiện tại đã 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 dành cho 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ó 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.
• Trong môi trường JDK 8, JAVA_HOME 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ó chính xác 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ó chính xác không.
• Số chứng chỉ có chính xác 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ố, 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, nên xóa hoặc che đi Access Secret và các thông tin xác thực nhạy cảm khác.

Dấu thời gian thất bại

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

Nếu nghiệp vụ cho phép, 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 giữ 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 Git.
• Không ghi đầy đủ Access Secret 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ý từ xa.
• Provider sslTrusJarsigner 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 do dịch vụ ký mã từ xa hoàn thành.
• 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, 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 v.v. qua dòng lệnh	Công cụ máy khách
Các công cụ Windows như Microsoft SignTool, Visual Studio v.v.	Windows Provider
Các bản dựng tự động như GitHub Actions, Electron Builder v.v.	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