.. meta:: :title: Using the Keyring Component or Keyring Plugin :description: The keyring_vault plugin can store the encryption keys inside the HashiCorp Vault. :language: en-US :keywords: galera cluster, keyring_vault :copyright: This software documentation is (C)2009-2018 Percona LLC and/or its affiliates and is distributed under the Creative Commons Attribution-ShareAlike 2.0 Generic license. .. container:: left-margin .. container:: left-margin-top :doc:`The Library <../index>` .. container:: left-margin-content .. cssclass:: here - :doc:`Documentation <./index>` - :doc:`Knowledge Base <../kb/index>` - :doc:`Training <../training/index>` .. cssclass:: sub-links - :doc:`Training Courses <../training/courses/index>` - :doc:`Tutorial Articles <../training/tutorials/index>` - :doc:`Training Videos <../training/videos/index>` - :doc:`FAQ <../faq>` - :ref:`search` Related Documents - :doc:`galera-parameters` .. container:: top-links - `Home `_ .. cssclass:: here - :doc:`Docs <./index>` - :doc:`KB <../kb/index>` .. cssclass:: nav-wider - :doc:`Training <../training/index>` - :doc:`FAQ <../faq>` .. cssclass:: library-document .. _`keyring-plugin`: ============================================== Using the Keyring Component or Keyring Plugin ============================================== .. index:: pair: Descriptions; Keyring Plugin This software documentation is (C)2009-2018 Percona LLC and/or its affiliates and is distributed under the `Creative Commons Attribution-ShareAlike 2.0 Generic license `_. The ``keyring_vault`` plugin can store the encryption keys inside the `HashiCorp Vault `_. .. note:: See also `Installing Vault `_ and `Production Hardening `_. Galera can use either of the following plugins: - ``keyring_file`` stores the keyring data locally - ``keyring_vault`` provides an interface for the database with a HashiCorp Vault server to store key and secure encryption keys. .. note:: Do not use the ``keyring_file`` plugin for regulatory compliance. To install the plugin, follow the `installing and uninstalling plugins `_ instructions. .. _`keyring-plugin-loading`: .. rst-class:: section-heading .. rubric:: Loading the Keyring Plugin Load the plugin at server startup with the ``-early-plugin-load`` option to enable keyrings. .. warning:: Only enable one keyring plugin at a time. Enabling multiple keyring plugins is not supported and may result in data loss. We recommend that you load the plugin in the configuration file to facilitate recovery for encrypted tables. Also, the redo log encryption and the undo log encryption cannot be used without ``--early-plugin-load``. The normal plugin load happens too late in startup. .. note:: The ``keyring_vault`` extension, ``.so`` and the file location for the vault configuration should be changed to match your operating system’s extension and the file location in your operating system. To use the ``keyring_vault``, you can add this option to your configuration file: .. code-block:: console [mysqld] early-plugin-load="keyring_vault=keyring_vault.so" loose-keyring_vault_config="/home/mysql/keyring_vault.conf" The keyring_vault extension, ".so" and the file location for the vault configuration should be changed to match your operating system's extension and operating system location. You can also run the following command, which loads the ``keyring_file`` plugin: .. code-block:: console $ mysqld --early-plugin-load="keyring_file=keyring_file.so" .. note:: If a server starts with different plugins loaded early, the ``--early-plugin-load`` option should contain the plugin names in a double-quoted list with each plugin name separated by a semicolon. The use of double quotes ensures the semicolons do not create issues when the list is executed in a script. Apart from installing the plugin you also must set the ``keyring_vault_config`` variable to point to the ``keyring_vault`` configuration file. The ``keyring_vault_config`` file has the following information: - ``vault_url`` - the Vault server address - ``secret_mount_point`` - the mount point name where ``keyring_vault`` stores the keys. - ``secret_mount_point_version`` - the KV Secrets Engine version (kv or kv-v2) used. - ``token`` - a token generated by the Vault server. - ``vault_ca [optional]`` - if the machine does not trust the Vault’s CA certificate, this variable points to the CA certificate used to sign the Vault’s certificates. This is an example of a configuration file: .. code-block:: console vault_url = https://vault.public.com:8202 secret_mount_point = secret secret_mount_point_version = AUTO token = 58a20c08-8001-fd5f-5192-7498a48eaf20 vault_ca = /data/keyring_vault_confs/vault_ca.crt .. warning:: Each ``secret_mount_point`` must be used by only one server. If multiple servers use the same ``secret_mount_point``, the behavior is unpredictable. The first time a key is fetched from a keyring, the ``keyring_vault`` communicates with the Vault server to retrieve the key type and data. .. _`keyring-plugin-secret-mount-point`: .. rst-class:: section-heading .. rubric:: secret_mount_point_version The ``secret_mount_point_version`` can be either ``1``, ``2``, ``AUTO``, or the ``secret_mount_point_version`` parameter is not listed in the configuration file. .. csv-table:: :class: doc-options :header: "Value", "Description" :widths: 20, 80 "``1``", "Works with KV Secrets Engine - Version 1 (kv). When forming key operation URLs, the ``secret_mount_point`` is always used without any transformations. For example, to return a key named skey, the URL is ``/v1//skey``." "``2``", "Works with KV Secrets Engine - Version 2 (kv) The initialization logic splits the secret_mount_point parameter into two parts: - The ``mount_point_path`` - the mount path under which the Vault Server secret was created - The ``directory_path`` - a virtual directory suffix that can be used to create virtual namespaces with the same real mount point For example, both the ``mount_point_path`` and the ``directory_path`` are needed to form key access URLs: ``/v1/`_ manual. The plugin library contains keyring user-defined functions which allow access to the internal keyring service functions. To enable the functions, you must enable the ``keyring_udf`` plugin: .. code-block:: console $ mysqld INSTALL PLUGIN keyring_udf SONAME 'keyring_udf.so'; .. note:: The ``keyring_udf`` plugin must be installed. Using the user-defined functions without the ``keyring_udf`` plugin generates an error. You must also create keyring encryption user-defined functions. .. _`keyring-plugin-using`: .. rst-class:: section-heading .. rubric:: Using the keyring_file component See `keyring component installation `_ for information on installing the component. .. warning:: Do not use the ``keyring_file`` component for regulatory compliance. .. note:: See also `MySQL Documentation: Using the keyring_file component `_. .. _`keyring-plugin-system-variables`: .. rst-class:: section-heading .. rubric:: System Variables .. _`keyring_vault_config`: .. rst-class:: section-heading .. rubric:: ``keyring_vault_config`` .. index:: pair: Keyring System Variables; keyring_vault_config This variable defines the location of the ``keyring_vault_plugin`` configuration file. .. csv-table:: :class: doc-options "Command Line", "``–keyring-vault-config``" "Scope", "Global" "Dynamic", "Yes" "Data Type", "Text" .. _`keyring_vault_timeout`: .. rst-class:: section-heading .. rubric:: ``keyring_vault_timeout`` .. index:: pair: Keyring System Variables; keyring_vault_timeout Set the duration in seconds for the Vault server connection timeout. The default value is ``15``. The allowed range is from ``0`` to ``86400``. The timeout can be also disabled to wait an infinite amount of time by setting this variable to ``0``. .. csv-table:: :class: doc-options "Command Line", "``–keyring_vault_timeout``" "Scope", "Global" "Dynamic", "Yes" "Data Type", "Numeric" "Default", "15" .. container:: bottom-links Related Documents - :doc:`galera-parameters`