29.3.2 The Keyring Service

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.

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.

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:

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:

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:

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:

Return value:

Returns 0 for success, 1 for failure.