This is the fourth article in the series dedicated on transition from keyring plugins to keyring components. In the previous article we have discussed component_keyring_encrypted_file keyring component, how different is it from the keyring_encrypted_file plugin and how to install it using a manifest and configuration file. In this post we will be discussing component_keyring_oci keyring component, how different is it from keyring_oci plugin and the steps to install it.
Introduction
component_keyring_oci keyring component is part of the component infrastructure. Like keyring_oci plugin, it 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 component well suited for Oracle Cloud Infrastructure MySQL customers for management of their MySQL Enterprise Edition keys.
The same OCI vault can be used by both component_keyring_oci keyring component and keyring_oci plugin. This built-in backward compatibility makes the migration from keyring_oci plugin to component_keyring_oci very simple. All you need to do is load component_keyring_oci using the same configuration options that were used with keyring_oci plugin and you can access all the keys that were created and stored in the vault using keyring_oci plugin.
Loading the component
Unlike keyring plugins, keyring components are not loaded using the --early-plugin-load server option or configured using system variables. Instead, the server determines which keyring component to load during startup using a manifest file (named mysqld.my), and the loaded component consults its own configuration file when it initializes.
Keyring components should be loaded only by using a manifest file, not by using the INSTALL COMPONENT statement. Keyring components loaded using that statement may be available too late in the server startup sequence for certain components that use the keyring, such as InnoDB.
The Manifest file
The server attempts to read its global manifest file from the directory where the server is installed.
If the global manifest file indicates use of a local manifest file, the server attempts to read its local manifest file from the data directory.
Local manifest files permit setting up component loading for multiple instances of the server, such that loading instructions for each server instance are specific to a given data directory instance. This enables different MySQL instances to use different keyring components.
To use a global manifest file only, the file contents look like this:
{
"components": "file://component_keyring_oci"
}Alternatively, to use a global and local manifest file pair, the global file looks like this:
{
"read_local_manifest": true
}The local file looks like this:
{
"components": "file://component_keyring_oci"
}The Configuration File
The component attempts to read its global configuration file from the directory where the component library file is installed (that is, the server plugin directory).
If the global configuration file indicates use of a local configuration file, the component attempts to read its local configuration file from the data directory.
The file name is component_keyring_oci.cnf in both locations.
Local configuration files permit setting up multiple server instances to use component_keyring_oci, such that component configuration for each server instance is specific to a given data directory instance. This enables the same keyring component to be used with a distinct OCI vault for each instance.
To use a global configuration file only, the file contents look like this:
{
"user": ocid1.user.oc1..aaaaaaaasqly<...>
"tenancy": ocid1.tenancy.oc1..aaaaaaaai<...>
"compartment": ocid1.compartment.oc1..aaaaaaaah2swh<...>
"virtual_vault": ocid1.vault.oc1.iad.bbo5xyzkaaeuk.abuwcljtmvxp4r<...>
"encryption_endpoint": bbo5xyzkaaeuk-crypto.kms.us-<...>
"management_endpoint": bbo5xyzkaaeuk-management.kms.us-<...>
"vaults_endpoint": vaults.us-<...>
"secrets_endpoint": secrets.vaults.us-<...>
"master_key": ocid1.key.oc1.iad.bbo5xyzkaaeuk.abuwcljrbsrewgap<...>
"key_file": ~/.oci/oci_api_key.pem
"key_fingerprint": ca:7c:e1:fa:86:b6:40:af:39:d6<...>
"ca_certificate": disabled
}For details on each configuration item, visit Using the Oracle Cloud Infrastructure Vault Keyring Component.
Alternatively, to use a global and local configuration file pair, the global file looks like this:
{
"read_local_config": true
}The local file looks like this:
{
"user": ocid1.user.oc1..aaaaaaaasqly<...>
"tenancy": ocid1.tenancy.oc1..aaaaaaaai<...>
"compartment": ocid1.compartment.oc1..aaaaaaaah2swh<...>
"virtual_vault": ocid1.vault.oc1.iad.bbo5xyzkaaeuk.abuwcljtmvxp4r<...>
"encryption_endpoint": bbo5xyzkaaeuk-crypto.kms.us-<...>
"management_endpoint": bbo5xyzkaaeuk-management.kms.us-<...>
"vaults_endpoint": vaults.us-<...>
"secrets_endpoint": secrets.vaults.us-<...>
"master_key": ocid1.key.oc1.iad.bbo5xyzkaaeuk.abuwcljrbsrewgap<...>
"key_file": ~/.oci/oci_api_key.pem
"key_fingerprint": ca:7c:e1:fa:86:b6:40:af:39:d6<...>
"ca_certificate": disabled
}Start the server with the manifest and configuration files in place as described above and you are good to go!
Verify component installation by examining the Performance Schema keyring_component_status table:
mysql> SELECT * FROM performance_schema.keyring_component_status;
+---------------------+--------------------------------------------------------------------+
| STATUS_KEY | STATUS_VALUE |
+---------------------+--------------------------------------------------------------------+
| Component_name | component_keyring_oci |
| Author | Oracle Corporation |
| License | PROPRIETARY |
| Implementation_name | component_keyring_oci |
| Version | 1.0 |
| Component_status | Active |
| user | ocid1.user.oc1..aaaaaaaasqly<...> |
| tenancy | ocid1.tenancy.oc1..aaaaaaaai<...> |
| compartment | ocid1.compartment.oc1..aaaaaaaah2swh<...> |
| virtual_vault | ocid1.vault.oc1.iad.bbo5xyzkaaeuk.abuwcljtmvxp4r<...> |
| master_key | ocid1.key.oc1.iad.bbo5xyzkaaeuk.abuwcljrbsrewgap<...> |
| encryption_endpoint | bbo5xyzkaaeuk-crypto.kms.us-<...> |
| management_endpoint | bbo5xyzkaaeuk-management.kms.us-<...> |
| vaults_endpoint | vaults.us-<...> |
| secrets_endpoint | secrets.vaults.us-<...> |
| key_file | ~/.oci/oci_api_key.pem |
| key_fingerprint | ca:7c:e1:fa:86:b6:40:af:39:d6<...> |
| ca_certificate | disabled |
+---------------------+--------------------------------------------------------------------+A Component_status value of Active indicates that the component initialized successfully.
If the component cannot be loaded, server startup fails. Check the server error log for diagnostic messages. If the component loads but fails to initialize due to configuration problems, the server starts but the Component_status value is Disabled. Check the server error log, correct the configuration issues, and use the ALTER INSTANCE RELOAD KEYRING statement to reload the configuration.
To see which keys exist, examine the Performance Schema keyring_keys table:
mysql> SELECT * FROM performance_schema.keyring_keys;
+-----------------------------+--------------+----------------+
| KEY_ID | KEY_OWNER | BACKEND_KEY_ID |
+-----------------------------+--------------+----------------+
| audit_log-20210322T130749-1 | | |
| MyKey | me@localhost | |
| YourKey | me@localhost | |
+-----------------------------+--------------+----------------+Conclusion
The component_keyring_oci keyring component is advanced, flexible and have fewer restrictions than the keyring_oci plugin. It can be loaded using the manifest and configuration file.
Thank you for using MySQL!