Documentation Home
Security in MySQL
Related Documentation Download this Excerpt
PDF (US Ltr) - 1.5Mb
PDF (A4) - 1.5Mb
HTML Download (TGZ) - 314.2Kb
HTML Download (Zip) - 323.0Kb


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()

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

    Syntax:

    STRING keyring_key_fetch(STRING key_id)

    Arguments:

    • key_id: The key ID as a string.

    Return values:

    Returns the key value 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()

    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.

    Syntax:

    STRING keyring_key_generate(STRING key_id, STRING key_type, INTEGER key_length)

    Arguments:

    • key_id: The key ID as a string.

    • key_type: The key type as a string.

    • key_length: The key length in bytes as an integer. The maximum length is 2,048.

    Return values:

    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()

    Given a key ID, returns the key length.

    Syntax:

    INTEGER keyring_key_length_fetch(STRING key_id)

    Arguments:

    • key_id: The key ID as a string.

    Return values:

    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()

    Removes the key with a given ID from the keyring.

    Syntax:

    INTEGER keyring_key_remove(STRING key_id)

    Arguments:

    • key_id: The key ID as a string.

    Return values:

    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()

    Obfuscates and stores a key in the keyring.

    Syntax:

    INTEGER keyring_key_store(STRING key_id, STRING key_type, STRING key)

    Arguments:

    • key_id: The key ID as a string.

    • key_type: The key type as a string.

    • key: The key value as a string.

    Return values:

    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()

    Given a key ID, returns the key type.

    Syntax:

    STRING keyring_key_type_fetch(STRING key_id)

    Arguments:

    • key_id: The key ID as a string.

    Return values:

    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
Sign Up Login You must be logged in to post a comment.