29.3.2 The Keyring Service

Contents

MySQL Server supports a keyring service that enables internal server components and plugins to securely store sensitive information for later retrieval. This section describes how to use the keyring service functions to store, retrieve, and remove keys in the MySQL keyring keystore. An SQL interface to the keyring service functions is also available as a set of user-defined functions (UDFs); see Section 6.4.4.8, “General-Purpose Keyring Key-Management Functions”. For general keyring information, see Section 6.4.4, “The MySQL Keyring”.

The keyring service uses whatever underlying keyring plugin is enabled, if any. If no keyring plugin is enabled, keyring service calls fail.

A “record” in the keystore consists of data (the key itself) and a unique identifier through which the key is accessed. The identifier has two parts:

key_id: The key ID or name. key_id values that begin with mysql_ are reserved by MySQL Server.
user_id: The session effective user ID. If there is no user context, this value can be NULL. The value need not actually be a “user”; the meaning depends on the application.
Functions that implement the keyring UDF interface pass the value of CURRENT_USER() as the user_id value to keyring service functions.

The keyring service functions have these characteristics in common:

Each function returns 0 for success, 1 for failure.
The key_id and user_id arguments form a unique combination indicating which key in the keyring to use.
The key_type argument provides additional information about the key, such as its encryption method or intended use.
Keyring service functions treat key IDs, user names, types, and values as binary strings, so comparisons are case sensitive. For example, IDs of MyKey and mykey refer to different keys.

These keyring service functions are available:

my_key_fetch()
Deobfuscates and retrieves a key from the keyring, along with its type. The function allocates the memory for the buffers used to store the returned key and key type. The caller should zero or obfuscate the memory when it is no longer needed, then free it.
Syntax:
```
bool my_key_fetch(const char *key_id, const char **key_type,
                  const char* user_id, void **key, size_t *key_len)
```
Arguments:
- key_id, user_id: Null-terminated strings that as a pair form a unique identifier indicating which key to fetch.
- key_type: The address of a buffer pointer. The function stores into it a pointer to a null-terminated string that provides additional information about the key (stored when the key was added).
- key: The address of a buffer pointer. The function stores into it a pointer to the buffer containing the fetched key data.
- key_len: The address of a variable into which the function stores the size in bytes of the *key buffer.
Return value:
Returns 0 for success, 1 for failure.
my_key_generate()
Generates a new random key of a given type and length and stores it in the keyring. The key has a length of key_len and is associated with the identifier formed from key_id and user_id. The type and length values must be consistent with the values supported by the underlying keyring plugin. See Section 6.4.4.7, “Supported Keyring Key Types”.
Syntax:
```
bool my_key_generate(const char *key_id, const char *key_type,
                     const char *user_id, size_t key_len)
```
Arguments:
- key_id, user_id: Null-terminated strings that as a pair form a unique identifier for the key to be generated.
- key_type: A null-terminated string that provides additional information about the key.
- key_len: The size in bytes of the key to be generated.
Return value:
Returns 0 for success, 1 for failure.
my_key_remove()
Removes a key from the keyring.
Syntax:
```
bool my_key_remove(const char *key_id, const char* user_id)
```
Arguments:
- key_id, user_id: Null-terminated strings that as a pair form a unique identifier for the key to be removed.
Return value:
Returns 0 for success, 1 for failure.
my_key_store()
Obfuscates and stores a key in the keyring.
Syntax:
```
bool my_key_store(const char *key_id, const char *key_type,
                  const char* user_id, void *key, size_t key_len)
```
Arguments:
- key_id, user_id: Null-terminated strings that as a pair form a unique identifier for the key to be stored.
- key_type: A null-terminated string that provides additional information about the key.
- key: The buffer containing the key data to be stored.
- key_len: The size in bytes of the key buffer.
Return value:
Returns 0 for success, 1 for failure.

Find a PHP function

Document created the 26/06/2006, last modified the 26/10/2018
Source of the printed document:https://www.gaudry.be/en/mysql-rf-keyring-service.html

The infobrol is a personal site whose content is my sole responsibility. The text is available under CreativeCommons license (BY-NC-SA). More info on the terms of use and the author.

References

Manuel MySQL : https://dev.mysql.com/

These references and links indicate documents consulted during the writing of this page, or which may provide additional information, but the authors of these sources can not be held responsible for the content of this page.
The author This site is solely responsible for the way in which the various concepts, and the freedoms that are taken with the reference works, are presented here. Remember that you must cross multiple source information to reduce the risk of errors.

Contents Haut