Руководство по использованию 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-подпись, подпись по ID элемента и пользовательские профили 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-файлы.