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.
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:
SQL interface: In SQL statements, call the functions described in Section 6.4.4.14, “General-Purpose Keyring Key-Management Functions”.
C interface: In C-language code, call the keyring service functions described in Section 5.6.9.2, “The Keyring Service”.
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 6.4.4.12, “Supported Keyring Key Types and Lengths”.
To install keyring_oci, use the general instructions found in Section 6.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.
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_oci8, 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..longAlphaNumericStringkeyring_oci_tenancy=ocid1.tenancy.oc1..longAlphaNumericStringkeyring_oci_compartment=ocid1.compartment.oc1..longAlphaNumericStringkeyring_oci_virtual_vault=ocid1.vault.oc1.iad.shortAlphaNumericString.longAlphaNumericStringkeyring_oci_master_key=ocid1.key.oc1.iad.shortAlphaNumericString.longAlphaNumericStringkeyring_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_namekeyring_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 6.4.4.18, “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.