Интеграция с Java

sslTrus предоставляет sslTrusJarsigner Java Provider, который может использоваться вместе со встроенным в JDK инструментом jarsigner для подписания JAR-файлов Java через удалённый сервис подписания кода.

В процессе подписания закрытый ключ для подписания кода постоянно хранится в облачном HSM. Локально формируются данные, предназначенные для подписания, и структура подписи, а закрытое подписание выполняется через sslTrusJarsigner Provider, который вызывает удалённый сервис.

Помимо подписания JAR, sslTrusJarsigner также поддерживает подписание XMLDSig и может применяться в сценариях цифровой подписи XML.

Подготовка

Перед использованием подготовьте:

• JDK 8 или более новую версию.
• sslTrusJarsigner-<version>.jar.
• Access Key.
• Access Secret.
• Номер сертификата (Cert Code).
• JAR-файл или XML-файл, который требуется подписать.

В примерах этой статьи <version>, учётные данные доступа, номер сертификата и пути к файлам необходимо заменить фактическими значениями.

Загрузка sslTrusJarsigner

Загрузите последний релизный пакет со страницы релизов sslTrusJarsigner и распакуйте его.

Релизный пакет содержит:

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

Перед использованием рекомендуется проверить целостность файла по контрольной сумме SHA-256 sslTrusJarsigner-<version>.jar.

Проверка среды выполнения

Сначала убедитесь, что Java и входящий в состав JDK jarsigner работают корректно:

java -version
jarsigner -help

Проверьте версию sslTrus Jarsigner:

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

Просмотр справки:

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

Если команда jarsigner не существует, убедитесь, что установлена полная версия JDK, а не только среда выполнения Java Runtime.

Настройка учетных данных доступа

sslTrusJarsigner считывает учетные данные доступа к сервису удаленного подписания кода и номер сертификата из переменных окружения.

Linux и 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"

Если обслуживающий персонал предоставил выделенный адрес службы, также необходимо настроить SSLTRUS_JARSIGNER_URL.

Linux и macOS:

export SSLTRUS_JARSIGNER_URL="YOUR_SERVICE_URL"

Windows PowerShell:

$env:SSLTRUS_JARSIGNER_URL = "YOUR_SERVICE_URL"

Если выделенный адрес службы не предоставлен, задавать эту переменную не нужно.

Access Secret относится к чувствительным учетным данным, его не следует включать в исходный код, общедоступные файлы конфигурации или журналы сборки. В автоматизированных средах рекомендуется передавать его через CI/CD Secret или другие механизмы управления учетными данными.

Подписание JAR

sslTrusJarsigner интегрируется со стандартным инструментом jarsigner через механизм Java Security Provider.

В приведенном ниже примере:

app-unsigned.jar

После подписания на выходе получается:

app-signed.jar

JDK 9 или более поздняя версия

Linux и 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

Способ загрузки Provider в JDK 8 отличается от JDK 9 и более поздних версий.

Сначала убедитесь:

JAVA_HOME

Укажите на полный каталог установки JDK 8.

Linux и 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"

При использовании обратите внимание:

• Номер сертификата в конце команды должен совпадать с SSLTRUS_JARSIGNER_CERT_CODE.
• Рекомендуется использовать -signedjar для вывода в новый файл, чтобы избежать перезаписи исходного JAR.
• В примере используется SHA256withRSA для завершения подписи кода.
• Если временная метка не нужна, можно удалить -tsa и следующий за ним адрес временной метки.

Временная метка

Для официально выпускаемых JAR-подписей рекомендуется добавлять доверенную временную метку.

В примере используется:

http://timestamp.sectigo.com

Соответствующие параметры:

-tsa http://timestamp.sectigo.com

Отметка времени используется для подтверждения момента подписания, при этом исходный JAR-файл не загружается на сервер отметок времени.

Если требуется использовать другой сервис отметок времени, адрес после -tsa можно заменить на адрес TSA, соответствующий фактической политике подписания.

О различных сервисах отметок времени и их выборе для производственной среды см. справочные материалы.

XML-подпись

sslTrusJarsigner также предоставляет возможность цифровой подписи XML.

XML-файл можно подписать с помощью команды sign-xml, создающей XMLDSig Enveloped Signature.

В процессе подписания локально формируются структуры дайджеста и подписи, необходимые для XMLDSig, а фактическое подписание закрытым ключом RSA выполняется удалённым сервисом подписания кода.

Linux и 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"

По умолчанию выходной KeyInfo содержит только конечный сертификат. Если принимающая сторона требует, чтобы XML содержал полную цепочку сертификатов, можно добавить параметр --full-chain в конец команды.

После завершения выполнения:

input.xml

Для исходного XML-файла,

signed.xml

Для выходных файлов, содержащих XML-цифровую подпись.

Закрытый ключ подписи кода не записывается в XML-файл и не сохраняется на локальном компьютере.

Создание файла проверки

После завершения подписания можно создать JKS-файл для проверки подписи.

Linux и 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

Этот файл используется только для проверки подписи и не может применяться для подписания кода.

Закрытый ключ для подписания кода по-прежнему хранится в удалённом HSM и не записывается в verify.jks.

Проверка подписи JAR

Используйте сгенерированный verify.jks для проверки подписи:

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

Если требуется только просмотреть существующую информацию о подписи в JAR, можно выполнить:

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

Проверка подписи только проверяет существующую подпись и не вызывает удалённый закрытый ключ повторно для выполнения подписания.

Количество подписаний

Количество подписаний Jarsigner рассчитывается по фактически успешно выполненным удалённым действиям подписания.

Обычно:

Операция	Количество подписаний
Один JAR успешно подписан один раз	1 раз
Подписать 3 JAR по отдельности	3 раза
Повторно выполнить подписание того же JAR	добавляется ещё 1 раз
jarsigner -verify проверка подписи	0 раз
Создание verify.jks	0 раз

Таким образом, количество подписаний в основном зависит от того, сколько раз фактически была выполнена успешная операция подписания, а не от количества файлов исходного кода Java-проекта.

Подробные правила см. в справочных материалах.

Часто задаваемые вопросы

Отсутствуют Access Key, Access Secret или номер сертификата

Убедитесь, что в текущем терминале заданы:

SSLTRUS_JARSIGNER_ACCESS_KEY
SSLTRUS_JARSIGNER_ACCESS_SECRET
SSLTRUS_JARSIGNER_CERT_CODE

После настройки переменных окружения необходимо выполнить команду подписи в том же сеансе терминала.

Invalid option: -providerPath

Если появляется:

Invalid option: -providerPath

Обычно это означает, что используется JDK 8.

JDK 8 не использует параметр -providerPath из примеров для JDK 9 и более поздних версий — вместо этого используйте команды для JDK 8, приведённые в этой статье.

Не удаётся загрузить SSLTrusProvider

Если появляется сообщение о невозможности загрузки:

com.racent.codesign.SSLTrusProvider

请检查：

• Путь sslTrusJarsigner-<version>.jar корректен ли.
• Соответствует ли номер версии в имени файла фактическому файлу.
• Указывает ли JAVA_HOME в среде JDK 8 на полный JDK.

Не удается найти сертификат или alias

请检查：

• Правильный ли номер сертификата.
• Совпадает ли номер сертификата, указанный в конце команды, с SSLTRUS_JARSIGNER_CERT_CODE.
• Имеют ли текущие Access Key и Access Secret право на использование этого сертификата.

Ошибка запроса удаленной подписи

请检查：

• Доступна ли в текущей сети служба удаленной подписи кода.
• Нормально ли настроены прокси, брандмауэр и DNS.
• Правильные ли Access Key и Access Secret.
• Правильный ли номер сертификата.
• Если используется выделенный адрес службы, настроен ли SSLTRUS_JARSIGNER_URL в соответствии с фактической информацией о поставке.

При устранении неполадок можно сохранять полное сообщение об ошибке, но перед отправкой журналов или скриншотов ошибок следует удалить или замаскировать конфиденциальные учетные данные, такие как Access Secret.

Сбой отметки времени

Убедитесь, что текущая сеть может получить доступ к серверу отметок времени, указанному в -tsa.

Если это допустимо для бизнеса, можно временно удалить:

-tsa <URL>

Выполните подпись ещё раз, чтобы определить, возникает ли проблема на этапе удалённого подписания кода или на этапе запроса метки времени.

Примечания по безопасности

В процессе интеграции с Java необходимо учитывать следующее:

• Access Secret следует хранить как конфиденциальные учётные данные.
• Не добавляйте учётные данные доступа в репозиторий Git.
• Не выводите полный Access Secret в журналы.
• verify.jks используется только для проверки и не содержит закрытого ключа, пригодного для удалённого подписания.
• Локальный Provider sslTrusJarsigner не сохраняет закрытый ключ подписания кода.
• Операция подписания закрытым ключом всегда выполняется удалённым сервисом подписания кода.
• В автоматизированных средах рекомендуется внедрять учётные данные доступа через CI/CD Secret или специализированную систему управления учётными данными.

Связанные способы интеграции

Если подписывать нужно не Java JAR или XML-файлы, можно выбрать другие способы интеграции в зависимости от конкретного сценария:

Сценарий	Способ интеграции
Подписание EXE, DLL, MSI и других файлов непосредственно из командной строки	Клиентский инструмент
Microsoft SignTool, Visual Studio и другие инструменты Windows	Windows Provider
GitHub Actions, Electron Builder и другие средства автоматизированной сборки	CI/CD и инструменты сборки
Самостоятельная разработка клиента удалённого подписания	Интеграция через API