8.6.5 MySQL Enterprise Encryption Component Function Descriptions

In releases from MySQL 8.0.30, MySQL Enterprise Encryption's functions are provided by the MySQL component component_enterprise_encryption. This reference describes those functions.

For information on upgrading to the new component functions provided by the MySQL component component_enterprise_encryption, and a list of the behavior differences between the legacy functions and the component functions, see Upgrading MySQL Enterprise Encryption.

The reference for the legacy functions in releases before MySQL 8.0.30 based on the openssl_udf shared library is Section 8.6.6, “MySQL Enterprise Encryption Legacy Function Descriptions”.

MySQL Enterprise Encryption functions have these general characteristics:

• For arguments of the wrong type or an incorrect number of arguments, each function returns an error.

• If the arguments are not suitable to permit a function to perform the requested operation, it returns NULL or 0 as appropriate. This occurs, for example, if a function does not support a specified algorithm, a key length is too short or long, or a string expected to be a key string in PEM format is not a valid key.

• The underlying SSL library takes care of randomness initialization.

The component functions only support the RSA encryption algorithm.

For additional examples and discussion, see Section 8.6.3, “MySQL Enterprise Encryption Usage and Examples”.

• asymmetric_decrypt(algorithm, data_str, priv_key_str)

  Decrypts an encrypted string using the given algorithm and key string, and returns the resulting plaintext as a binary string. If decryption fails, the result is NULL.

  For the legacy version of this function in use before MySQL 8.0.29, see Section 8.6.6, “MySQL Enterprise Encryption Legacy Function Descriptions”.

  By default, the component_enterprise_encryption function assumes that encrypted text uses the RSAES-OAEP padding scheme. The function supports decryption for content encrypted by the legacy openssl_udf shared library functions if the system variable enterprise_encryption.rsa_support_legacy_padding is set to ON (the default is OFF). When ON is set, the function also supports the RSAES-PKCS1-v1_5 padding scheme, as used by the legacy openssl_udf shared library functions. When OFF is set, content encrypted by the legacy functions cannot be decrypted, and the function returns null output for such content.

  algorithm is the encryption algorithm used to create the key. The supported algorithm value is 'RSA'.

  data_str is the encrypted string to decrypt, which was encrypted with asymmetric_encrypt().

  priv_key_str is a valid PEM encoded RSA private key. For successful decryption, the key string must correspond to the public key string used with asymmetric_encrypt() to produce the encrypted string. The asymmetric_encrypt() component function only supports encryption using a public key, so decryption takes place with the corresponding private key.

  For a usage example, see the description of asymmetric_encrypt().

• asymmetric_encrypt(algorithm, data_str, pub_key_str)

  Encrypts a string using the given algorithm and key string, and returns the resulting ciphertext as a binary string. If encryption fails, the result is NULL.

  For the legacy version of this function in use before MySQL 8.0.29, see Section 8.6.6, “MySQL Enterprise Encryption Legacy Function Descriptions”.

  algorithm is the encryption algorithm used to create the key. The supported algorithm value is 'RSA'.

  data_str is the string to encrypt. The length of this string cannot be greater than the key string length in bytes, minus 42 (to account for the padding).

  pub_key_str is a valid PEM encoded RSA public key. The asymmetric_encrypt() component function only supports encryption using a public key.

  To recover the original unencrypted string, pass the encrypted string to asymmetric_decrypt(), along with the other part of the key pair used for encryption, as in the following example:

  -- Generate private/public key pair
  SET @priv = create_asymmetric_priv_key('RSA', 2048);
  SET @pub = create_asymmetric_pub_key('RSA', @priv);
  
  -- Encrypt using public key, decrypt using private key
  SET @ciphertext = asymmetric_encrypt('RSA', 'The quick brown fox', @pub);
  SET @plaintext = asymmetric_decrypt('RSA', @ciphertext, @priv);

  Suppose that:

  SET @s = a string to be encrypted
  SET @priv = a valid private RSA key string in PEM format
  SET @pub = the corresponding public RSA key string in PEM format

  Then these identity relationships hold:

  asymmetric_decrypt('RSA', asymmetric_encrypt('RSA', @s, @pub), @priv) = @s

• asymmetric_sign(algorithm, text, priv_key_str, digest_type)

  Signs a digest string or data string using a private key, and returns the signature as a binary string. If signing fails, the result is NULL.

  For the legacy version of this function in use before MySQL 8.0.29, see Section 8.6.6, “MySQL Enterprise Encryption Legacy Function Descriptions”.

  algorithm is the encryption algorithm used to create the key. The supported algorithm value is 'RSA'.

  text is a data string or digest string. The function accepts digests but does not require them, as it is also capable of handling data strings of an arbitrary length. A digest string can be generated by calling create_digest().

  priv_key_str is the private key string to use for signing the digest string. It must be a valid PEM encoded RSA private key.

  digest_type is the algorithm to be used to sign the data. The supported digest_type values are 'SHA224', 'SHA256', 'SHA384', and 'SHA512' when OpenSSL 1.0.1 is in use. If OpenSSL 1.1.1 is in use, the additional digest_type values 'SHA3-224', 'SHA3-256', 'SHA3-384', and 'SHA3-512' are available.

  For a usage example, see the description of asymmetric_verify().

• asymmetric_verify(algorithm, text, sig_str, pub_key_str, digest_type)

  Verifies whether the signature string matches the digest string, and returns 1 or 0 to indicate whether verification succeeded or failed. If verification fails, the result is NULL.

  For the legacy version of this function in use before MySQL 8.0.29, see Section 8.6.6, “MySQL Enterprise Encryption Legacy Function Descriptions”.

  By default, the component_enterprise_encryption function assumes that signatures use the RSASSA-PSS signature scheme. The function supports verification for signatures produced by the legacy openssl_udf shared library functions if the system variable enterprise_encryption.rsa_support_legacy_padding is set to ON (the default is OFF). When ON is set, the function also supports the RSASSA-PKCS1-v1_5 signature scheme, as used by the legacy openssl_udf shared library functions. When OFF is set, signatures produced by the legacy functions cannot be verified, and the function returns null output for such content.

  algorithm is the encryption algorithm used to create the key. The supported algorithm value is 'RSA'.

  text is a data string or digest string. The component function accepts digests but does not require them, as it is also capable of handling data strings of an arbitrary length. A digest string can be generated by calling create_digest().

  sig_str is the signature string to be verified. A signature string can be generated by calling asymmetric_sign().

  pub_key_str is the public key string of the signer. It corresponds to the private key passed to asymmetric_sign() to generate the signature string. It must be a valid PEM encoded RSA public key.

  digest_type is the algorithm that was used to sign the data. The supported digest_type values are 'SHA224', 'SHA256', 'SHA384', and 'SHA512' when OpenSSL 1.0.1 is in use. If OpenSSL 1.1.1 is in use, the additional digest_type values 'SHA3-224', 'SHA3-256', 'SHA3-384', and 'SHA3-512' are available.

  -- Set the encryption algorithm and digest type
  SET @algo = 'RSA';
  SET @dig_type = 'SHA512';
  
  -- Create private/public key pair
  SET @priv = create_asymmetric_priv_key(@algo, 2048);
  SET @pub = create_asymmetric_pub_key(@algo, @priv);
  
  -- Generate digest from string
  SET @dig = create_digest(@dig_type, 'The quick brown fox');
  
  -- Generate signature for digest and verify signature against digest
  SET @sig = asymmetric_sign(@algo, @dig, @priv, @dig_type);
  SET @verf = asymmetric_verify(@algo, @dig, @sig, @pub, @dig_type);

• create_asymmetric_priv_key(algorithm, key_length)

  Creates a private key using the given algorithm and key length, and returns the key as a binary string in PEM format. The key is in PKCS #8 format. If key generation fails, the result is NULL.

  For the legacy version of this function in use before MySQL 8.0.29, see Section 8.6.6, “MySQL Enterprise Encryption Legacy Function Descriptions”.

  algorithm is the encryption algorithm used to create the key. The supported algorithm value is 'RSA'.

  key_length is the key length in bits. If you exceed the maximum allowed key length or specify less than the minimum, key generation fails and the result is null output. The minimum allowed key length in bits is 2048. The maximum allowed key length is the value of the enterprise_encryption.maximum_rsa_key_size system variable, which defaults to 4096. It has a maximum setting of 16384, which is the maximum key length allowed for the RSA algorithm. See Section 8.6.2, “Configuring MySQL Enterprise Encryption”.

  Note

  Generating longer keys can consume significant CPU resources. Limiting the key length using the enterprise_encryption.maximum_rsa_key_size system variable lets you provide adequate security for your requirements while balancing this with resource usage.

  This example creates a 2048-bit RSA private key, then derives a public key from the private key:

  SET @priv = create_asymmetric_priv_key('RSA', 2048);
  SET @pub = create_asymmetric_pub_key('RSA', @priv);

• create_asymmetric_pub_key(algorithm, priv_key_str)

  Derives a public key from the given private key using the given algorithm, and returns the key as a binary string in PEM format. The key is in PKCS #8 format. If key derivation fails, the result is NULL.

  For the legacy version of this function in use before MySQL 8.0.29, see Section 8.6.6, “MySQL Enterprise Encryption Legacy Function Descriptions”.

  algorithm is the encryption algorithm used to create the key. The supported algorithm value is 'RSA'.

  priv_key_str is a valid PEM encoded RSA private key.

  For a usage example, see the description of create_asymmetric_priv_key().

• create_digest(digest_type, str)

  Creates a digest from the given string using the given digest type, and returns the digest as a binary string. If digest generation fails, the result is NULL.

  For the legacy version of this function in use before MySQL 8.0.29, see Section 8.6.6, “MySQL Enterprise Encryption Legacy Function Descriptions”.

  The resulting digest string is suitable for use with asymmetric_sign() and asymmetric_verify(). The component versions of these functions accept digests but do not require them, as they are capable of handling data of an arbitrary length.

  digest_type is the digest algorithm to be used to generate the digest string. The supported digest_type values are 'SHA224', 'SHA256', 'SHA384', and 'SHA512' when OpenSSL 1.0.1 is in use. If OpenSSL 1.1.1 is in use, the additional digest_type values 'SHA3-224', 'SHA3-256', 'SHA3-384', and 'SHA3-512' are available.

  str is the non-null data string for which the digest is to be generated.

  SET @dig = create_digest('SHA512', 'The quick brown fox');