Утилита шифрования Encryption_message_cli#

Консольная утилита предназначена для перешифрования сообщений находящихся на момент запуска утилиты в очередях. Процесс шифрования и дешифрования производится с помощью плагина шифрования EncryptionMessagePlugin только для durable-сообщений.

Запуск утилиты#

Для запуска утилиты из командной строки можно использовать стартовый скрипт запуска ./bin/encryption-message-cli.sh.

Команды скрипта запуска#

Скрипт запуска поддерживает следующие команды:

• run - запуск утилиты с передачей ей указанных аргументов командной строки и переменных окружения;

• start - старт утилиты или вывод сообщения о том, что утилита в данный момент уже запущена;

• stop - остановка утилиты;

• restart - перезапуск утилиты (остановка с последующим стартом);

• status - вывод статуса запуска утилиты.

Аргументы командной строки утилиты#

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

Обязательный аргумент#

--config    Путь до файла конфигурации приложения
-c          (в формате HOCON).

Необязательный аргумент#

--logback   Путь до файла конфигурации logback
-l          (в формате XML).

Пример запуска#

./bin/encryption-message-cli.sh run -c ./path/to/cli/config/enc-cli.conf -l ./path/to/logback/config/logback.xml

Конфигурация утилиты#

Для передачи дополнительных настроек утилите используется конфигурационный файл в формате HOCON.

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

encryptionMessageCli {
  # path to broker root dir (with ./enc, ./bin, ./lib ... )
  # REQUIRED
  brokerDirPath: "/u01/artemis/installDir/broker"

  # path to file with application UID
  # NOT required, default: 'uid'
  // uidFilePath: "./logs/uid"

  # relative path to broker.xml
  # NOT required, default: 'etc/broker.xml'
  // brokerXml: "etc/broker_VAULT.xml"

  # relative path to addresses.xml
  # NOT required, default: 'etc/addresses.xml'
  // addressesXml: "etc/addresses_more.xml"

  # broker connection url
  # NOT required, default: used artemis acceptor value from brokerXml
  // url: "tcp://srv-68-8.sy.dev.sbt:61616?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;amqpMinLargeMessageSize=102400;protocols=CORE,AMQP,MQTT;useEpoll=true;amqpCredits=1000;amqpLowCredits=300;amqpDuplicateDetection=true;supportAdvisory=false;suppressInternalManagementObjects=false;sslEnabled=true;enabledProtocols=TLSv1.2,TLSv1.3;keyStorePath=/u01/artemis/installdir/broker/ssl/artemis-vault-keystore.jks;keyStorePassword=qwe123;trustStorePath=/u01/artemis/installdir/broker/ssl/artemis-vault-keystore.jks;trustStorePassword=qwe123;verifyHost=false;needClientAuth=true"
  // url: "tcp://localhost:61616"

  # user/password
  # NOT required
  // user: "user"
  // password: "password"

  # max number of retries on failure during processing
  # NOT required, default: 10
  // retriesLimit: 5

  # max number of processing threads
  # NOT required, default: 25
  // threadPoolSize: 10

  # max number of parallel consumers (per each queue)
  # NOT required, default: 5
  // parallelConsumers: 3

  # header key name for re-encrypted messages
  # NOT required, default: 'HDR_RE_ENCRYPTED_MSG'
  // reEncryptedMessageHeaderKey: HDR_RE_ENCRYPTED_MSG

  # list of processing addresses (if same config option in encryptionMessagePlugin can't successfully extracted)
  # NOT required
  // addresses: ["queues.*.*", "test"]

  # list of excluded from processing addresses (used if same config option in encryptionMessagePlugin can't successfully extracted)
  # NOT required
  // excludedAddresses: ["DLQ", "ExpiryQueue"]

  # global waiting timeout for finishing all processing threads
  # NOT required, default: Inf
  // globalTimeout: "10 min"

  # consumer receive waiting timeout per each message, Inf - infinite waiting
  # NOT required, default: Inf
  // consumerReceiveTimeout: "1 sec"

  # processing threads pool shutdown timeout, Inf - infinite waiting
  # NOT required, default: "5 sec"
  // shutdownTimeout: "20 sec"

  # session options
  # NOT required, default:  (xa: false, autoCommitSends: false, autoCommitAcks: false, preAcknowledge: false, blockingCommit: false, ackBatchSize: 1)
  // xa: false
  // autoCommitSends: false
  // autoCommitAcks: false
  // preAcknowledge: false
  // blockingCommit: false
  // ackBatchSize: 1
}

Настройки конфигурации утилиты#

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

Описание работы утилиты#

В момент старта приложения происходит проверка наличия файла со значением UID текущего запуска (с путем из параметра uidFilePath).

Если файл отсутствует, производится полный цикл перешифрации всех сообщений. Приложение генерирует новое уникальное значение UID текущего запуска и сохраняет его во вновь создаваемом файле (с путем из параметра uidFilePath).

Если файл присутствует, утилита вычитывает «старое» значение UID и использует его в качестве UID текущего запуска.

Утилита подключается к очередям из списка очередей, требующих шифрования своих персистентных сообщений (список загружается из конфигурации плагина шифрования EncryptionMessagePlugin).

Цикл перешифрации сообщений#

Для каждой очереди происходит последовательная обработка:

• вычитывается очередное сообщение;

• к заголовкам сообщения добавляется служебный заголовок признака успешного перешифрования (с именем из параметра reEncryptedMessageHeaderKey и значением UID текущего запуска, хранимого в файле с путем из параметра uidFilePath);

• приоритет сообщения сбрасывается до минимального (0);

• сообщение записывается обратно в ту же очередь.

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

Может как запускаться несколько параллельных обработчиков на одну очередь, так и обрабатываться параллельно несколько очередей.

Общее число параллельных обработчиков задается значением параметра threadPoolSize. Максимальное количество параллельных обработчиков, приходящихся на одну очередь, задается значением параметра parallelConsumers.

Так, например:

• если threadPoolSize = 10 и parallelConsumers = 5, то при старте будет запущено по 5 обработчиков для двух первых очередей из списка (общим числом - 10), а по мере освобождения обработчики будут назначаться на следующие очереди из расчета не более 5 параллельно работающих на каждую.

• если threadPoolSize = 5 и parallelConsumers = 5, то при старте будет запущено 5 обработчиков для первой очереди из списка, а по мере освобождения обработчики будут назначаться на следующие очереди из расчета не более 5 параллельно работающих на каждую.

Параметры подключения к брокеру#

Настройки подключения к брокеру считываются утилитой из файла конфигурации брокера broker.xml. Для этого используется содержимое XML-элемента acceptor со значением атрибута name="artemis".

Пример:

<acceptor name="artemis">tcp://10.25.68.8:21616?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;amqpMinLargeMessageSize=102400;protocols=CORE,AMQP,MQTT;useEpoll=true;amqpCredits=1000;amqpLowCredits=300;amqpDuplicateDetection=true;supportAdvisory=false;suppressInternalManagementObjects=false;sslEnabled=true;enabledProtocols=TLSv1.2,TLSv1.3;keyStorePath=/u01/artemis_2/installdir/broker/ssl/artemis.jks;keyStorePassword=ENC(a0nDk25h1LG9swzDFn6rTJNAvgapn62gLcMIFoOo4cgyLnsQmwTFxj+QuV3k761K);trustStorePath=/u01/artemis_2/installdir/broker/ssl/artemis.jks;trustStorePassword=ENC(vlotZ5jvGVdXkCcPywqx96fu0gFjJx04EH1S23cW08vcrtN2D+4Jsj/OXknTystG);verifyHost=false;needClientAuth=true</acceptor>

Если не удается загрузить настройки из acceptor, утилита использует параметр url из конфигурации приложения.

Список адресов и очередей для перешифрования сообщений#

Список адресов и очередей, сообщения их которых будут перешифровываться утилитой, определяется следующим образом:

1. Загружается общий список всех используемых адресов и очередей из файла конфигурации адресов брокера addresses.xml.

2. Загружается список шаблонов адресов с шифрованием (encryptionMessagePlugin.addresses) и шаблонов исключений (encryptionMessagePlugin.excludedAddresses) из конфигурации плагина шифрования EncryptionMessagePlugin.

3. Если загрузить списки шаблонов из конфигурации плагина шифрования не удается, используются списки из параметров конфигурации приложения (addresses, excludedAddresses).

4. Из общего списка адресов и очередей брокера отфильтровываются только те адреса, которые соответствуют списку шаблонов адресов с шифрованием и не соответствуют списку шаблонов исключений.

Статус завершения#

В случае успешного завершения обработки сообщений со всех адресов и очередей, утилита формирует статус успешного завершения:

1. Производится создание архивной копии файла с UID текущего запуска приложения (с путем из параметра uidFilePath), при этом к его имени добавляется суффикс .backup.

2. Удаляется файл с UID текущего запуска приложения (с путем из параметра uidFilePath).

3. Процесс приложения утилиты завершается с кодом успеха - 0.

В случае неуспеха, утилита формирует статус ошибочного завершения:

1. Сохраняется неизменным файл с UID текущего запуска приложения (с путем из параметра uidFilePath).

2. Процесс приложения утилиты завершается с кодом ошибки - 1.

Повторный запуск в случае неуспешного завершения#

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

1. Для этого необходимо убедиться, что по пути, заданному параметром конфигурации uidFilePath, сохранился файл с UID предыдущего запуска (файл должен остаться после прошлого неуспешного завершения).

2. Повторный старт утилиты приводит к запуску цикла перешифрации сообщений со «старым» значением UID.

3. При этом перешифровываться будут только те сообщения, которые не успели обработаться во время предыдущего запуска, так как все успешно обработанные сообщения уже успели получить служебный заголовок со значением "старого" UID.

Таймаут завершения#

В настройках приложения может быть задан общий таймаут времени ожидания успешного завершения обработки сообщений из всех адресов globalTimeout.

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

По умолчанию таймаут завершения не используется (задана бесконечная длительность).

Формат значений продолжительности#

Параметры настроек globalTimeout и consumerReceiveTimeout должны содержать в качестве значений величины продолжительностей временного интервала.

Допустимы следующие варианты формата задания длительности (Duration):

• число трактуется, как продолжительность в миллисекундах.

• строка трактуется, как значение продолжительности с указанием единиц измерения. Для обозначения требуемых единиц измерения можно использовать:

  • d, day, days;

  • h, hr, hrs, hour, hours;

  • min, minute, minutes;

  • s, sec, secs, second, seconds;

  • ms, milli, millis, millisecond, milliseconds;

  • µs, micro, micros, microsecond, microseconds;

  • ns, nano, nanos, nanosecond, nanoseconds.

  • Можно использовать пробелы до, после и между частями строки.

  • Можно задавать бесконечную продолжительность, как:

    • Inf;

    • PlusInf;

    • +Inf;

    • Duration.Inf;

    • -Inf;

    • MinusInf;

    • Duration.MinusInf.