#### 6.4.4.11 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/](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”](keyring-functions-general-purpose.html).

* C interface: In C-language code, call the keyring service functions described in [Section 5.6.9.2, “The Keyring Service”](keyring-service.html).

 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”](keyring-key-types.html).

 To install `keyring_oci`, use the general instructions found in [Section 6.4.4.3, “Keyring Plugin Installation”](keyring-plugin-installation.html), 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:

* [Overview of Vault](https://docs.cloud.oracle.com/iaas/Content/KeyManagement/Concepts/keyoverview.htm)

* [Resource Identifiers](https://docs.cloud.oracle.com/en-us/iaas/Content/General/Concepts/identifiers.htm)

* [Required Keys and OCIDs](https://docs.cloud.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm)

* [Managing Keys](https://docs.cloud.oracle.com/en-us/iaas/Content/KeyManagement/Tasks/managingkeys.htm)

* [Managing Compartments](https://docs.cloud.oracle.com/en-us/iaas/Content/Identity/Tasks/managingcompartments.htm)

* [Managing Vaults](https://docs.cloud.oracle.com/en-us/iaas/Content/KeyManagement/Tasks/managingvaults.htm)

* [Managing Secrets](https://docs.cloud.oracle.com/en-us/iaas/Content/KeyManagement/Tasks/managingsecrets.htm)

 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`](keyring-system-variables.html#sysvar_keyring_oci_user)               |   Yes   |
|         Tenancy OCID         |            [`keyring_oci_tenancy`](keyring-system-variables.html#sysvar_keyring_oci_tenancy)            |   Yes   |
|       Compartment OCID       |        [`keyring_oci_compartment`](keyring-system-variables.html#sysvar_keyring_oci_compartment)        |   Yes   |
|          Vault OCID          |      [`keyring_oci_virtual_vault`](keyring-system-variables.html#sysvar_keyring_oci_virtual_vault)      |   Yes   |
|       Master key OCID        |         [`keyring_oci_master_key`](keyring-system-variables.html#sysvar_keyring_oci_master_key)         |   Yes   |
|  Encryption server endpoint  |[`keyring_oci_encryption_endpoint`](keyring-system-variables.html#sysvar_keyring_oci_encryption_endpoint)|   Yes   |
|Key management server endpoint|[`keyring_oci_management_endpoint`](keyring-system-variables.html#sysvar_keyring_oci_management_endpoint)|   Yes   |
|    Vaults server endpoint    |    [`keyring_oci_vaults_endpoint`](keyring-system-variables.html#sysvar_keyring_oci_vaults_endpoint)    |   Yes   |
|   Secrets server endpoint    |   [`keyring_oci_secrets_endpoint`](keyring-system-variables.html#sysvar_keyring_oci_secrets_endpoint)   |   Yes   |
|     RSA private key file     |           [`keyring_oci_key_file`](keyring-system-variables.html#sysvar_keyring_oci_key_file)           |   Yes   |
| RSA private key fingerprint  |    [`keyring_oci_key_fingerprint`](keyring-system-variables.html#sysvar_keyring_oci_key_fingerprint)    |   Yes   |
|  CA certificate bundle file  |     [`keyring_oci_ca_certificate`](keyring-system-variables.html#sysvar_keyring_oci_ca_certificate)     |   No    |

 To be usable during the server startup process, `keyring_oci` must be loaded using the [`--early-plugin-load`](server-options.html#option_mysqld_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`](keyring-system-variables.html#sysvar_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-system-variables.html#sysvar_keyring_oci_tenancy), [`keyring_oci_compartment`](keyring-system-variables.html#sysvar_keyring_oci_compartment), and [`keyring_oci_virtual_vault`](keyring-system-variables.html#sysvar_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`](keyring-system-variables.html#sysvar_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-system-variables.html#sysvar_keyring_oci_encryption_endpoint), [`keyring_oci_management_endpoint`](keyring-system-variables.html#sysvar_keyring_oci_management_endpoint), [`keyring_oci_vaults_endpoint`](keyring-system-variables.html#sysvar_keyring_oci_vaults_endpoint), and [`keyring_oci_secrets_endpoint`](keyring-system-variables.html#sysvar_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](https://docs.cloud.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm). Assign the private key file name and key fingerprint to the [`keyring_oci_key_file`](keyring-system-variables.html#sysvar_keyring_oci_key_file) and [`keyring_oci_key_fingerprint`](keyring-system-variables.html#sysvar_keyring_oci_key_fingerprint) system variables.

 In addition to the mandatory system variables, [`keyring_oci_ca_certificate`](keyring-system-variables.html#sysvar_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_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..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 6.4.4.18, “Keyring System Variables”](keyring-system-variables.html).

 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`](set-variable.html) for parameters that are persisted to `mysqld-auto.conf`.

* Restart the server.

