Руководство по использованию sslTrusJarsigner

Подготовка

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

• JDK 8 или более позднюю версию.
• sslTrusJarsigner-<version>.jar.
• Access Key, Access Secret и номер сертификата.
• JAR-файл или файл TIMS/1E XML для подписи.

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

Загрузка

Загрузите последний релизный пакет со следующей страницы:

Загрузить последний пакет

После загрузки и распаковки ZIP-файла вы получите:

• sslTrusJarsigner-<version>.jar
• Файл контрольной суммы SHA-256

Рекомендуется перед использованием проверить целостность JAR-файла по контрольному файлу.

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

Выполните следующую команду, чтобы убедиться, что Java, jarsigner и файлы инструмента доступны:

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

Посмотреть справочную информацию:

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

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

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"

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

Linux и macOS:

export SSLTRUS_JARSIGNER_URL="YOUR_SERVICE_URL"

Windows PowerShell:

$env:SSLTRUS_JARSIGNER_URL = "YOUR_SERVICE_URL"

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

Подпись

В следующем примере 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

Сначала убедитесь, что 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.
• Если метка времени не нужна, можно удалить -tsa и адрес после неё.

Подпись XML (XMLDSig)

XML TIMS/1E использует команду sign-xml для создания XML Digital Signature (XMLDSig) enveloped-подписи. Закрытый ключ по-прежнему хранится только в удалённой службе подписи; инструмент локально формирует структуру дайджеста и подписи, необходимую для 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"

Формат подписи

Создаваемая подпись использует пространство имён стандарта XMLDSig http://www.w3.org/2000/09/xmldsig#, узел Signature записывается в выходной файл как последний дочерний узел корневого элемента. Текущий профиль подписи фиксирован следующим образом:

Параметр	Фиксированное значение
Тип подписи	Enveloped signature
Область подписи	Весь XML-документ, Reference URI=""
Reference Transform	Enveloped Signature Transform
Canonicalization	Inclusive Canonical XML 1.0
Алгоритм дайджеста	SHA-256
Алгоритм подписи	RSA-SHA256
KeyInfo	X509Data, по умолчанию включает листовой сертификат

Вызывающей стороне не нужно самостоятельно вычислять дайджест или формировать SignatureValue. Инструмент заполнит KeyInfo/X509Data листовым сертификатом из удалённого сертификата и запишет в XML итоговый SignatureValue.

Включение полной цепочки сертификатов

По умолчанию вывод содержит только конечный сертификат, чтобы уменьшить размер XML и сохранить совместимость с распространёнными файлами TIMS/1E. Если принимающая сторона требует включения цепочки промежуточных сертификатов в XML, добавьте в конец команды --full-chain:

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

--full-chain влияет только на список сертификатов в KeyInfo/X509Data, не изменяя область подписи, алгоритм дайджеста или алгоритм подписи. Этот параметр можно указывать до или после номера сертификата; если номер сертификата не указан, используется SSLTRUS_JARSIGNER_CERT_CODE.

Ограничения ввода и использования

• Ввод должен быть корректно сформированным XML и содержать корневой узел.
• Входной файл не должен уже содержать узел XMLDSig Signature; инструмент отклоняет повторное подписание, чтобы избежать создания файла, в котором невозможно подтвердить область подписи.
• В настоящее время поддерживается только enveloped-подпись всего документа; detached signature, подпись по идентификатору элемента и пользовательские профили XMLDSig не поддерживаются.
• Инструмент отключает загрузку внешних XML-сущностей и внешних DTD, поэтому XML, зависящий от раскрытия внешних сущностей, не принимается.
• После завершения подписания не изменяйте структуру, текст, атрибуты или пространства имён XML; любые такие изменения приведут к ошибке проверки XMLDSig. Всегда сохраняйте исходный входной файл и записывайте результат подписания в новый выходной файл.

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

После подписания можно создать 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 используется только для проверки подписи и не может использоваться для создания подписи.

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

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

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

Если нужно только просмотреть информацию о подписи JAR:

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

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

Появляется сообщение об отсутствии Access Key, Access Secret или номера сертификата

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

• SSLTRUS_JARSIGNER_ACCESS_KEY
• SSLTRUS_JARSIGNER_ACCESS_SECRET
• SSLTRUS_JARSIGNER_CERT_CODE

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

Появляется сообщение Недопустимый параметр: -providerPath

В настоящее время используется JDK 8. Используйте команду подписи для JDK 8, приведённую в этой статье.

Появляется сообщение о невозможности загрузить com.racent.codesign.SSLTrusProvider

Проверьте:

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

Появляется сообщение о том, что сертификат или alias не найден

Проверьте:

• Правильность номера сертификата.
• Совпадает ли номер сертификата в конце команды с переменной окружения.
• Имеет ли текущий набор учётных данных право использовать этот сертификат.

Ошибка запроса подписи

Проверьте:

• Сетевое подключение, настройки прокси и брандмауэра.
• Правильность учётных данных и номера сертификата.
• Настроен ли адрес выделенного сервиса в соответствии с информацией, предоставленной сотрудником службы поддержки.

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

Ошибка метки времени

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

Меры безопасности

• Не сохраняйте реальный Access Secret в исходном коде, документации, общих скриптах или образах.
• Не передавайте третьим лицам командные строки, историю терминала или журналы конвейера, содержащие учётные данные.
• В автоматизированных средах используйте защищённые переменные секретов для внедрения учётных данных.
• Загружайте инструменты только из доверенных каналов публикации и проверяйте целостность файлов перед использованием.
• Рекомендуется сохранять неподписанные исходные JAR-файлы.