Kafka-encryption-ott-interceptor#

Интерсептор для плавного перехода с kafka-ott-signature-interceptor на kafka-encryption-interceptor. Целевым решением для подписи сообщений является kafka-encryption-interceptor.

Описание модуля#

Представляет собой гибридный Kafka-интерсептор, разработанный для бесшовного перехода от старого механизма подписи сообщений (kafka-ott-signature-interceptor) к новому (kafka-encryption-interceptor) — шифрованию и подписи на основе симметричных ключей.

Так как у kafka-ott-signature-interceptor и kafka-encryption-interceptor разные форматы заголовков, при прямом переходе возможны ошибки совместимости между старыми и новыми клиентами.

kafka-encryption-ott-interceptor поддерживает оба формата заголовков:

  • Добавляет оба набора заголовков к исходящим сообщениям.

  • Умеет читать сообщения от любого из двух интерсепторов.

kafka-encryption-ott-interceptor позволяет перейти на новый интерсептор без остановки системы. Подходит для всех используемых вариантов решений.

Последовательность выполнения#

Этапы перехода#

  1. Все производители и потребители асинхронно подключают kafka-encryption-ott-interceptor. Конфигурация интерсептора включает параметры обоих механизмов (encryption и OTT).

  1. К новым исходящим сообщениям прикрепляются два набора заголовков.

    ВАЖНО! kafka-encryption-ott-interceptor должен настраиваться только в режиме signature. При режиме encryption тело сообщения будет зашифровано и kafka-ott-signature-interceptor не сможет проверить подпись.

  2. Старые и новые клиенты читают и проверяют сообщения.

  3. Количество сообщений, подписываемых kafka-ott-signature-interceptor, сокращается.

  1. Поэтапно отключается OTT-часть. Режим интерсептора меняется на encryption.

  2. Осуществляется полный переход на интерсептор kafka-encryption-interceptor.

Архитектура и логика работы#

Producer (отправка сообщений)#

Producer работает по следующей логике:

  1. Запрашивает ОТТ-токен (как в kafka-ott-signature-interceptor).

  2. Подписывает тело сообщения:

    • с помощью ОТТ-токена (добавляет заголовки kafka-ott-signature-interceptor);

    • с помощью симметричного ключа (добавляет заголовки kafka-encryption-interceptor).

  3. Отправляет сообщение с заголовками двух типов.

Consumer (чтение сообщений)#

Consumer работает по следующей логике:

  1. Проверяет наличие заголовков:

    • Если имеются encryption-заголовки, то проверяется подпись через симметричный ключ.

    • Если encryption-заголовки отсутствуют или произошла ошибка при их проверке, то проверяется подпись через ОТТ.

  2. Если одна из подписей валидна, сообщение считается корректным.

  3. При ошибке чтения подписей поддерживается настраиваемое поведение.

Поддерживаемые режимы#

Название

Описание

encrypt

Шифрование сообщения

signature

Подпись сообщения (encrypt и OTT)

ВАЖНО! В текущей версии kafka-encryption-ott-interceptor работает только в режиме подписи (signature), режим encrypt не поддерживается.

Таблица параметров#

kafka-encryption-ott-interceptor поддерживает параметры обоих интерсепторов.

ВАЖНО! Интерсептор использует в качестве транзитивной зависимости библиотеку sbp.com.sbt.ott:ott-jsonrpc-hb-client для генерации и валидации токенов безопасности, которая не входит в состав компонента EVTD. Данная библиотека относится к серверной части ОТТ (ОТТ-сервис). Подробнее в документации продукта OTT (Platform V One-Time-Token) и его компонента OTTS.

kafka-encryption-ott-interceptor не изменяет параметры, переданные ему из конфигурации. Все параметры ОТТ-клиента c префиксом .ott., указанные в конфигурационных файлах, принимаются как есть, и интерсептор не имеет логики переопределения или обработки этих параметров.

Все параметры ОТТ-клиента c префиксом .ott., указанные в конфигурационных файлах интерсептора, относятся к ОТТ-клиенту sbp.com.sbt.ott:ott-jsonrpc-hb-client и принимаются как есть. Интерсептор не имеет логики переопределения или обработки каких-то параметров.

Следует дополнительно уточнить значение параметра interceptor.signature.ott.authz.realm для автоматизированной системы (АС).

Параметр

Дефолтное значение

Описание

Источник

interceptor.signature.mode

failOnValue

Поведение при ошибке: failOnValue, filter, failOnConsume

Общий

interceptor.signature.ott.module.id

—

ID модуля (alias сертификата) для ОТТ

OTT

interceptor.signature.ott.service.url

—

URL сервиса ОТТ

OTT

interceptor.signature.ott.service.hosts

—

Хосты ОТТ

OTT

interceptor.signature.ott.authz.realm

—

Realm авторизации

OTT

interceptor.encryption.algorithm

HmacSHA256

Алгоритм подписи (для режима encryption)

Encryption

interceptor.encryption.key.alias

—

Имя ключа для подписи

Encryption

interceptor.encryption.key.store.type

—

Тип хранилища: json, vault, transit

Encryption

interceptor.encryption.json.storage.location

—

Путь к JSON с ключами

Encryption

interceptor.encryption.mode.operation

signature

Режим: signature (использовать только его)

Encryption

interceptor.encryption.generate.key.password

true

Разрешить генерацию ключей из паролей

Encryption

interceptor.encryption.create.new.key

-

В режиме работы transit будет создан новый ключ. Если ключ с таким именем уже существует, будет создана новая версия ключа

Encryption

interceptor.encryption.json.storage.location

-

Путь до json-файла с ключами

Encryption

interceptor.encryption.storage.update.time

60 (значение в секундах)

Частота обновление ключей в локальном хранилище, если включен параметр interceptor.encryption.create.new.key и выбрано хранилище transit, будет происходить ротация ключа. Также можно настроить ротацию на стороне vault, тогда параметр interceptor.encryption.create.new.key требуется выключить. Интерсептор будет приходить в vault забирать новую версию

Encryption

interceptor.signature.ott.certstore.type

PKCS12

Тип хранилища: JKS, PEM, PKCS12

OTT

interceptor.signature.ott.certstore.path

—

Путь к keystore

OTT

interceptor.signature.ott.trust.store.path

—

Путь к truststore

OTT

interceptor.signature.ott.client.tls

TLSv1.2

Версия TLS

OTT

interceptor.jmx.metrics.enabled

false

Включить JMX-метрики

Общий

interceptor.trace.logger.enabled

false

Включить логирование

Общий

Настройки подключения и авторизации плагина ssl-context-builder#

Полный список возможных параметров есть в документации плагина ssl-context-builder

Параметр

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

Описание

ssl.vault.address

Адрес Vault

ssl.vault.auth.type

approle

Тип авторизации: approle, token, password, certificate, kubernetes

ssl.vault.tls.enable

true

Включить TLS для подключения к Vault

ssl.vault.tls.keystore.location

Путь к keystore для TLS

ssl.vault.tls.keystore.password

Пароль от keystore

ssl.vault.tls.truststore.location

Путь к truststore

ssl.vault.tls.truststore.password

Пароль от truststore

ssl.vault.pki.mode

pki

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

ssl.vault.namespace

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

ssl.vault.engine.version

2

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

Примеры конфигурации#

Пример конфигурации Kafka Producer (json-хранилище)#

# Подключение интерсептора
interceptor.classes=ru.sbt.ss.kafka.encryption.ott.interceptor.EncryptionOttProducerInterceptor
# === Настройки OTT ===
interceptor.signature.ott.service.url=https://service/ott-service/rest/token
interceptor.signature.ott.service.hosts=ott-service:443
interceptor.signature.ott.module.id=ott-test-moduleA
interceptor.signature.ott.authz.realm=mmt
interceptor.signature.ott.service.cert.alias=ott-service
interceptor.signature.ott.certstore.type=JKS
interceptor.signature.ott.certstore.path=config/jks/ott-test-moduleA.p12
interceptor.signature.ott.trust.store.path=config/jks/truststore.p12
interceptor.signature.ott.certstore.pwd={password}
interceptor.signature.ott.certstore.private.key.pwd={password}
interceptor.signature.ott.trust.store.pwd={password}
interceptor.signature.ott.client.tls=TLSv1.2
interceptor.signature.ott.request.add.subject=urn:sbrf:names:pprb:1.0:module:id#ott-test-moduleA
interceptor.signature.ott.request.add.action=urn:sbrf:names:pprb:1.0:action:id#publish
interceptor.signature.ott.request.add.resource=urn:sbrf:names:pprb:1.0:api:interface:fullname#TOPIC
interceptor.signature.ott.request.add.environment.realm=ott:realm#synapse
# === Настройки Encryption ===
interceptor.encryption.mode.operation=signature
interceptor.encryption.algorithm=HmacSHA256
interceptor.encryption.key.alias=hmac-key-256
interceptor.encryption.key.store.type=json
interceptor.encryption.json.storage.location=/keys/encryption-keys.json
interceptor.encryption.generate.key.password=true
# === Поведение при ошибках ===
interceptor.signature.mode=failOnValue
interceptor.encryption.mode=failOnValue
# === Дополнительно ===
interceptor.jmx.metrics.enabled=true
interceptor.trace.logger.enabled=true

Пример конфигурации Kafka Consumer (json-хранилище)#

# Подключение интерсептора
interceptor.classes=ru.sbt.ss.kafka.encryption.ott.interceptor.EncryptionOttConsumerInterceptor
# === Настройки OTT ===
interceptor.signature.ott.service.url=https://service/ott-service/rest/token
interceptor.signature.ott.service.hosts=ott-service:443
interceptor.signature.ott.module.id=ott-test-moduleA
interceptor.signature.ott.authz.realm=mmt
interceptor.signature.ott.service.cert.alias=ott-service
interceptor.signature.ott.certstore.type=JKS
interceptor.signature.ott.certstore.path=config/jks/ott-test-moduleA.p12
interceptor.signature.ott.trust.store.path=config/jks/truststore.p12
interceptor.signature.ott.certstore.pwd={password}
interceptor.signature.ott.certstore.private.key.pwd={password}
interceptor.signature.ott.trust.store.pwd={password}
interceptor.signature.ott.client.tls=TLSv1.2
interceptor.signature.ott.request.add.subject=urn:sbrf:names:pprb:1.0:module:id#ott-test-moduleA
interceptor.signature.ott.request.add.resource=urn:sbrf:names:pprb:1.0:api:interface:fullname#TOPIC
interceptor.signature.ott.request.add.environment.realm=ott:realm#synapse
# === Настройки Encryption ===
interceptor.encryption.mode.operation=signature
interceptor.encryption.key.alias=hmac-key-256
interceptor.encryption.key.store.type=json
interceptor.encryption.json.storage.location=/keys/encryption-keys.json
interceptor.encryption.generate.key.password=true
# === Поведение при ошибках ===
interceptor.encryption.ott.mode=failOnValue
# === Дополнительно ===
interceptor.jmx.metrics.enabled=true
interceptor.trace.logger.enabled=true

Пример конфигурации Kafka Producer (transit-хранилище)#

Настройки плагина ssl-context-builder#
# Настройка vault 
ssl.vault.address = https://xx.xx.xx.x:xxxx
ssl.vault.auth.type = APPROLE
ssl.vault.auth.role.id = role
ssl.vault.auth.secret.id = secret

ssl.vault.tls.enable = true
ssl.vault.tls.keystore.location = config/vaultclient.jks
ssl.vault.tls.keystore.password = 123
ssl.vault.tls.key.password = 123
ssl.vault.tls.truststore.location = config/vaultclient.jks
ssl.vault.tls.truststore.password = 123
ssl.vault.transit.key.type=hmac-key
ssl.vault.transit.mount.path=transit
ssl.vault.transit.namespace=""
Подключение интерсептора#
interceptor.classes=ru.sbt.ss.kafka.encryption.ott.interceptor.EncryptionOttProducerInterceptor
# === Настройки OTT ===
interceptor.signature.ott.service.url=https://service/ott-service/rest/token
interceptor.signature.ott.service.hosts=ott-service:443
interceptor.signature.ott.module.id=ott-test-moduleA
interceptor.signature.ott.authz.realm=mmt
interceptor.signature.ott.service.cert.alias=ott-service
interceptor.signature.ott.certstore.type=JKS
interceptor.signature.ott.certstore.path=config/jks/ott-test-moduleA.p12
interceptor.signature.ott.trust.store.path=config/jks/truststore.p12
interceptor.signature.ott.certstore.pwd={password}
interceptor.signature.ott.certstore.private.key.pwd={password}
interceptor.signature.ott.trust.store.pwd={password}
interceptor.signature.ott.client.tls=TLSv1.2
interceptor.signature.ott.request.add.subject=urn:sbrf:names:pprb:1.0:module:id#ott-test-moduleA
interceptor.signature.ott.request.add.action=urn:sbrf:names:pprb:1.0:action:id#publish
interceptor.signature.ott.request.add.resource=urn:sbrf:names:pprb:1.0:api:interface:fullname#TOPIC
interceptor.signature.ott.request.add.environment.realm=ott:realm#synapse
# === Настройки Encryption ===
ssl.vault.transit.key.type=hmac-key
ssl.vault.transit.mount.path=transit
ssl.vault.transit.namespace=""
interceptor.encryption.algorithm=HmacSHA256
interceptor.encryption.key.alias=hmac-key-256
interceptor.encryption.create.new.key=true
interceptor.encryption.key.store.type=transit
interceptor.encryption.mode.operation=signature
interceptor.encryption.storage.update.time=60
# === Поведение при ошибках ===
interceptor.signature.mode=failOnValue
interceptor.encryption.mode=failOnValue
# === Дополнительно ===
interceptor.jmx.metrics.enabled=true
interceptor.trace.logger.enabled=true

Пример конфигурации Kafka Consumer (transit-хранилище)#

Настройки плагина ssl-context-builder#
# Настройка vault
ssl.vault.address = https://xx.xx.xx.x:xxxx
ssl.vault.auth.type = APPROLE
ssl.vault.auth.role.id = role
ssl.vault.auth.secret.id = secret

ssl.vault.tls.enable = true
ssl.vault.tls.keystore.location = config/vaultclient.jks
ssl.vault.tls.keystore.password = 123
ssl.vault.tls.key.password = 123
ssl.vault.tls.truststore.location = config/vaultclient.jks
ssl.vault.tls.truststore.password = 123
ssl.vault.transit.key.type=hmac-key
ssl.vault.transit.mount.path=transit
ssl.vault.transit.namespace=""
Подключение интерсептора#
interceptor.classes=ru.sbt.ss.kafka.encryption.ott.interceptor.EncryptionOttConsumerInterceptor
# === Настройки OTT ===
interceptor.signature.ott.service.url=https://service/ott-service/rest/token
interceptor.signature.ott.service.hosts=ott-service:443
interceptor.signature.ott.module.id=ott-test-moduleA
interceptor.signature.ott.authz.realm=mmt
interceptor.signature.ott.service.cert.alias=ott-service
interceptor.signature.ott.certstore.type=JKS
interceptor.signature.ott.certstore.path=config/jks/ott-test-moduleA.p12
interceptor.signature.ott.trust.store.path=config/jks/truststore.p12
interceptor.signature.ott.certstore.pwd={password}
interceptor.signature.ott.certstore.private.key.pwd={password}
interceptor.signature.ott.trust.store.pwd={password}
interceptor.signature.ott.client.tls=TLSv1.2
interceptor.signature.ott.request.add.subject=urn:sbrf:names:pprb:1.0:module:id#ott-test-moduleA
interceptor.signature.ott.request.add.resource=urn:sbrf:names:pprb:1.0:api:interface:fullname#TOPIC
interceptor.signature.ott.request.add.environment.realm=ott:realm#synapse
# === Настройки Encryption ===
interceptor.encryption.key.store.type=transit
interceptor.encryption.mode.operation=signature
interceptor.encryption.create.new.key=false
interceptor.encryption.storage.update.time=60
# === Поведение при ошибках ===
interceptor.encryption.ott.mode=failOnValue
# === Дополнительно ===
interceptor.jmx.metrics.enabled=true
interceptor.trace.logger.enabled=true

Пример конфигурации Kafka Producer (kv-хранилище)#

Настройки плагина ssl-context-builder#
# Настройка vault
ssl.vault.address = https://xx.xx.xx.x:xxxx
ssl.vault.auth.type = APPROLE
ssl.vault.auth.role.id = role
ssl.vault.auth.secret.id = secret

ssl.vault.tls.enable = true
ssl.vault.tls.keystore.location = config/vaultclient.jks
ssl.vault.tls.keystore.password = 123
ssl.vault.tls.key.password = 123
ssl.vault.tls.truststore.location = config/vaultclient.jks
ssl.vault.tls.truststore.password = 123
ssl.vault.secret.path = encryptions/keys
ssl.vault.kv.mount.path = kv2

Подключение интерсептора#

interceptor.classes=ru.sbt.ss.kafka.encryption.ott.interceptor.EncryptionOttProducerInterceptor
# === Настройки OTT ===
interceptor.signature.ott.service.url=https://service/ott-service/rest/token
interceptor.signature.ott.service.hosts=ott-service:443
interceptor.signature.ott.module.id=ott-test-moduleA
interceptor.signature.ott.authz.realm=mmt
interceptor.signature.ott.service.cert.alias=ott-service
interceptor.signature.ott.certstore.type=JKS
interceptor.signature.ott.certstore.path=config/jks/ott-test-moduleA.p12
interceptor.signature.ott.trust.store.path=config/jks/truststore.p12
interceptor.signature.ott.certstore.pwd={password}
interceptor.signature.ott.certstore.private.key.pwd={password}
interceptor.signature.ott.trust.store.pwd={password}
interceptor.signature.ott.client.tls=TLSv1.2
interceptor.signature.ott.request.add.subject=urn:sbrf:names:pprb:1.0:module:id#ott-test-moduleA
interceptor.signature.ott.request.add.action=urn:sbrf:names:pprb:1.0:action:id#publish
interceptor.signature.ott.request.add.resource=urn:sbrf:names:pprb:1.0:api:interface:fullname#TOPIC
interceptor.signature.ott.request.add.environment.realm=ott:realm#synapse
# === Настройки Encryption ===
interceptor.encryption.algorithm = AES_128/GCM/NoPadding
interceptor.encryption.key.alias = aes128
interceptor.encryption.key.store.type = vault
interceptor.encryption.mode.operation = signature
# === Поведение при ошибках ===
interceptor.signature.mode=failOnValue
interceptor.encryption.mode=failOnValue
# === Дополнительно ===
interceptor.jmx.metrics.enabled=true
interceptor.trace.logger.enabled=true

Пример конфигурации Kafka Consumer (kv-хранилище)#

Настройки плагина ssl-context-builder#

# Настройка vault
ssl.vault.address = https://xx.xx.xx.x:xxxx
ssl.vault.auth.type = APPROLE
ssl.vault.auth.role.id = role
ssl.vault.auth.secret.id = secret

ssl.vault.tls.enable = true
ssl.vault.tls.keystore.location = config/vaultclient.jks
ssl.vault.tls.keystore.password = 123
ssl.vault.tls.key.password = 123
ssl.vault.tls.truststore.location = config/vaultclient.jks
ssl.vault.tls.truststore.password = 123
ssl.vault.secret.path = encryptions/keys
ssl.vault.kv.mount.path = kv2

Подключение интерсептора#

interceptor.classes=ru.sbt.ss.kafka.encryption.ott.interceptor.EncryptionOttConsumerInterceptor
# === Настройки OTT ===
interceptor.signature.ott.service.url=https://service/ott-service/rest/token
interceptor.signature.ott.service.hosts=ott-service:443
interceptor.signature.ott.module.id=ott-test-moduleA
interceptor.signature.ott.authz.realm=mmt
interceptor.signature.ott.service.cert.alias=ott-service
interceptor.signature.ott.certstore.type=JKS
interceptor.signature.ott.certstore.path=config/jks/ott-test-moduleA.p12
interceptor.signature.ott.trust.store.path=config/jks/truststore.p12
interceptor.signature.ott.certstore.pwd={password}
interceptor.signature.ott.certstore.private.key.pwd={password}
interceptor.signature.ott.trust.store.pwd={password}
interceptor.signature.ott.client.tls=TLSv1.2
interceptor.signature.ott.request.add.subject=urn:sbrf:names:pprb:1.0:module:id#ott-test-moduleA
interceptor.signature.ott.request.add.resource=urn:sbrf:names:pprb:1.0:api:interface:fullname#TOPIC
interceptor.signature.ott.request.add.environment.realm=ott:realm#synapse
# === Настройки Encryption ===
interceptor.encryption.key.store.type = vault
interceptor.encryption.mode.operation = signature
# === Поведение при ошибках ===
interceptor.encryption.ott.mode=failOnValue
# === Дополнительно ===
interceptor.jmx.metrics.enabled=true
interceptor.trace.logger.enabled=true

Результат#

Выполнено подключение интерсептора Kafka-encryption-ott-interceptor.