7.6.9.2 The Keyring Service — MySQL 8.4

7.6.9.2 Сервис Keyring

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

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

В этом разделе описывается, как использовать функции сервиса keyring для хранения, извлечения и удаления ключей в хранилище ключей MySQL keyring. Сведения об интерфейсе SQL, использующем функции, см. в разделе 8.4.4.12 «Функции управления ключами keyring общего назначения». Для общей информации о keyring см. раздел 8.4.4 «Сервис MySQL Keyring».

Сервис keyring использует любой поддерживаемый плагин keyring, если таковой имеется. Если плагин keyring не включён, вызовы сервиса keyring завершаются ошибкой.

«Запись» в хранилище ключей состоит из данных (сам ключ) и уникального идентификатора, по которому осуществляется доступ к ключу. Идентификатор имеет две части:

key_id: Идентификатор или имя ключа. key_id значения, начинающиеся с mysql_, зарезервированы сервером MySQL.
user_id: Эффективный идентификатор пользователя сессии. Если контекст пользователя отсутствует, это значение может быть NULL. Значение необязательно должно быть «пользователем»; его смысл зависит от приложения.

Функции, реализующие интерфейс функции keyring, передают значение CURRENT_USER() как значение user_id функциям сервиса keyring.

Функции сервиса keyring обладают следующими общими характеристиками:

Каждая функция возвращает 0 при успехе и 1 при ошибке.
Аргументы key_id и user_id образуют уникальную комбинацию, определяющую, какой ключ в keyring использовать.
Аргумент key_type предоставляет дополнительную информацию о ключе, такую как метод шифрования или предполагаемое использование.
Функции сервиса keyring обрабатывают идентификаторы ключей, имена пользователей, типы и значения как двоичные строки, поэтому сравнения чувствительны к регистру. Например, идентификаторы MyKey и mykey относятся к разным ключам.

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

my_key_fetch()

Дешифрует и извлекает ключ из keyring вместе с его типом. Функция выделяет память для буферов, используемых для хранения возвращаемого ключа и типа ключа. Вызывающая сторона должна обнулить или зашифровать память, когда она больше не нужна, а затем освободить её.

Синтаксис:
```
bool my_key_fetch(const char *key_id, const char **key_type,
                  const char* user_id, void **key, size_t *key_len)
```
Аргументы:
- key_id, user_id: Строки с нулевым завершением, которые в паре образуют уникальный идентификатор, указывающий, какой ключ извлечь.
- key_type: Адрес указателя буфера. Функция сохраняет в нём указатель на строку с нулевым завершением, содержащую дополнительную информацию о ключе (сохранённую при добавлении ключа).
- key: Адрес указателя буфера. Функция сохраняет в нём указатель на буфер, содержащий извлечённые данные ключа.
- key_len: Адрес переменной, в которую функция сохраняет размер буфера *key в байтах.
Значение возврата:

Возвращает 0 при успехе, 1 при ошибке.
my_key_generate()

Генерирует новый случайный ключ заданного типа и длины и сохраняет его в keyring. Длина ключа составляет key_len, и он ассоциирован с идентификатором, сформированным из key_id и user_id. Значения типа и длины должны соответствовать поддерживаемым значениям плагином keyring. См. раздел 8.4.4.10 «Поддерживаемые типы и длины ключей keyring».

Синтаксис:
```
bool my_key_generate(const char *key_id, const char *key_type,
                     const char *user_id, size_t key_len)
```
Аргументы:
- key_id, user_id: Строки с нулевым завершением, которые в паре образуют уникальный идентификатор генерируемого ключа.
- key_type: Строка с нулевым завершением, предоставляющая дополнительную информацию о ключе.
- key_len: Размер генерируемого ключа в байтах.
Значение возврата:

Возвращает 0 при успехе, 1 при ошибке.
my_key_remove()

Удаляет ключ из keyring.

Синтаксис:
```
bool my_key_remove(const char *key_id, const char* user_id)
```
Аргументы:
- key_id, user_id: Строки с нулевым завершением, которые в паре образуют уникальный идентификатор удаляемого ключа.
Значение возврата:

Возвращает 0 при успехе, 1 при ошибке.
my_key_store()

Шифрует и сохраняет ключ в keyring.

Синтаксис:
```
bool my_key_store(const char *key_id, const char *key_type,
                  const char* user_id, void *key, size_t key_len)
```
Аргументы:
- key_id, user_id: Строки с нулевым завершением, которые в паре образуют уникальный идентификатор сохраняемого ключа.
- key_type: Строка с нулевым завершением, предоставляющая дополнительную информацию о ключе.
- key: Буфер, содержащий данные сохраняемого ключа.
- key_len: Размер буфера key в байтах.
Значение возврата:

Возвращает 0 при успехе, 1 при ошибке.