8.6.1 MySQL Enterprise Encryption Installation and Upgrading

In releases before MySQL 8.0.30, the functions provided by MySQL Enterprise Encryption are installed by creating them individually, based on the openssl_udf shared library. From MySQL 8.0.30, the functions are provided by a MySQL component component_enterprise_encryption, and installing the component installs all of the functions. The functions from the openssl_udf shared library are deprecated from that release, and you should upgrade to the component instead.

• Installation From MySQL 8.0.30

• Installation To MySQL 8.0.29

• Upgrading MySQL Enterprise Encryption

Installation From MySQL 8.0.30

From MySQL 8.0.30, MySQL Enterprise Encryption’s functions are provided by a MySQL component component_enterprise_encryption, rather than being installed from the openssl_udf shared library. If you are upgrading to MySQL 8.0.30 from an earlier release where you used MySQL Enterprise Encryption, the functions you created remain available and are supported. However, these legacy functions are deprecated from this release, and it is recommended that you install the component instead. The component functions are backward compatible. For upgrade information, see Upgrading MySQL Enterprise Encryption.

If you are upgrading, before installing the component, unload the legacy functions using the DROP FUNCTION statement:

DROP FUNCTION asymmetric_decrypt;
DROP FUNCTION asymmetric_derive;
DROP FUNCTION asymmetric_encrypt;
DROP FUNCTION asymmetric_sign;
DROP FUNCTION asymmetric_verify;
DROP FUNCTION create_asymmetric_priv_key;
DROP FUNCTION create_asymmetric_pub_key;
DROP FUNCTION create_dh_parameters;
DROP FUNCTION create_digest;

The function names must be specified in lowercase. The statements require the DROP privilege for the mysql database.

To install the component, issue an INSTALL COMPONENT statement:

INSTALL COMPONENT "file://component_enterprise_encryption";

INSTALL COMPONENT requires the INSERT privilege for the mysql.component system table because it adds a row to that table to register the component. To verify that the component has been installed, issue:

SELECT * FROM mysql.component;

Components listed in mysql.component are loaded by the loader service during the startup sequence.

If you need to uninstall the component, issue an UNINSTALL COMPONENT statement:

UNINSTALL COMPONENT "file://component_enterprise_encryption";

For more details, see Section 7.5.1, “Installing and Uninstalling Components”.

Installing the component installs all of the functions, so you do not need to create them using CREATE FUNCTION statements as you do before MySQL 8.0.30. Uninstalling the component uninstalls all of the functions.

When you have installed the component, if you want the component functions to support decryption and verification for content produced by the legacy functions before MySQL 8.0.30, set the component’s system variable enterprise_encryption.rsa_support_legacy_padding to ON. Also, if you want to change the maximum length allowed for the RSA keys generated by the component functions, use the component’s system variable enterprise_encryption.maximum_rsa_key_size to set an appropriate maximum. For configuration information, see Section 8.6.2, “Configuring MySQL Enterprise Encryption”.

Installation To MySQL 8.0.29

Before MySQL 8.0.29, MySQL Enterprise Encryption functions are located in a loadable function library file installed in the plugin directory (the directory named by the plugin_dir system variable). The function library base name is openssl_udf and the suffix is platform dependent. For example, the file name on Linux or Windows is openssl_udf.so or openssl_udf.dll, respectively.

To install functions from the openssl_udf shared library file, use the CREATE FUNCTION statement. To load all functions from the library, use this set of statements, adjusting the file name suffix as necessary:

CREATE FUNCTION asymmetric_decrypt RETURNS STRING
  SONAME 'openssl_udf.so';
CREATE FUNCTION asymmetric_derive RETURNS STRING
  SONAME 'openssl_udf.so';
CREATE FUNCTION asymmetric_encrypt RETURNS STRING
  SONAME 'openssl_udf.so';
CREATE FUNCTION asymmetric_sign RETURNS STRING
  SONAME 'openssl_udf.so';
CREATE FUNCTION asymmetric_verify RETURNS INTEGER
  SONAME 'openssl_udf.so';
CREATE FUNCTION create_asymmetric_priv_key RETURNS STRING
  SONAME 'openssl_udf.so';
CREATE FUNCTION create_asymmetric_pub_key RETURNS STRING
  SONAME 'openssl_udf.so';
CREATE FUNCTION create_dh_parameters RETURNS STRING
  SONAME 'openssl_udf.so';
CREATE FUNCTION create_digest RETURNS STRING
  SONAME 'openssl_udf.so';

Once installed, the functions remain installed across server restarts. If you need to unload the functions, use the DROP FUNCTION statement:

DROP FUNCTION asymmetric_decrypt;
DROP FUNCTION asymmetric_derive;
DROP FUNCTION asymmetric_encrypt;
DROP FUNCTION asymmetric_sign;
DROP FUNCTION asymmetric_verify;
DROP FUNCTION create_asymmetric_priv_key;
DROP FUNCTION create_asymmetric_pub_key;
DROP FUNCTION create_dh_parameters;
DROP FUNCTION create_digest;

In the CREATE FUNCTION and DROP FUNCTION statements, the function names must be specified in lowercase. This differs from their use at function invocation time, for which you can use any lettercase.

The CREATE FUNCTION and DROP FUNCTION statements require the INSERT and DROP privilege, respectively, for the mysql database.

The functions provided by the openssl_udf shared library allow a minimum key size of 1024 bits. You can set a maximum key size using the MYSQL_OPENSSL_UDF_RSA_BITS_THRESHOLD, MYSQL_OPENSSL_UDF_DSA_BITS_THRESHOLD, and MYSQL_OPENSSL_UDF_DH_BITS_THRESHOLD environment variables, as described in Section 8.6.2, “Configuring MySQL Enterprise Encryption”. If you do not set a maximum key size, the upper limit is 16384 for the RSA algorithm and 10000 for the DSA algorithm, as specified by OpenSSL.

Upgrading MySQL Enterprise Encryption

If you upgrade to MySQL 8.0.30 or later from an earlier release where you used the functions provided by the openssl_udf shared library, the functions you created remain available and are supported. However, these legacy functions are deprecated from MySQL 8.0.30, and it is recommended that you install the MySQL Enterprise Encryption component component_enterprise_encryption instead.

When you are upgrading, before installing the component, you must unload the legacy functions using the DROP FUNCTION statement. For instructions to do this, see Installation From MySQL 8.0.30.

The component functions are backward compatible:

• RSA public and private keys generated by the legacy functions can be used with the component functions.

• Data encrypted with the legacy functions can be decrypted by the component functions.

• Signatures created by the legacy functions can be verified with the component functions.

For the component functions to support decryption and verification for content produced by the legacy functions, you must set the system variable enterprise_encryption.rsa_support_legacy_padding to ON (the default is OFF). For configuration information, see Section 8.6.2, “Configuring MySQL Enterprise Encryption”.

The legacy functions cannot handle encrypted data, public keys, and signatures created by the component functions, due to the differences in the padding and key format used by the component functions to meet the current standards.

The new functions provided by the component_enterprise_encryption component have some differences in behavior and support from the legacy functions provided by the openssl_udf shared library. The most important of these are as follows:

• The legacy functions support the older DSA algorithm and Diffie-Hellman key exchange method. The component functions use only the generally preferred RSA algorithm.

• For the legacy functions, the minimum RSA key size is less than current best practice. The component functions follow current best practice on minimum RSA key size.

• The legacy functions support only SHA2 for digests, and require digests for signatures. The component functions also support SHA3 for digests (provided that OpenSSL 1.1.1 is in use), and do not require digests for signatures, although they support them.

• The asymmetric_encrypt() legacy function supports encryption using private keys. The asymmetric_encrypt() component function only accepts a public key. It is recommended that you only encrypt using public keys with the legacy function as well.

• The create_dh_parameters() and asymmetric_derive() legacy functions for the Diffie-Hellman key exchange method are not provided by the component_enterprise_encryption component.

Table 1 summarizes the technical differences in support and operation between the legacy functions provided by the openssl_udf shared library, and the functions provided by the component_enterprise_encryption component from MySQL 8.0.30.

Table 8.48 MySQL Enterprise Encryption functions

Capability	Legacy functions (to MySQL 8.0.29)	Component functions (from MySQL 8.0.30)
Encryption method	RSA, DSA, Diffie-Hellman (DH)	RSA only
Key for encryption	Private or public	Public only
RSA key format	PKCS #1 v1.5	PKCS #8
Minimum RSA key size	1024 bits	2048 bits
Maximum RSA key size limit	Set with environment variable MYSQL_OPENSSL_UDF_RSA_BITS_THRESHOLD, default limit is algorithm maximum 16384	Set with system variable enterprise_encryption.maximum_rsa_key_size, default limit is 4096
Digest algorithms	SHA2	SHA2, SHA3 (with OpenSSL 1.1.1)
Signatures	Digest required	Digests supported but not required, any string of arbitrary length can be used
Output padding	RSAES-PKCS1-v1_5	RSAES-OAEP
Signature padding	RSASSA-PKCS1-v1_5	RSASSA-PSS