Documentation Home
MySQL 5.7 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 38.1Mb
PDF (A4) - 38.1Mb
PDF (RPM) - 37.3Mb
HTML Download (TGZ) - 10.2Mb
HTML Download (Zip) - 10.3Mb
HTML Download (RPM) - 8.9Mb
Man Pages (TGZ) - 217.0Kb
Man Pages (Zip) - 329.9Kb
Info (Gzip) - 3.5Mb
Info (Zip) - 3.5Mb
Excerpts from this Manual

MySQL 5.7 Reference Manual  /  ...  /  The Keyring Service

28.3.2 The Keyring Service

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.5.4.6, “General-Purpose Keyring Key-Management Functions”. For general keyring information, see Section 6.5.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:

    my_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 values:

    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.5.4.5, “Supported Keyring Key Types”.

    Syntax:

    my_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 values:

    Returns 0 for success, 1 for failure.

  • my_key_remove()

    Removes a key from the keyring.

    Syntax:

    my_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 values:

    Returns 0 for success, 1 for failure.

  • my_key_store()

    Obfuscates and stores a key in the keyring.

    Syntax:

    my_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 values:

    Returns 0 for success, 1 for failure.


User Comments
Sign Up Login You must be logged in to post a comment.