Хранилище секретов

Описание

Для реализации механизмов защиты параметров конфигурации, либо настройки функциональности TDE требуется наличие установленного и интегрированного решения хранилища секретов (KMS). В СУБД Pangolin реализована интеграция с:

Внешним решением:
- KMS HashiCorp Vault, который используется в качестве защищенного хранилища ключей засекречивания и настроек, а также, как система управления ключами.
  
  HashiCorp Vault – это инструмент с открытым исходным кодом, который обеспечивает безопасный и надежный способ хранения и распространения секретов, таких как ключи API, токены доступа и пароли.
- Системой хранения секретов ОдинКлюч.
  
  ОдинКлюч – это менеджер, который обеспечивает надежную защиту паролей и конфиденциальных данных (ключей прозрачного защитного преобразования данных TDE и\или параметров конфигурации).
Разработанным плагином-заменителем KMS, реализованным в виде библиотеки libkms_substitute_plugin.so.

KMS-заменитель реализует локальное файловое хранение секретов.

О настройке каждого из решений читайте в соответствующих разделах.

Для настройки подключения к хранилищу секретов используется утилита setup_kms_credentials.

В версии 6.3.0 реализована доработка обеспечения отказоустойчивости СУБД Pangolin при отказе хранилища секретов.

Утилита setup_kms_credentials

Сведения

Функциональность доступна только для редакций Enterprise и Enterprise для ERP-систем.

Утилита setup_kms_credentials:

обеспечивает настройку параметров подключения к хранилищу секретов;
упрощает процесс изменения параметров для работы с хранилищем секретов;
обеспечивает возможность обнаружения ошибок в параметрах подключения к хранилищу секретов на этапе конфигурирования доступа;
обеспечивает настройку системы для работы с хранилищем сертификатов;
упрощает использование утилиты в автоматизированных скриптах;
обеспечивает настройку проверки серверного сертификата хранилища секретов.

Если изменение параметров подключения к хранилищу секретов или сертификатов производится на работающем кластере, то выполните/запустите перечитывание конфигурационных параметров в компонентах кластера. Перезапуск кластера не требуется.

Утилита setup_kms_credentials используется для настройки соединения с хранилищем секретов (KMS) и сохранения параметров, необходимых для работы с ним. Она создает и при необходимости дополняет засекреченный файл enc_connection_settings.cfg, в котором хранятся параметры соединения к хранилищу и засекреченные учетные данные для этого соединения.

Файл enc_connection_settings.cfg располагается в директории /etc/pangolin-security-utilities/, владельцем является kmadmin_pg, группа pangolin_users, права -rw-r-----. Данный файл является настройкой конкретного узла кластера, не включается в резервные копии базы данных и хранится на сервере БД в засекреченном виде.

Дополнительные параметры, сохраняемые утилитой, имеют значения по умолчанию либо расширяют существующие типы данных. Это обеспечивает обратную совместимость формата засекреченного файла enc_connection_settings.cfg. Процесс добавления новых параметров при этом не меняется.

Установка

Установите rpm/deb-пакет содержащий утилиту безопасности setup_kms_credentials из каталога utilities дистрибутива:

Сведения

В случаеавтоматизированной установки СУБД данный пакет устанавливается по умолчанию.

SberLinux, РЕД ОС, CentOS
Astra Linux
Альт СП

sudo dnf install pangolin-security-utilities-{product_version}-{OS}.x86_64.rpm

sudo apt install pangolin-security-utilities-{product_version}_amd64.deb

sudo apt-get install pangolin-security-utilities-{product_version}-{OS}.x86_64.rpm

Подсказка

Пример заполненной команды:

cd distributive/utilities
sudo dnf install -y pangolin-security-utilities-6.7.6-sberlinux9.6.x86_64.rpm

Управление

Параметры для работы с хранилищем секретов

Вывод команды setup_kms_credentials --help:

 Options:
 --purpose      [-s]     Secret storage target { certs, secrets }, default = secrets
 --format       [-f]     Output format {json, table} in show mode, default = table
 --cluster      [-c]     Cluster id
 --host         [-h]     Domain name or ip address of Secret storage or several delimeted with ","
 --port         [-p]     Secret storage server port or several delimeted with ","
 --protocol     [-l]     Secret storage protocol { http (1), https (2) }, default = https
 --prefix       [-x]     Secrets path prefix, default = kv
 --suffix       [-u]     Secrets path suffix, default = empty, default value if provided without argument
 --namespace    [-n]     Secrets namespace, default = empty
 --type         [-t]     Auth type { userpass (1), approle (2) }
 --auth         [-a]     Auth point, default = empty
 --id           [-i]     Login or role id
 --root-ca      [-r]     File or folder with root certificate to check Secret storage server, default value if  provided without argument
 --storage      [-S]     Remote storage {Vault, OneKey}, default = Vault
 --skip-confirm          Secret's input, edit/delete record without confirmation
 --index                 Record's index for edit/delete mode
 --plain                 Plain output
 --no-check              Do not check credentials
 --debug                 Show debug messages in show mode
 --help                  This help

Параметры подключения передаются строкой вида:

/opt/pangolin-security-utilities/bin/setup_kms_credentials -c {cluster_id} -h {IP-Address} -p {port} -t {type_auth} -i {login}

К обязательным параметрам относятся:

-c – идентификатор кластера;
-h – IP-адрес узла;
-p – порт для подключения;
-t – тип авторизации;
-i – логин пользователя.

Тип авторизации (значение параметра -t) может принимать значения:

1 – для Userpass-авторизации;
2 – для Approle-авторизации.

примечание

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

Необязательные параметры:

--purpose - назначение (сертификаты certs или секреты secrets). Значение по умолчанию - secrets;
--format/-f - формат вывода (JSON, table - таблица). Значение по умолчанию - table;
--protocol/-l - протокол (http или https). Значение по умолчанию - https;
--prefix/-x - префикс пути. Значение по умолчанию - kv;
--suffix/-u - суффикс пути. По умолчанию передаваемое значение отсутствует.
--namespace/-n - пространство имен, по умолчанию не задано;
--auth/-a - точка авторизации, по умолчанию не передается;
--root-ca/-r - файл или папка с корневым сертификатом для проверки сервера хранилища секретов. При указании параметра без аргумента используется системное хранилище корневых сертификатов, установленное в операционной системе.
--skip-confirm - настройка ввода, определяющая наличие/отсутствие подтверждения для редактирования или удаления записи;
--index - индекс записи в режиме редактирования или удаления;
--plain - вывод информации;
--no-check - режим для отключения проверки параметров подключения к хранилищу секретов;
--debug - показать информацию для отладки;
--storage {onekey|vault} - определение типа системы хранения секретов (ОдинКлюч или Vault). Значение по умолчанию — vault.

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

примечание

Параметры root-ca и suffix являются локальными параметрами отдельной записи. Единственный глобальный параметр - cluster_id.

Утилита setup_kms_credentials обеспечивает возможность задавать значения параметров root-ca и suffix (оба параметра расположены в разделе credentials) для каждого отдельного подключения к хранилищу секретов/сертификатов.

Если файл /etc/pangolin-security-utilities/enc_connection_settings.cfg (/etc/pangolin-security-utilities/enc_connection_settings_cert.cfg) имеет старый формат, root-ca и suffix не заданы для конкретного подключения, то для обеспечения совместимости утилита дублирует эти два параметра для каждого отдельного подключения.

Если соединение было создано с помощью новой версии программы, а параметры root-ca и suffix не были заданы, то в файл с параметрами подключений к хранилищу секретов/сертификатов /etc/pangolin-security-utilities/enc_connection_settings.cfg (/etc/pangolin-security-utilities/enc_connection_settings_cert.cfg) будут записаны пустые значения для данных параметров. В выводе команды show для параметра root-ca будет указываться реально используемое (вычисляемое) значение данного параметра для каждой записи, а при выводе в JSON-формат значение по умолчанию будет соответствовать True в поле root_ca_calculated. В табличном выводе параметр root_ca_calculated не указывается.

Режимы работы утилиты

Режимы работы утилиты:

setup - ввести новый набор данных для хранилища (хранилищ) секретов или сертификатов, поведение по умолчанию;
show - показать текущий набор параметров подключений к хранилищам секретов/сертификатов (без паролей и идентификаторов секретов);
add - добавить новую запись в набор параметров подключений к хранилищам секретов/сертификатов;
delete - удалить запись из набора параметров подключений к хранилищам секретов/сертификатов по номеру записи;
deleteall – удалить файл enc_connection_settings.cfg (enc_connection_settings_cert.cfg), используется совместно с флагом --purpose;
edit - редактировать запись из набора параметров подключений к хранилищам секретов/сертификатов по номеру записи.

Удаление файла с параметрами подключения к хранилищу секретов/сертификатов

Утилита setup_kms_credentials удаляет файл /etc/pangolin-security-utilities/enc_connection_settings.cfg (/etc/pangolin-security-utilities/enc_connection_settings_cert.cfg), если он не содержит записей с параметрами подключения к хранилищу секретов/сертификатов сразу после операции удаления последней записи:

[kmadmin_pg@server-name ~]$ ls -lh /etc/pangolin-security-utilities/enc_connection_settings.cfg
-rw-r----- 1 kmadmin_pg pangolin_users 328 Nov  7 12:24 /etc/pangolin-security-utilities/enc_connection_settings.cfg

[kmadmin_pg@server-name ~]$ /opt/pangolin-security-utilities/bin/setup_kms_credentials delete --index=0 --skip-confirm

[kmadmin_pg@server-name ~]$ ls -lh /etc/pangolin-security-utilities/enc_connection_settings.cfg
ls: cannot access '/etc/pangolin-security-utilities/enc_connection_settings.cfg': No such file or directory

Если файл был удален, то при последующем создании новой записи с параметрами подключения к хранилищу секретов/сертификатов необходимо заново ввести значение cluster-id:

[kmadmin_pg@server-name ~]$ /opt/pangolin-security-utilities/bin/setup_kms_credentials add --cluster ZVO --host <IP-Address> --port 8200 --type 1 -i secmanLogIn --purpose secrets --no-check

Enter password:
**************

Confirm password:
**************

Credentials for Secret storage has been added successfully

При отсутствии файла enc_connection_settings.cfg (enc_connection_settings_cert.cfg) команда show утилиты setup_kms_credentials выводит сообщение No credentials specified или {} для JSON-формата.

Режим deletall

Режим deleteall используется совместно с флагом --purpose и удаляет файл /etc/pangolin-security-utilities/enc_connection_settings.cfg (/etc/pangolin-security-utilities/enc_connection_settings_cert.cfg).

Если в качестве значения флага установлено certs (deleteall --purpose=certs), то будет удален файл с параметрами подключения к хранилищу сертификатов enc_connection_settings_cert.cfg:

[kmadmin_pg@server-name ~]$ ls -lh /etc/pangolin-security-utilities/enc_connection_settings_cert.cfg
-rw-r--r-- 1 kmadmin_pg pangolin_users 376 May  6 11:32 /etc/pangolin-security-utilities/enc_connection_settings_cert.cfg

[kmadmin_pg@server-name ~]$ /opt/pangolin-security-utilities/bin/setup_kms_credentials deleteall --purpose=certs --skip-confirm

[kmadmin_pg@server-name ~]$ ls -lh /etc/pangolin-security-utilities/enc_connection_settings_cert.cfg
ls: cannot access '/etc/pangolin-security-utilities/enc_connection_settings_cert.cfg': No such file or directory

[kmadmin_pg@server-name ~]$ ls -lh /etc/pangolin-security-utilities/enc_connection_settings.cfg
-rw-r--r-- 1 kmadmin_pg pangolin_users 328 May  6 10:27 /etc/pangolin-security-utilities/enc_connection_settings.cfg

Если значение флага соответствует secrets (deleteall --purpose=secrets), то файл с параметрами подключения к хранилищу секретов /etc/pangolin-security-utilities/enc_connection_settings.cfg будет удален.

При попытке вызвать команду deleteall, когда файл с параметрами подключения к хранилищу секретов/сертификатов уже удален, команда не выполнится, а в консоль будет выведено сообщение File enc_connection_settings.cfg does not exist или File enc_connection_settings_cert.cfg does not exist, если флаг --purpose при вызове команды был установлен в значение certs.

Функция check_kms_is_on() (проверка доступности плагина взаимодействия с хранилищем секретов)

Специальная проверка, которая показывает, получилось ли выбрать такие значения из файла enc_connection_settions.cfg, содержащего варианты подключения к хранилищу секретов.

Функция проверяет, что плагин взаимодействия с KMS:

найден, доступен и подключен к KMS;
содержит в себе все функции API sKmsConnectionInitialized.

Пример использования:

SELECT check_kms_is_on();

При успешном подключении на выходе функции будет получено значение true, в противном случае — false.

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

Пример команды просмотра записей в табличном формате:

[user ~]$ /opt/pangolin-security-utilities/bin/setup_kms_credentials show --plain

Pangolin cluster ID: {cluster_id}
+-------------------------------------------------------------------------------------------------------------------------------------------------------------+
|  # | protocol |         host | port |     root CA path |  suffix | prefix | namespace |            cred type | auth point |              id |        status |
-----+----------+--------------+------+------------------+---------+--------+-----------+----------------------+------------+-----------------+----------------
|  0 |    https | <IP-Address> | 8200 | /pg_ssl/root_di1 | suffix1 |     kv |           | Userpass Auth Method |   userpass | adminencryption |            Ok |
|  1 |    https | <IP-Address> | 8200 | /pg_ssl/root_di2 | suffix2 |     kv |           | Userpass Auth Method |   userpass | adminencryption |            Ok |
+-------------------------------------------------------------------------------------------------------------------------------------------------------------+

[kmadmin_pg@server-name ~]$ /opt/pangolin-security-utilities/bin/setup_kms_credentials show --purpose=certs --plain

Pangolin cluster ID: test
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|  # | protocol |         host | port |     root CA path |  suffix |               prefix | namespace |            cred type | auth point |              id |  status |
-----+----------+--------------+------+------------------+---------+----------------------+-----------+----------------------+------------+-----------------+----------
|  0 |    https | <IP-Address> | 8203 | /pg_ssl/root_di1 |  pango1 | <certificate_prefix> |           | Userpass Auth Method |   userpass | adminencryption |      Ok |
|  1 |    https | <IP-Address> | 8203 | /pg_ssl/root_di2 |  pango2 | <certificate_prefix> |           | Userpass Auth Method |   userpass | adminencryption |      Ok |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Режим просмотра добавленных параметров подключения в JSON

Пример команды просмотра записей в JSON-формате:

[user ~]$ /opt/pangolin-security-utilities/bin/setup_kms_credentials show --format=json

{
	"cluster_id" : "test",
	"credentials" :
	[
		{
			"auth_point" : "userpass",
			"host" : {IP-Address},
			"id" : "qewr",
			"namespace" : "",
			"port" : {port},
			"prefix" : "kv",
			"protocol" : "HTTPS",
			"status" : "Storage error",
			"type" : "USER_PASS"
		},
		{
			"auth_point" : "userpass",
			"host" : {IP-Address},
			"id" : "qwer",
			"namespace" : "",
			"port" : {port},
			"prefix" : "kv",
			"protocol" : "HTTPS",
			"status" : "Storage error",
			"type" : "USER_PASS"
		}
	],
	"root_ca" : "/pg_ssl",
	"suffix" : ""
}

[user ~]$ /opt/pangolin-security-utilities/bin/setup_kms_credentials show --purpose=certs --format=json

{
        "cluster_id" : "test",
        "credentials" :
        [
                {
                        "auth_point" : "userpass",
                        "host" : {IP-Address},
                        "id" : "adminencryption",
                        "namespace" : "",
                        "port" : {port},
                        "prefix" : "certificate_prefix",
                        "protocol" : "HTTPS",
                        "root_ca" : "/pg_ssl/root_di1",
                        "root_ca_calculated" : "false",
                        "status" : "Ok",
                        "suffix" : "pango1",
                        "type" : "USER_PASS"
                },
                {
                        "auth_point" : "userpass",
                        "host" : {IP-Address},
                        "id" : "adminencryption",
                        "namespace" : "",
                        "port" : {port},
                        "prefix" : "certificate_prefix",
                        "protocol" : "HTTPS",
                        "root_ca" : "/pg_ssl/root_di2",
                        "root_ca_calculated" : "false",
                        "status" : "Ok",
                        "suffix" : "pango2",
                        "type" : "USER_PASS"
                }
        ]
}

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

Значение параметра secure_config_log_level задает уровень логирования, на котором будут выводиться сообщения о загрузке параметров из защищенного хранилища. Значение по умолчанию: LOG. Для уменьшения размера лога установить значение меньше чем log_min_messages.

Параметр может быть установлен как в файле конфигурации, так и командой:

ALTER SYSTEM SET secure_config_log_level = DEBUG1;

Диагностика

Если при добавлении новой записи в файл с параметрами подключения к хранилищу секретов/сертификатов, указать параметр cluster-id, отличный от уже записанного, утилита заканчивает работу с ошибкой:

Error: wrong cluster-id {wrong cluster-id}, credentials was set for {correct cluster-id}

Если при использовании режима deletall не указан флаг --purpose, то утилита закончит работу с ошибкой:

Error: --purpose not specified

При вызове setup_kms_credentials delete в случае не заданного индекса будет получено сообщение об ошибке:

Error:  Index to delete not specified

При вызове операции delete утилиты setup_kms_credentials на несуществующем хранилище будет получен вывод об ошибке:

Error: File enc_connection_settings.cfg does not exist

Внимание!

Новый формат файлов enc_connection_settings.cfg(enc_connection_settings_cert.cfg) обратно не совместим с более ранними версиями СУБД Pangolin.

Любые изменения в файле enc_connection_settings.cfg (enc_connection_settings_cert.cfg): создание, редактирование или удаление записи с параметрами подключения к хранилищу секретов/сертификатов, логируются в syslog:

May 21 15:44:07 <server_name> setup_kms_credentials[102792]: Credentials for Secret storage has been added successfully
May 21 15:44:50 <server_name> setup_kms_credentials[102831]: Credentials for Secret storage has been removed successfully

При выполнении команд setup, edit или add утилита setup_kms_credentials осуществляет проверку добавляемой или редактируемой записи с параметрами подключения.

В зависимости от результата проверки, дополнительно к сообщению о произведенном действии, будет выведено сообщение Credentials check ok, если проверка пройдена, или сообщение Credentials check failed, если проверка не пройдена.

Для отключения вывода сообщения будет использоваться существующий ключ --no-check.

Ключ --verify учитывает результат проверки при выполнении запрашиваемой операции: если проверка не пройдена, утилита заканчивает работу с ошибкой, запись не добавляется / не изменяется:

Credentials check failed
Error: Credentials for Secret storage not edited / added / set

Ключи --verify и --no-check не совместимы — утилита заканчивает работу с ошибкой, если указать их вместе:

Error: keys --verify and --no-check cannot be used together

KMS-заменитель

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

Плагин-заменитель KMS считывает данные для пары ключ-значение из двух файлов. Первый файл /etc/pangolin-security-utilities/kms_static_params.cfg содержит статические параметры, второй файл /etc/pangolin-security-utilities/kms_dynamic_params.cfg – динамические. Файл со статическими параметрами засекречен ключом, генерируемым из параметров сервера. Файл с динамическими параметрами может меняться. При внесении изменений необходимо обеспечить идентичность файлов с динамическими параметрами в кластере.

Если файлы /etc/pangolin-security-utilities/kms_static_params.cfg и /etc/pangolin-security-utilities/kms_dynamic_params.cfg не обнаружены или имеют некорректный формат, система будет считать, что используется реальный KMS, но учетные данные для подключения к нему не найдены.

Ограничения

При использовании KMS-заменителя ротация мастер-ключа и WAL-ключа запрещена.
Изменение параметров кластера, хранящихся в KMS, можно проводить только в выключенном режиме.
Чтобы инициализация базы данных с подключенным заменителем KMS выполнилась, необходимо, чтобы файлы /etc/pangolin-security-utilities/enc_connection_settings.cfg, kms_static_params.cfg и kms_dynamic_params.cfg либо все присутствовали, либо все отсутствовали.
Если в исходный файл с динамическими параметрами вносятся правки, то изменения необходимо выполнять на каждом узле.
В случае использования KMS-заменителя отключить прозрачное защитное преобразование данных (TDE) и защиту конфигурации утилитами tde_disabler и secure_config_disabler невозможно.
При включении в кластер нового узла актуальные файлы со статическими и динамическими параметрами должны быть таким же образом скопированы на него, файл со статическими параметрами засекречен с помощью утилиты засекречивания encrypt_params_file.

Подготовка файлов со статическими и динамическими параметрами

Сведения

Для работы с утилитами, представленными в данном разделе, требуется установить rpm/deb-пакет компонентаpangolin-security-utilities.

В случае автоматизированной установки СУБД данный пакет устанавливается по умолчанию.

Статические параметры

Файл со статическими параметрами /etc/pangolin-security-utilities/kms_static_params.cfg представляет собой простой текстовый документ, каждая строка которого содержит пару:

<имя ключа (параметра на KMS)> = <значение для данного ключа>

В файл со статическими параметрами должны быть помещены:
- меткa мастер-ключа;
- дата и время создания мастер-ключа actual_master_key_created;
- сгенерированные мастер-ключ, ключ засекречивания WAL и ключа засекречивания ключей для создания защищенного дампа.
Пример файла со статическими параметрами:
```
actual_master_key = master_key_value_00000000_000000_000
actual_master_key_created = {timestamp}
master_key_value_00000000_000000_000 = {hash}
wal_key = {hash}
secret_dump_key = {hash}
```
Где:
- {timestamp} – актуальные дата и время создания мастер-ключа, например, 20251101_070115_770. В случае, если установить в параметре actual_master_key_created значение 00000000_000000_000, то будет получена ошибка при вызове функции get_last_master_key_rotation_time():
```
ERROR:  Failed to get last master key rotation time
```
- {hash} – хеш ключей, полученный с помощью утилиты generate_encryption_key.
Сгенерировать master_key, wal_key и secret_dump_key возможно с помощью утилиты /opt/pangolin-security-utilities/bin/generate_encryption_key.

Файл /etc/pangolin-security-utilities/kms_static_params.cfg помещается на все узлы кластера во время настройки перед запуском утилиты setup_kms_credentials. С помощью утилиты засекречивания /opt/pangolin-security-utilities/bin/encrypt_params_file подготовленный файл со статическими параметрами необходимо закодировать на каждом узле кластера.

Динамические параметры

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

Файл с динамическими параметрами /etc/pangolin-security-utilities/kms_dynamic_params.cfg представляет собой простой текстовый документ, каждая строка которого содержит пару:

<имя ключа (параметра на KMS)> = <значение для данного ключа>

Пример файла с динамическими параметрами:

secure_config = on
is_tde_on = on
pg_ident +=
ssl = on
password_policies_enable = on
psql_encrypt_password = on
password_encryption = scram-sha-256
enabled_sec_admin_extra_auth_methods = cert
enabled_extra_auth_methods = cert
...

Подготовка файлов

Выполните шаги:

Создайте файлы для хранения статических и динамических параметров. В кластерной конфигурации повторите это действие на реплике:
```
sudo su
touch /etc/pangolin-security-utilities/kms_dynamic_params.cfg
touch /etc/pangolin-security-utilities/kms_static_params.cfg
chown kmadmin_pg:pangolin_users /etc/pangolin-security-utilities/kms_dynamic_params.cfg
chown kmadmin_pg:pangolin_users /etc/pangolin-security-utilities/kms_static_params.cfg
```
Ожидаемый результат:
```
ls -la /etc/pangolin-security-utilities
-rw-r--r--    1 kmadmin_pg pangolin_users     0 Nov  1 12:25 kms_dynamic_params.cfg
-rw-r--r--    1 kmadmin_pg pangolin_users     0 Nov  1 12:25 kms_static_params.cfg
```
Файл со статическими параметрами имеет простой текстовый формат, каждая строка содержит пару: <имя ключа> = <значение для данного ключа>. Файл может содержать следующие параметры:
- actual_master_key – метка актуального мастер-ключа;
- actual_master_key_created = <timestamp> – параметр, содержащий дату и время установки/ротации мастер-ключа в формате YYYYMMDD_HHMMSS_MMM, где YYYY – год, MM – месяц, DD – день, HH – часы в формате 24 часа, MM – минуты, SS – секунды, MMM - миллисекунды;
- master_key_value_00000000_000000_000 – значение мастер-ключа;
- wal_key – значение ключа засекречивания WAL-журналов;
- secret_dump_key – значение ключа кодирования ключей для создания дампа с помощью расширения secret_dump.
Примечание
При старте БД с использованием KMS-заменителя считывается параметрmaster_key_value_00000000_000000_000 из файла со статическими параметрами, поэтому значение метки мастер-ключа (actual_master_key) и имя мастер-ключа (master_key_value_<timestamp>) необходимо указать master_key_value_00000000_000000_000, иначе будет получена ошибка:
Parameter master_key_value_00000000_000000_000 does not exist in static KMS config file

Сгенерируйте 3 ключа (master_key, wal_key и secret_dump_key) с помощью утилиты generate_encryption_key на мастере:

sudo su - kmadmin_pg
/opt/pangolin-security-utilities/bin/generate_encryption_key

Ожидаемый результат:

Key was generated successfully. Key: {hash}
Key was generated successfully. Key: {hash}
Key was generated successfully. Key: {hash}

Заполните файл со статическими параметрами, укажите master_key, wal_key и secret_dump_key полученные на предыдущем шаге. В кластерной конфигурации повторите это действие на реплике:
```
sudo su - kmadmin_pg
vim /etc/pangolin-security-utilities/kms_static_params.cfg
```
Ожидаемый результат:
```
cat /etc/pangolin-security-utilities/kms_static_params.cfg

actual_master_key = master_key_value_00000000_000000_000
actual_master_key_created = {timestamp}
master_key_value_00000000_000000_000 = {hash}
wal_key = {hash}
secret_dump_key = {hash}
```
Где:
- {timestamp} – актуальные дата и время создания мастер-ключа, например, 20251101_070115_770. В случае, если установить в параметре actual_master_key_created значение 00000000_000000_000, то будет получена ошибка при вызове функции get_last_master_key_rotation_time():
```
ERROR:  Failed to get last master key rotation time
```
- {hash} – хеш ключей, полученный в пункте 2 с помощью утилиты generate_encryption_key.
Засекретьте файл со статическими параметрами утилитой encrypt_params_file. В кластерной конфигурации повторите это действие на реплике:
```
sudo su - kmadmin_pg
/opt/pangolin-security-utilities/bin/encrypt_params_file
```
Ожидаемый результат:
```
Start to encrypt file: /etc/pangolin-security-utilities/kms_static_params.cfg
File /etc/pangolin-security-utilities/kms_static_params.cfg was encrypted successfully
```
Заполните файл с динамическими параметрами. В кластерной конфигурации повторите это действие на реплике:
```
sudo su - kmadmin_pg
vim /etc/pangolin-security-utilities/kms_dynamic_params.cfg
```
Ожидаемый результат:
```
cat /etc/pangolin-security-utilities/kms_dynamic_params.cfg

secure_config = off
is_tde_on = off
allowed_servers =
...
```
Примечание
Если не требуется включение функциональности защиты конфигурации, то в файле с динамическими параметрами достаточно указать 2 параметраsecure_config = off и is_tde_on = on.

Обеспечение отказоустойчивости СУБД Pangolin при отказе хранилища секретов

Отказоустойчивость обеспечивается:

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

Засекреченный дамп хранится в виде файлов, недоступныx для перекодирования и использования на другой установке. Алгоритм засекречивания основывается на информации о системных параметрах и защищен от перекодирования.

Сведения

Функциональность доступна только для редакций Enterprise и Enterprise для ERP-систем.

Внимание!

Кеширование данных происходит только при включенных функциональностях обращения к хранилищу секретов. При отключении функциональности кеш сохраняется и инвалидируется по истечении vault_cache_expiration_timeout.

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

По умолчанию функциональность выключена. Включение происходит установкой параметра enable_vault_params_cache в значение on одновременно локально и в хранилище секретов. Локально функциональность может быть установлена как вручную, так и командой:

ALTER SYSTEM SET enable_vault_params_cache = on;

Внимание!

Перед включением функциональности убедитесь в том, что значение параметра secure_config = on.

Время жизни дампа контролируется параметром vault_cache_expiration_timeout. Параметр имеет значение по умолчанию (1 месяц), источником параметра является хранилище секретов, значение параметра — строка в формате interval.

Имеется возможность кеширования сертификатов. По умолчанию значение параметра - on:

SHOW enable_vault_certificates_cache;

Кеширование серверных и клиентских сертификатов в Pangolin Pooler настраиваются следующими параметрами:

server_tls_enable_vault_certificates_cache = 0
client_tls_enable_vault_certificates_cache = 0

Добавлен новый источник конфигурационных параметров vault cache, присваиваемый параметру при восстановлении его из кеша. Например, для enabled_extra_auth_methods при восстановлении из кеша:

SELECT source FROM pg_settings WHERE name = 'enabled_extra_auth_methods';
vault cache

Также имеется возможность настройки старта отсчета времени жизни кеша:

с его последнего успешного формирования;
c первого неуспешного взаимодействия с хранилищем.

Поведение настраивается параметром vault_cache_expiration_at_fault, значение по умолчанию on. Если параметр включен, то отсчет времени жизни ведется с первого неуспешного взаимодействия с хранилищем секретов/сертификатов.

Реализованы функции мониторинга оставшегося времени жизни кеша для сертификатов:

SELECT certificate_cache_expired_at();

И для конфигурационных параметров/ключей кодирования:

SELECT params_cache_expired_at();

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

при истечении времени жизни:
```
Vault cache will be expired at:
expired
```
если истечение времени жизни еще не началось:
```
Vault cache will be expired at:
expiration not started yet
```

во время истечения времени жизни:

Vault cache will be expired at:
years: \d*
month: \d*
days: \d*
hours: \d*
minutes: \d*
seconds: \d*

Также время жизни кеша может быть возвращено в формате interval:

select params_cache_expired_at_interval();
 params_cache_expired_at_interval
----------------------------------
 365 days 23:59:42.451545

select certificate_cache_expired_at_interval();
 params_cache_expired_at_interval
----------------------------------
 365 days 23:59:42.451545

В случае, соответствующем expired:

select params_cache_expired_at_interval();
 params_cache_expired_at_interval
----------------------------------
 00:00:00

select certificate_cache_expired_at_interval();
 params_cache_expired_at_interval
----------------------------------
 00:00:00

В случае, соответствующем expiration not started yet:

select params_cache_expired_at_interval();
 params_cache_expired_at_interval
----------------------------------
 -1 mons -1 days -00:00:00.000001
(1 row)

select certificate_cache_expired_at_interval();
 params_cache_expired_at_interval
----------------------------------
 -1 mons -1 days -00:00:00.000001
(1 row)

Функция, возвращающая признак работы от кеша сертификатов/параметров:

SELECT vault_cache_usage();

В зависимости от источника данных сообщение будет содержать признак cache или vault:

SELECT * FROM vault_cache_usage();

    cache     | source
--------------+--------
 params       | vault/cache
 certificates | vault/cache
(2 rows)

Поведение при отсутствии параметра secure_config в кластере:

В этом случае кластер считается невалидным и при возможности будет произведен запуск от кешированных параметров. В логах присутствуют соответствующие сообщения:

WARNING:  parameter "secure_config" does not exist on KMS
WARNING:  postgres: Try to restore cached parameters
LOG:  Enabled vault cache mode: enabled
WARNING:  Parameter secure_config restored from local cache

Сценарии использования

Доступны следующие сценарии с включенной и выключенной функциональностью:

При выключенной функциональности и успешном подключении – Преобразованные файлы дампа не создаются. База данных запускается успешно.
При выключенной функциональности и неуспешном подключении – Преобразованные файлы дампа не создаются. База данных не может запуститься, в логах появится ошибка подключения к хранилищу секретов.
При включенной функциональности и успешном подключении – Созданы преобразованные файлы дампа. База данных запускается штатно.
При включенной функциональности и неуспешном соединении – В случае наличия кеша по итогу успешного подключения ранее будут использоваться параметры кеша. При отсутствии кеша или его повреждении база данных не может начать свою работу и завершается с ошибкой в логе.

примечание
Сценарий под номером 4 аналогичен и для файлов сертификатов.

Другой причиной невозможности запуска базы данных является истечение срока службы данных (vault_cache_expiration_timeout). При этом СУБД Pangolin не будет остановлен, если vault_cache_expiration_timeout истек уже во время работы. Проверка происходит только при обращении к хранилищу секретов.

Причиной ошибки при запуске с включенной функциональностью может являться:

повреждение засекреченных параметров;
повреждение сохраненных засекреченных файлов сертификатов;
повреждение сохраненных засекреченных ключей;
смена параметров оборудования;
истечение срока давности кеша.

При включенной функциональности и отсутствии связи с хранилищем секретов Pangolin запускается успешно, так как использует полученный ранее кеш

В данном подразделе приведен пример отсутствия связи с хранилищем секретов, при включенной функциональности, СУБД запускается успешно, так как использует полученный ранее кеш.

Заблокируйте трафик с Хранилищем секретов, выполнив команду:
```
sudo iptables -A OUTPUT -d <IP-Address> -j DROP
```
Проверьте подключение к хранилищу секретов с помощью команды ping:
```
ping <IP-Address>
```
Ожидаемый результат: Связь с хранилищем секретов отсутствует.
Выполните перезапуск сервера:
```
systemctl --user restart postgresql
```
Ожидаемый результат: Перезапуск выполнен успешно.
Разблокируйте трафик:
```
sudo iptables -F
```
Проверьте подключение к хранилищу секретов:
```
ping <IP-Address>
```
Ожидаемый результат: Связь с хранилищем секретов восстановлена
```
PING <IP-Address> (<IP-Address>) 56(84) bytes of data.
64 bytes from <IP-Address>: icmp_seq=1 ttl=64 time=0.454 ms
```

Описание​

Утилита setup_kms_credentials​

Установка​

Управление​

Параметры для работы с хранилищем секретов​

Режимы работы утилиты​

Удаление файла с параметрами подключения к хранилищу секретов/сертификатов​

Режим deletall​

Функция check_kms_is_on() (проверка доступности плагина взаимодействия с хранилищем секретов)​

Режим просмотра добавленных параметров подключения​

Режим просмотра добавленных параметров подключения в JSON​

Задание уровня логирования сообщений о загрузке параметров из защищенного хранилища​

Диагностика​

KMS-заменитель​

Ограничения​

Подготовка файлов со статическими и динамическими параметрами​

Статические параметры​

Динамические параметры​

Подготовка файлов​

Обеспечение отказоустойчивости СУБД Pangolin при отказе хранилища секретов​

Сценарии использования​

При включенной функциональности и отсутствии связи с хранилищем секретов Pangolin запускается успешно, так как использует полученный ранее кеш​

Описание

Утилита setup_kms_credentials

Установка

Управление

Параметры для работы с хранилищем секретов

Режимы работы утилиты

Удаление файла с параметрами подключения к хранилищу секретов/сертификатов

Режим deletall

Функция check_kms_is_on() (проверка доступности плагина взаимодействия с хранилищем секретов)

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

Режим просмотра добавленных параметров подключения в JSON

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

Диагностика

KMS-заменитель

Ограничения

Подготовка файлов со статическими и динамическими параметрами

Статические параметры

Динамические параметры

Подготовка файлов

Обеспечение отказоустойчивости СУБД Pangolin при отказе хранилища секретов

Сценарии использования

При включенной функциональности и отсутствии связи с хранилищем секретов Pangolin запускается успешно, так как использует полученный ранее кеш