Documentation Home
MySQL 8.0 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 43.1Mb
PDF (A4) - 43.2Mb
Man Pages (TGZ) - 295.4Kb
Man Pages (Zip) - 400.6Kb
Info (Gzip) - 4.3Mb
Info (Zip) - 4.3Mb
Excerpts from this Manual

MySQL 8.0 Reference Manual  /  ...  /  Using the Oracle Cloud Infrastructure Vault Keyring Plugin

8.4.4.12 Using the Oracle Cloud Infrastructure Vault Keyring Plugin

Note

The keyring_oci plugin is an extension included in MySQL Enterprise Edition, a commercial product. To learn more about commercial products, see https://www.mysql.com/products/.

The keyring_oci plugin is a keyring plugin that communicates with Oracle Cloud Infrastructure Vault for back end storage. No key information is permanently stored in MySQL server local storage. All keys are stored in Oracle Cloud Infrastructure Vault, making this plugin well suited for Oracle Cloud Infrastructure MySQL customers for management of their MySQL Enterprise Edition keys.

As of MySQL 8.0.31, this plugin is deprecated and subject to removal in a future release of MySQL. Instead, consider using the component_keyring_oci component for storing keyring data (see Section 8.4.4.11, “Using the Oracle Cloud Infrastructure Vault Keyring Component”).

The keyring_oci plugin supports the functions that comprise the standard MySQL Keyring service interface. Keyring operations performed by those functions are accessible at two levels:

Example (using the SQL interface):

SELECT keyring_key_generate('MyKey', 'AES', 32);
SELECT keyring_key_remove('MyKey');

For information about the characteristics of key values permitted by keyring_oci, see Section 8.4.4.13, “Supported Keyring Key Types and Lengths”.

To install keyring_oci, use the general instructions found in Section 8.4.4.3, “Keyring Plugin Installation”, together with the configuration information specific to keyring_oci found here. Plugin-specific configuration involves setting a number of system variables to indicate the names or values of Oracle Cloud Infrastructure resources.

You are assumed to be familiar with Oracle Cloud Infrastructure concepts, but the following documentation may be helpful when setting up resources to be used by the keyring_oci plugin:

The keyring_oci plugin supports the configuration parameters shown in the following table. To specify these parameters, assign values to the corresponding system variables.

Configuration Parameter System Variable Mandatory
User OCID keyring_oci_user Yes
Tenancy OCID keyring_oci_tenancy Yes
Compartment OCID keyring_oci_compartment Yes
Vault OCID keyring_oci_virtual_vault Yes
Master key OCID keyring_oci_master_key Yes
Encryption server endpoint keyring_oci_encryption_endpoint Yes
Key management server endpoint keyring_oci_management_endpoint Yes
Vaults server endpoint keyring_oci_vaults_endpoint Yes
Secrets server endpoint keyring_oci_secrets_endpoint Yes
RSA private key file keyring_oci_key_file Yes
RSA private key fingerprint keyring_oci_key_fingerprint Yes
CA certificate bundle file keyring_oci_ca_certificate No

To be usable during the server startup process, keyring_oci must be loaded using the --early-plugin-load option. As indicated by the preceding table, several plugin-related system variables are mandatory and must also be set:

  • Oracle Cloud Infrastructure uses Oracle Cloud IDs (OCIDs) extensively to designate resources, and several keyring_oci parameters specify OCID values of the resources to use. Consequently, prior to using the keyring_oci plugin, these prerequisites must be satisfied:

    • A user for connecting to Oracle Cloud Infrastructure must exist. Create the user if necessary and assign the user OCID to the keyring_oci_user system variable.

    • The Oracle Cloud Infrastructure tenancy to be used must exist, as well as the MySQL compartment within the tenancy, and the vault within the compartment. Create these resources if necessary and make sure the user is enabled to use them. Assign the OCIDs for the tenancy, compartment and vault to the keyring_oci_tenancy, keyring_oci_compartment, and keyring_oci_virtual_vault system variables.

    • A master key for encryption must exist. Create it if necessary and assign its OCID to the keyring_oci_master_key system variable.

  • Several server endpoints must be specified. These endpoints are vault specific and Oracle Cloud Infrastructure assigns them at vault-creation time. Obtain their values from the vault details page and assign them to the keyring_oci_encryption_endpoint, keyring_oci_management_endpoint, keyring_oci_vaults_endpoint, and keyring_oci_secrets_endpoint system variables.

  • The Oracle Cloud Infrastructure API uses an RSA private/public key pair for authentication. To create this key pair and obtain the key fingerprint, use the instructions at Required Keys and OCIDs. Assign the private key file name and key fingerprint to the keyring_oci_key_file and keyring_oci_key_fingerprint system variables.

In addition to the mandatory system variables, keyring_oci_ca_certificate optionally may be set to specify a certificate authority (CA) certificate bundle file for peer authentication.

Important

If you copy a parameter from the Oracle Cloud Infrastructure Console, the copied value may include an initial https:// part. Omit that part when setting the corresponding keyring_oci system variable.

For example, to load and configure keyring_oci, use these lines in the server my.cnf file (adjust the .so suffix and file location for your platform as necessary):

[mysqld]
early-plugin-load=keyring_oci.so
keyring_oci_user=ocid1.user.oc1..longAlphaNumericString
keyring_oci_tenancy=ocid1.tenancy.oc1..longAlphaNumericString
keyring_oci_compartment=ocid1.compartment.oc1..longAlphaNumericString
keyring_oci_virtual_vault=ocid1.vault.oc1.iad.shortAlphaNumericString.longAlphaNumericString
keyring_oci_master_key=ocid1.key.oc1.iad.shortAlphaNumericString.longAlphaNumericString
keyring_oci_encryption_endpoint=shortAlphaNumericString-crypto.kms.us-ashburn-1.oraclecloud.com
keyring_oci_management_endpoint=shortAlphaNumericString-management.kms.us-ashburn-1.oraclecloud.com
keyring_oci_vaults_endpoint=vaults.us-ashburn-1.oci.oraclecloud.com
keyring_oci_secrets_endpoint=secrets.vaults.us-ashburn-1.oci.oraclecloud.com
keyring_oci_key_file=file_name
keyring_oci_key_fingerprint=12:34:56:78:90:ab:cd:ef:12:34:56:78:90:ab:cd:ef

For additional information about the keyring_oci plugin-specific system variables, see Section 8.4.4.19, “Keyring System Variables”.

The keyring_oci plugin does not support runtime reconfiguration and none of its system variables can be modified at runtime. To change configuration parameters, do this:

  • Modify parameter settings in the my.cnf file, or use SET PERSIST_ONLY for parameters that are persisted to mysqld-auto.conf.

  • Restart the server.