1 files changed, 181 insertions, 0 deletions
diff --git a/plugin/hashicorp_key_management/hashicorp_key_management.txt b/plugin/hashicorp_key_management/hashicorp_key_management.txt
new file mode 100644
index 00000000000..1750154858e
--- /dev/null
+++ b/plugin/hashicorp_key_management/hashicorp_key_management.txt
@@ -0,0 +1,181 @@
+This file describes a hasicorp_key_management plugin that is used to
+implement encryption using keys stored in the Hashicorp Vault KMS.
+
+The current version of this plugin implements the following features:
+
+- Authentication is done using the Hashicorp Vault's token
+  authentication method;
+- If additional client authentication is required, then the
+  path to the CA authentication bundle file may be passed
+  as a plugin parameter;
+- The creation of the keys and their management is carried
+  out using the Hashicorp Vault KMS and their tools;
+- The plugin uses libcurl (https) as an interface to
+  the HashiCorp Vault server;
+- JSON parsing is performed through the JSON service
+  (through the include/mysql/service_json.h);
+- HashiCorp Vault 1.2.4 was used for development and testing.
+
+Since we require support for key versioning, then the key-value
+storage must be configured in Hashicorp Vault as a key-value storage
+that uses the interface of the second version. For example, you can
+create it as follows:
+
+~$ vault secrets enable -path /test -version=2 kv
+
+Key names must correspond to their numerical identifiers.
+Key identifiers itself, their possible values and rules of use
+are described in more detail in the MariaDB main documentation.
+
+From the point of view of the key-value storage (in terms
+of Hashicorp Vault), the key is a secret containing one key-value
+pair with the name "data" and a value representing a binary string
+containing the key value, for example:
+
+~$ vault kv get /test/1
+
+====== Metadata ======
+Key              Value
+---              -----
+created_time     2019-12-14T14:19:19.42432951Z
+deletion_time    n/a
+destroyed        false
+version          1
+
+==== Data ====
+Key     Value
+---     -----
+data    0123456789ABCDEF0123456789ABCDEF
+
+Keys values are strings containing binary data. MariaDB currently
+uses the AES algorithm with 256-bit keys as the default encryption
+method. In this case, the keys that will be stored in the Hashicorp
+Vault should be 32-byte strings. Most likely you will use some utilities
+for creating and administering keys designed to work with Hashicorp
+Vault. But in the simplest case, keys can be created from the command
+line through the vault utility, for example, as follows:
+
+~$ vault kv put /test/1 data="0123456789ABCDEF0123456789ABCDEF"
+
+If you use default encryption (AES), you should ensure that the
+key length is 32 bytes, otherwise it may fail to use InnoDB as
+a data storage.
+
+The plugin currently does not unseal Hashicorp Vault on its own,
+you must do this in advance and on your own.
+
+To use Hashicorp Vault KMS, the plugin must be preloaded and
+activated on the server. Most of its parameters should not be
+changed during plugin operation and therefore must be preconfigured
+as part of the server configuration through configuration file or
+command line options:
+
+--plugin-load-add=hashicorp_key_management.so
+--loose-hashicorp-key-management
+--loose-hashicorp-key-management-vault-url="$VAULT_ADDR/v1/test"
+--loose-hashicorp-key-management-token="$VAULT_TOKEN"
+
+Currently, the plugin supports the following parameters, which
+must be set in advance and cannot be changed during server
+operation:
+
+--[loose-]hashicorp-key-management-vault-url="<url>"
+
+  HTTP[s] URL that is used to connect to the Hashicorp Vault
+  server. It must include the name of the scheme (https://
+  for a secure connection) and, according to the API rules
+  for storages of the key-value type in Hashicorp Vault,
+  after the server address, the path must begin with the
+  "/v1/" string (as prefix), for example:
+
+     https://127.0.0.1:8200/v1/my_secrets
+
+  By default, the path is not set, therefore you must
+  replace with the correct path to your secrets.
+
+--[loose-]hashicorp-key-management-token="<token>"
+
+  Authentication token that passed to the Hashicorp Vault
+  in the request header.
+
+  By default, this parameter contains an empty string,
+  so you must specify the correct value for it, otherwise
+  the Hashicorp Vault server will refuse authorization.
+
+--[loose-]hashicorp-key-management-vault-ca="<path>"
+
+  Path to the Certificate Authority (CA) bundle (is a file
+  that contains root and intermediate certificates).
+
+  By default, this parameter contains an empty string,
+  which means no CA bundle.
+
+--[loose-]hashicorp-key-management-timeout=<timeout>
+
+  Set the duration (in seconds) for the Hashicorp Vault server
+  connection timeout. The default value is 15 seconds. The allowed
+  range is from 1 to 86400 seconds. The user can also specify a zero
+  value, which means the default timeout value set by the libcurl
+  library (currently 300 seconds).
+
+--[loose-]hashicorp-key-management-retries=<retries>
+
+  Number of server request retries in case of timeout.
+  Default is three retries.
+
+--[loose-]hashicorp-key-management-caching-enabled="on"|"off"
+
+  Enable key caching (storing key values received from
+  the Hashicorp Vault server in the local memory). By default
+  caching is enabled.
+
+--[loose-]hashicorp-key-management-use-cache-on-timeout="on"|"off"
+
+  This parameter instructs the plugin to use the key values
+  or version numbers taken from the cache in the event of a
+  timeout when accessing the vault server. By default this
+  option is disabled.
+
+  Please note that key values or version numbers will be read
+  from the cache when the timeout expires only after the number
+  of attempts to read them from the storage server that specified
+  by the --[loose-]hashicorp-key-management-retries parameter
+  has been exhausted.
+
+--[loose-]hashicorp-key-management-cache-timeout=<timeout>
+
+  The time (in milliseconds) after which the value of the key
+  stored in the cache becomes invalid and an attempt to read this
+  data causes a new request send to the vault server. By default,
+  cache entries become invalid after 60,000 milliseconds (after
+  one minute).
+
+  If the value of this parameter is zero, then the keys will always
+  be considered invalid, but they still can be used if the vault
+  server is unavailable and the corresponding cache operating mode
+  (--[loose-]hashicorp-key-management-use-cache-on-timeout="on")
+  is enabled.
+
+--[loose-]hashicorp-key-management-cache-version-timeout=<timeout>
+
+  The time (in milliseconds) after which the information about
+  latest version number of the key (which stored in the cache)
+  becomes invalid and an attempt to read this information causes
+  a new request send to the vault server.
+
+  If the value of this parameter is zero, then information abount
+  latest key version numbers always considered invalid, unless
+  there is no communication with the vault server and use of the
+  cache is allowed when the server is unavailable.
+
+  By default, this parameter is zero, that is, the latest version
+  numbers for the keys stored in the cache are considered always
+  invalid, except when the vault server is unavailable and use
+  of the cache is allowed on server failures.
+
+--[loose-]hashicorp-key-management-check-kv-version="on"|"off"
+
+  This parameter enables ("on", this is the default value) or disables
+  ("off") checking the kv storage version during plugin initialization.
+  The plugin requires storage to be version 2 or older in order for it
+  to work properly.