7.6.9.2 The Keyring Service — MySQL 9.2

7.6.9.2 Сервис ключей

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

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

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

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

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

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

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

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

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

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

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.11 «Поддерживаемые типы и длины ключей 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 для ошибки.