VaultSslContextBuilderPlugin#

Описание плагина#

Плагин позволяет получать сертификаты из HashiCorp Vault и формировать ssl-контекст. Плагин также поддерживает формирование ssl-контекста на основе хранилищ сертификатов-файлов.

Подключение плагина#

  1. В classpath SMBX-брокера должны быть добавлен jar-файл плагина.

  2. В файле конфигурации broker.xml в части настройки плагинов необходимо добавить следующие настройки:

    <broker-plugins>
    ...
        <broker-plugin class-name="ru.sbt.ss.artemis.ssl.context.factory.plugin.VaultSslContextPlugin">
            <property key="CONFIGURATION_FILE_LOCATION" value="path_to_config_file"/> - путь до конфигурационного файла с настройками для подключения к HashiCorp Vault и создания ssl-context 
            <property key="FACTORY_PRIORITY" value="12"/> - необязательный параметр, устанавливает приоритетность фабрики из плагина. Стандартное значение: 20
            <property key="WEB_CONSOLE_PORT" value="1234"/> - необязательный параметр, определяет на каком порту будет развернута web-консоль SMBX. Если настройка не указана, то значение по умолчанию — 8161
            <property key="WEB_CONSOLE_CLIENT_AUTH" value="false"/> - необязательный параметр, значение по умолчанию — true
        </broker-plugin>
    ...
    </broker-plugins>

  1. В конфигурационном файле должны быть прописаны настройки, указанные в таблицах ниже.

  2. В настройке аксептора необходимо обязательно явно указать параметр keyStorePath, который должен совпадать со значением, указанным в настройке ssl.keystore.location, находящейся в конфигурационном файле данного плагина.

<acceptors>
    <acceptor name="acceptorName">tcp://host:port?
        ...
        sslEnabled=true;
        enabledProtocols=TLSv1.2,TLSv1.3;
        keyStorePath=path_to_keystore_vault.jks;
        verifyHost=false;
        needClientAuth=true;
        ...
    </acceptor>
</acceptors>

<connectors>
    <connector name="connectorName">tcp://host:port?...sslEnabled=true;enabledProtocols=TLSv1.2,TLSv1.3;verifyHost=false</connector>
</connectors>

Параметры для формирования ssl-контекста c использованием HashiCorp Vault#

Имя

Описание

Значение по умолчанию

ssl.keystore.location

Расположение хранилища сертификатов, полученных из Vault

ssl.keystore.type

Тип хранилища сертификатов, полученных из Vault

JKS

ssl.keystore.mode

Права доступа к файлу хранилища сертификатов в POSIX формате, «644» или «w-r–r–»

ssl.truststore.location

Расположение хранилища доверенных сертификатов, полученных из Vault

ssl.truststore.type

Тип хранилища доверенных сертификатов, полученных из Vault

JKS

ssl.truststore.mode

Права доступа к файлу хранилища доверенных сертификатов в POSIX формате, «644» или «w-r–r–»

ssl.protocol

Версия протокола TLS

TLSv1.2

ssl.endpoint.identification.algorithm

Алгоритм проверки хоста подключения

HTTPs

ssl.conscrypt

Использование библиотеки Conscrypt

false

ssl.allowed.dn

Белый список доверенных DN

ssl.allowed.dn.file

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

ssl.keystore.certificate.chain.location

Расположение сертификата, полученного из Vault

ssl.keystore.key.location

Расположение приватного ключа сертификата, полученного из Vault

ssl.truststore.certificates.location

Расположение файла с доверенными сертификатами, полученными из Vault

ssl.keystore.certificate.chain.mode

Права доступа к файлу сертификата в POSIX формате, «644» или «w-r–r–»

ssl.keystore.key.mode

Права доступа к файлу приватного ключа сертификата в POSIX формате, «644» или «w-r–r–»

ssl.truststore.certificates.mode

Права доступа к файлу с доверенными сертификатами в POSIX формате, «644» или «w-r–r–»

security.encoding.class

Класс для расшифровки паролей

ru.sbt.ss.password.BaseEncryptor

security.encoding.key

Ключ для расшифровки паролей конфигурации

ssl.vault.address

Адрес подключения к Vault, обязательный параметр

ssl.vault.auth.type

Тип алгоритма аутентификации в Vault: approle, token, password, certificate, Kubernetes

approle

ssl.vault.auth.mount

Путь до API аутентификации в Vault

ssl.vault.auth.role.id

Идентификатор роли приложения при ssl.vault.auth.type=approle

ssl.vault.auth.secret.id

Секрет роли приложения при ssl.vault.auth.type=approle

ssl.vault.auth.token

Токен для подключения к Vault при ssl.vault.auth.type=token

ssl.vault.auth.username

Имя пользователя для подключения к Vault при ssl.vault.auth.type=password

ssl.vault.auth.password

Пароль пользователя для подключения к Vault при ssl.vault.auth.type=password

ssl.vault.auth.rolename

Роль для подключения к Vault при ssl.vault.auth.type=kubernetes

ssl.vault.auth.jwt

Service account jwt для подключения к Vault при ssl.vault.auth.type=kubernetes. Значение с префиксом «env:» - будет браться из переменных среды, с префиксом «file:» - будет браться из файла

ssl.vault.tls.enable

Включение протокола TLS при подключении к Vault

true

ssl.vault.tls.<параметр SSLContextBuilder>

Параметры для создания SSLContext при подключении по HTTPS к Vault

ssl.vault.namespace

Пространство имен в Vault

ssl.vault.pki.mode

Режим выпуска сертификатов: pki, kv

pki

ssl.vault.pki.mount

Путь до API движка выпуска сертификатов в Vault

pki

ssl.vault.pki.role.name

Имя роли в движке выпуска сертификатов в Vault, обязательный параметр

ssl.vault.pki.common.name

Значение поля CN в выпускаемом сертификате

ssl.vault.pki.email

Электронный адрес владельца сертификата, задается при использовании Secret Manager

ssl.vault.pki.alt.names

Список хостов через запятую для поля SAN сертификата

ssl.vault.pki.alt.ip

Список IP адресов через запятую для поля SAN сертификата

ssl.vault.pki.ttl

Параметр TTL для выпускаемого сертификата

ssl.vault.pki.csr

Запрос на сертификат в формате PEM

ssl.vault.pki.csr.path

Путь до файла с запросом на выпуск нового сертификата

ssl.vault.pki.trust.only

Признак формирования SSLContext только с использованием хранилища доверенных сертификатов

ssl.vault.pki.max.wait.time

Максимальное время ожидания момента валидности полученного сертификата в миллисекундах

10000

ssl.vault.pki.crl.enable

Включение проверки попадания сертификата в список отозванных

true

ssl.vault.secret.path

Путь до Key-Value секрета с пароля для хранилищ сертификатов ssl.keystore.location и ssl.truststore.location

ssl.vault.secret.key

Имя поля с паролем от ключа

ssl.vault.secret.keystore

Имя поля с паролем от хранилища сертификатов ssl.keystore.location

ssl.vault.secret.truststore

Имя поля с паролем от хранилища сертификатов ssl.truststore.location

ssl.vault.pem.path

Путь до Key-Value c pem сертификатом и приватным ключем для него

ssl.vault.pem.name

Имя поля pem сертификата

ssl.vault.pem.key

Имя поля приватного ключа

ssl.vault.pem.trust.path

Путь до Key-Value секрета c доверенными сертификатами в формате PEM

ssl.vault.pem.trust.aliases

Список ключей в секрете, содержимое которых необходимо загрузить в хранилище доверенных сертификатов, разделитель запятая. Загружает только те сертификаты, которые будут найдены по указанным alias, отсутствующие в Vault алиасы будут проигнорированы. Если один из сертификатов будет клиентский/серверный, то он добавится в truststore.jks с остальными сертификатами. Если в сертификате в Vault будет несколько ключей, то в jks добавится только первый указанный сертификат.

ssl.vault.before.expire

Промежуток времени до истечения сертификата для его перевыпуска в формате java.time.Duration

PT0S

ssl.vault.alias.ca

Префикс идентификатора сертификата CA Vault - при нескольких сертификатах идентификатор будет формироваться объединением префикса и номера сертификата в цепочке

ca

ssl.vault.alias.key

Идентификатор ключа и сертификата, выпущенных Vault

key

ssl.vault.engine.version

Версия Key-Value хранилища секретов

2

ssl.vault.retries

Количество попыток подключения к Vault

5

ssl.vault.retry.interval

Интервал между попыток подключения к Vault в миллисекундах

500

ssl.vault.timeout

Тайм-аут запроса к Vault в секундах

3

Параметры для формирования ssl-контекста на основе хранилищ сертификатов-файлов (без использования HashiCorp Vault)#

Имя

Описание

Значение по умолчанию

ssl.key.password

Пароль от ключа

ssl.keystore.location

Расположение хранилища сертификатов

ssl.keystore.password

Пароль от хранилища сертификатов

ssl.keystore.type

Тип хранилища сертификатов

JKS

ssl.truststore.location

Расположение хранилища доверенных сертификатов

ssl.truststore.password

Пароль от хранилища доверенных сертификатов

ssl.truststore.type

Тип хранилища доверенных сертификатов

JKS

ssl.protocol

Версия протокола TLS

TLSv1.2

ssl.endpoint.identification.algorithm

Алгоритм проверки host подключения

HTTPs

ssl.conscrypt

Использование библиотеки Conscrypt

false

ssl.allowed.dn

Белый список доверенных DN

ssl.allowed.dn.file

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

security.encoding.class

Класс для расшифровки паролей

ru.sbt.ss.password.DefaultEncoder

security.encoding.key

Ключ для расшифровки паролей конфигурации

ssl.keystore.certificate.chain.location

Расположение сертификата, полученного из Vault

ssl.keystore.key.location

Расположение приватного ключа сертификата, полученного из Vault

ssl.truststore.certificates.location

Расположение файла с доверенными сертификатами, полученными из Vault

Дополнительный параметр для получения cluster-password из HashiCorp Vault#

Имя

Описание

Значение по умолчанию

secret.artemis.cluster.password

Пароль от Artemis-кластера

–

  1. Использование secret.artemis.cluster.password совместно с настройками для формирования ssl-контекста с использованием HashiCorp Vault:

    • secret.artemis.cluster.password=vault:keyPath:keySecret, где vault — обязательный префикс, keyPath — путь до секрета, keySecret — имя поля с кластерным паролем.

Признаком формирования ssl-контекста без использования HashiCorp Vault является отсутствие настроек с префиксом ssl.vault (достаточно отсутствие настройки ssl.vault.address).

Если пароль от кластера задается в настройках данного плагина, то настройка <cluster-password>...</cluster-password>, находящаяся в broker.xml, должна быть представлена в следующем виде:

<cluster-password>vault:secret.artemis.cluster.password</cluster-password>

Особенности применения#

При использовании данного плагина необходимо удалять настройку c тегом <web>...</web> в файле bootstrap.xml.