Documentation Home
Security in MySQL
Related Documentation Download this Excerpt
PDF (US Ltr) - 1.6Mb
PDF (A4) - 1.6Mb
HTML Download (TGZ) - 328.1Kb
HTML Download (Zip) - 336.6Kb


Security in MySQL  /  ...  /  General-Purpose Keyring Function Reference

7.4.8.3 General-Purpose Keyring Function Reference

For each general-purpose keyring user-defined function (UDF), this section describes its purpose, calling sequence, and return value. For information about the conditions under which these UDFs can be invoked, see Section 7.4.8.2, “Using General-Purpose Keyring Functions”.

  • keyring_key_fetch(key_id)

    Given a key ID, deobfuscates and returns the key value.

    Arguments:

    • key_id: A string that specifies the key ID.

    Return value:

    Returns the key value as a string for success, NULL if the key does not exist, or NULL and an error for failure.

    Note

    Keyring values retrieved using keyring_key_fetch() are limited to 2,048 bytes, due to limitations of the UDF interface. A keyring value longer than that length can be stored using a keyring service function (see The Keyring Service), but if retrieved using keyring_key_fetch(), is truncated to 2,048 bytes.

    Example:

    mysql> SELECT keyring_key_generate('RSA_key', 'RSA', 16);
    +--------------------------------------------+
    | keyring_key_generate('RSA_key', 'RSA', 16) |
    +--------------------------------------------+
    |                                          1 |
    +--------------------------------------------+
    mysql> SELECT HEX(keyring_key_fetch('RSA_key'));
    +-----------------------------------+
    | HEX(keyring_key_fetch('RSA_key')) |
    +-----------------------------------+
    | 91C2253B696064D3556984B6630F891A  |
    +-----------------------------------+
    mysql> SELECT keyring_key_type_fetch('RSA_key');
    +-----------------------------------+
    | keyring_key_type_fetch('RSA_key') |
    +-----------------------------------+
    | RSA                               |
    +-----------------------------------+
    mysql> SELECT keyring_key_length_fetch('RSA_key');
    +-------------------------------------+
    | keyring_key_length_fetch('RSA_key') |
    +-------------------------------------+
    |                                  16 |
    +-------------------------------------+

    The example uses HEX() to display the key value because it may contain nonprintable characters. The example also uses a short key for brevity, but be aware that longer keys provide better security.

  • keyring_key_generate(key_id, key_type, key_length)

    Generates a new random key with a given ID, type, and length, and stores it in the keyring. The type and length values must be consistent with the values supported by the underlying keyring plugin, with the additional constraint that keys cannot be longer than 2,048 bytes (16,384 bits), due to limitations of the UDF interface. For the permitted types per plugin, see The Keyring Service.

    Arguments:

    • key_id: A string that specifies the key ID.

    • key_type: A string that specifies the key type.

    • key_length: An integer that specifies the key length in bytes. The maximum length is 2,048.

    Return value:

    Returns 1 for success, or NULL and an error for failure.

    Example:

    mysql> SELECT keyring_key_generate('RSA_key', 'RSA', 384);
    +---------------------------------------------+
    | keyring_key_generate('RSA_key', 'RSA', 384) |
    +---------------------------------------------+
    |                                           1 |
    +---------------------------------------------+
  • keyring_key_length_fetch(key_id)

    Given a key ID, returns the key length.

    Arguments:

    • key_id: A string that specifies the key ID.

    Return value:

    Returns the key length in bytes as an integer for success, NULL if the key does not exist, or NULL and an error for failure.

    Example:

    See the description of keyring_key_fetch().

  • keyring_key_remove(key_id)

    Removes the key with a given ID from the keyring.

    Arguments:

    • key_id: A string that specifies the key ID.

    Return value:

    Returns 1 for success, or NULL for failure.

    Example:

    mysql> SELECT keyring_key_remove('AES_key');
    +-------------------------------+
    | keyring_key_remove('AES_key') |
    +-------------------------------+
    |                             1 |
    +-------------------------------+
  • keyring_key_store(key_id, key_type, key)

    Obfuscates and stores a key in the keyring.

    Arguments:

    • key_id: A string that specifies the key ID.

    • key_type: A string that specifies the key type.

    • key: A string that specifies the key value.

    Return value:

    Returns 1 for success, or NULL and an error for failure.

    Example:

    mysql> SELECT keyring_key_store('new key', 'DSA', 'My key value');
    +-----------------------------------------------------+
    | keyring_key_store('new key', 'DSA', 'My key value') |
    +-----------------------------------------------------+
    |                                                   1 |
    +-----------------------------------------------------+
  • keyring_key_type_fetch(key_id)

    Given a key ID, returns the key type.

    Arguments:

    • key_id: A string that specifies the key ID.

    Return value:

    Returns the key type as a string for success, NULL if the key does not exist, or NULL and an error for failure.

    Example:

    See the description of keyring_key_fetch().


User Comments
User comments in this section are, as the name implies, provided by MySQL users. The MySQL documentation team is not responsible for, nor do they endorse, any of the information provided here.
Sign Up Login You must be logged in to post a comment.