5.5.6.2 The Keyring Service — MySQL 5.7

5.5.6.2 Сервис Keyring

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

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

Этот раздел описывает, как использовать функции сервиса keyring для хранения, извлечения и удаления ключей в хранилище ключей MySQL keyring. Для получения информации о SQL-интерфейсе, использующем функции, см. Раздел 6.4.4.8, “Общецелевые функции управления ключами keyring”. Для общей информации о keyring, см. Раздел 6.4.4, “Сервис MySQL Keyring”.

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

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

key_id: Идентификатор или имя ключа. key_id значения, начинающиеся с mysql_, зарезервированы MySQL Server.
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()

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

Синтаксис:
```
my_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()

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

Синтаксис:
```
my_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()

Удаляет ключ из хранилища ключей.

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

Возвращает 0 для успеха, 1 для неудачи.
my_key_store()

Зашифровывает и сохраняет ключ в хранилище ключей.

Синтаксис:
```
my_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 для неудачи.