From 87466430e4ad7e87df577e5095adef592fe63ef3 Mon Sep 17 00:00:00 2001 From: Patrick Birch <48594400+patrickbirch@users.noreply.github.com> Date: Tue, 11 Feb 2025 02:50:26 -0600 Subject: [PATCH] PS-9671 [DOCS] - Update data masking documentation in 8.4 modified: docs/data-masking-function-list.md modified: docs/data-masking-overview.md --- docs/data-masking-function-list.md | 102 ++++++++++++++++++++++++++--- docs/data-masking-overview.md | 61 ++++++++++++++++- 2 files changed, 152 insertions(+), 11 deletions(-) diff --git a/docs/data-masking-function-list.md b/docs/data-masking-function-list.md index f42738c9142..75bb4d72a28 100644 --- a/docs/data-masking-function-list.md +++ b/docs/data-masking-function-list.md @@ -1,8 +1,26 @@ -# Data masking component functions +# Data masking component functions and variables The feature is in [tech preview](glossary.md#tech-preview). -| **Name** | **Usage** | +## Permissions + +In Percona Server for MySQL 8.4.4-1, dictionary-related functions no longer run internal queries as the root user without a password. Following MySQL best practices, many admins disable the `root` user, which previously caused these functions to stop working. The server now uses the built-in `mysql.session` user to execute dictionary queries. + +However, for this to work, you need to grant the mysql.session user `SELECT`, `INSERT`, `UPDATE`, and `DELETE` privileges on the `masking_dictionaries` table. + +```{.bash data-prompt="mysql>"} +mysql> GRANT SELECT, INSERT, UPDATE, DELETE ON mysql.masking_dictionaries TO 'mysql.session'@'localhost'; +``` + +If you change the value of the `masking_functions.masking_database` system variable to something other than `mysql`, make sure to update the `GRANT` query to match the new value. + +```{.bash data-prompt="mysql>"} +mysql> GRANT SELECT, INSERT, UPDATE, DELETE ON .masking_dictionaries TO 'mysql.session'@'localhost'; +``` + +## Data masking component functions + +| **Name** | **Details** | |---------------------------------------------------|-------------------------------------------------------| | [`gen_blocklist(str, from_dictionary_name, to_dictionary_name)`](#gen_blockliststr-from_dictionary_name-to_dictionary_name) | Replace a term from a dictionary | | [`gen_dictionary(dictionary_name)`](#gen_dictionarydictionary_name) | Returns a random term from a dictionary | @@ -24,13 +42,19 @@ The feature is in [tech preview](glossary.md#tech-preview). | [`mask_ssn(str [,mask_char])`](#mask_ssnstr-mask_char) | Masks the US Social Security number | | [`mask_uk_nin(str [,mask_char])`](#mask_uk_ninstr-mask_char) | Masks the United Kingdom National Insurance number | | [`mask_uuid(str [,mask_char])`](#mask_uuidstr-mask_char) | Masks the Universally Unique Identifier | +| [`masking_dictionaries_flush()`](#masking_dictionaries_flush) | Resyncs the internal dictionary term cache | | [`masking_dictionary_remove(dictionary_name)`](#masking_dictionary_removedictionary_name) | Removes the dictionary | | [`masking_dictionary_term_add(dictionary_name, term_name)`](#masking_dictionary_term_adddictionary_name-term_name) | Adds a term to the masking dictionary | | [`masking_dictionary_term_remove(dictionary_name, term_name)`](#masking_dictionary_term_removedictionary_name-term_name) | Removes a term from the masking dictionary | + ## gen_blocklist(str, from_dictionary_name, to_dictionary_name) -Replaces one term in a dictionary with a term, selected at random, in another dictionary. +Replaces a term from one dictionary with a randomly selected term in another dictionary. + +### Version update + +Percona Server for MySQL 8.4.4-1 introduces an internal term cache. The server now uses in-memory data structures for lookups instead of querying the `.masking_dictionaries` table every time. This improvement boosts performance, especially when handling multiple rows. ### Parameters @@ -66,6 +90,10 @@ mysql> SELECT gen_blocklist('apple', 'fruit', 'nut'); Returns a term from a dictionary selected at random. +### Version update + +Percona Server for MySQL 8.4.4-1 introduces an internal term cache. The server now uses in-memory data structures for lookups instead of querying the `.masking_dictionaries` table every time. This improvement boosts performance, especially when handling multiple rows. + ### Parameters | Parameter | Optional | Description | Type | @@ -760,6 +788,34 @@ mysql> SELECT mask_uuid('9a3b642c-06c6-11ee-be56-0242ac120002'); +-------------------------------------------------------+ ``` + +## masking_dictionaries_flush() + +Resyncs the internal dictionary term cache. + +### Parameters + +None + +### Returns + +Returns an integer value of `1` (one) when successful. + +### Example + +```{.bash data-prompt="mysql>"} +mysql> SELECT masking_dictionaries_flush(); +``` +??? example "Expected output" + + ```{.text .no-copy} + +------------------------------+ + | masking_dictionaries_flush() | + +------------------------------+ + | 1 | + +---------------------------- + + ``` + ## masking_dictionary_remove(dictionary_name) Removes all of the terms and then removes the dictionary. @@ -775,7 +831,7 @@ Requires the `MASKING_DICTIONARIES_ADMIN` privilege. ### Returns -Returns a string value of `1` (one) in the `utf8mb4` character set if the operation is successful or `NULL` if the operation could not find the `dictionary_name`. +Returns an integer value of `1` (one) if the operation is successful. Returns the integer value of `0` (zero) for a failure. ### Example @@ -807,9 +863,7 @@ Adds a term to the dictionary and requires the `MASKING_DICTIONARIES_ADMIN` priv ### Returns -Returns a string value of `1` (one) in the `utf8mb4` character set if the operation is successful. If the `dictionary_name` does not exist, the operation creates the dictionary. - -Returns `NULL` if the operation fails. An operation can fail if the `term_name` is already available in the dictionary specified by `dictionary_name`. +Returns an integer value of `1` (one) if the operation is successful. Returns an integer value of `0` (zero) for a failure. If the `dictionary_name` does not exist, the operation creates the dictionary. The operation uses `INSERT IGNORE` and can have the following outcomes: @@ -872,7 +926,7 @@ Requires the `MASKING_DICTIONARIES_ADMIN` privilege. ### Returns -Returns a string value of `1` (one) in the `utf8mb4` character set if the operation is successful. +Returns a integer value of `1` (one) if the operation is successful. Returns the integer value of `0` (zero) for a failure. Returns `NULL` if the operation fails. An operation can fail if the following occurs: @@ -902,3 +956,35 @@ mysql> SELECT masking_dictionary_term_remove('trees','pine'); | 1 | +-------------------------------------------------------+ ``` + +## System variables + + +| **Name** | **Details** | +|---------------------------------------------------|-------------------------------------------------------| +| [`dictionaries_flush_interval_seconds (integer, unsigned)`](#dictionaries_flush_interval_secondsinteger-unsigned) | The number of seconds between updates to the internal dictionary cache to match changes in the dictionaries table.| +| [`masking_database(str)`](#masking_databasestr) | Set a different database name to use for the dictionaries table. | + +### dictionaries_flush_interval_seconds(integer, unsigned) + +| Option | Description | +|--------------|------------------| +| command-line | Yes | +| scope | Global | +| data type | unsigned integer | +| default | 0 | + + +Percona Server for MySQL 8.4.4-1 adds this variable. The number of seconds between a synchronization between the dictionaries table and the internal dictionary cache. The default value is 0 seconds (disabled). The minimum value is 1 second. The maximum value is 31,536,000 seconds (1 year). + +### masking_database(string) + +| Option | Description | +| -------------- | ------------------ | +| Scope: | Global | +| Read, Write, or Read-Only: | Read-Only | +| Data type | String | +| Default value | "mysql" | + +Specify the name of the database that holds the `masking_dictionaries` table. By default, it uses the `mysql` database. + diff --git a/docs/data-masking-overview.md b/docs/data-masking-overview.md index 5f2187a6438..b47c6d78b89 100644 --- a/docs/data-masking-overview.md +++ b/docs/data-masking-overview.md @@ -1,6 +1,47 @@ # Data masking overview -Data masking helps to limit the exposure of sensitive data by preventing access to non-authorized users. Masking provides a way to create a version of the data in situations, such as a presentation, sales demo, or software testing, when the real data should not be used. Data masking changes the data values while using the same format and cannot be reverse engineered. Masking reduces an organization's risk by making the data useless to an outside party. +Data masking protects sensitive information by restricting data access to authorized users only. When you need to present, demonstrate, or test software without revealing actual data, masking creates safe versions of your data. The masking process changes values while keeping the same data format, making the original values impossible to recover. This security approach reduces organizational risk because any exposed data becomes worthless to unauthorized parties. + +Data masking in Percona Server for MySQL is an essential tool for protecting sensitive information in various scenarios: + +| Scenario | Description | +|---|----| +| Protecting data in development and testing | Developers and testers require realistic data to validate applications. By masking sensitive details, such as credit card numbers, Social Security numbers, and addresses, accurate user information can be safeguarded in non-production environments. | +| Compliance with data privacy regulations | Stringent laws like GDPR, HIPAA, and CCPA mandate the protection of personal data. Data masking enables the anonymization of personal information, facilitating its use for analysis and reporting while ensuring compliance with regulations. | +| Securing data when collaborating with external entities | Sharing data with third-party vendors demands the masking of sensitive information to prevent access to accurate personal details. | +| Supporting customer service and training | Customer support teams and trainers often require access to customer data. Through data masking, they can utilize realistic information without compromising actual customer details. | +| Facilitating data analysis and reporting | Analysts rely on access to data for generating reports and uncovering insights. By employing data masking techniques, they can work with realistic data sets without compromising privacy. | + +These examples underscore how data masking serves as a crucial safeguard for sensitive information, allowing organizations to leverage their data effectively across diverse functions. + + +## Version updates + +Percona Server for MySQL 8.4.4-4 introduces performance improvements for data masking through an internal term cache. The cache affects the following functions in the [data masking component](data-masking-function-list.md): + +* [gen_blocklist()](data-masking-function-list.md#gen_blockliststr-from_dictionary_name-to_dictionary_name) + +* [gen_dictionary()](data-masking-function-list.md#gen_dictionarydictionary_name) + +The new cache stores dictionary data in memory, making lookups faster than the previous method of querying the `.masking_dictionaries` table each time. This speed boost is especially noticeable when you're working with many rows of data. + +However, the cache brings some new considerations. If you change the dictionary table directly (instead of using the proper dictionary management functions), your cache and table data can become different. + +The dictionary manipulation functions are the following: + +* [`masking_dictionary_term_add()`](data-masking-function-list.md#masking_dictionary_term_adddictionary_name-term_name) + +* [`masking_dictionary_term_remove()`](data-masking-function-list.md#masking_dictionary_term_removedictionary_name-term_name) + +* [`masking_dictionary_remove()`](data-masking-function-list.md#masking_dictionary_removedictionary_name) + +To fix this, you can use the new [`masking_dictionaries_flush()`](data-masking-function-list.md#masking_dictionaries_flush) function to sync them back up. This function returns `1` when successful. + +The changes also affect how row-based replication works. When dictionary changes happen on the source server, they travel through the binary log to the replica server. While the replica applies these changes to its table correctly, the dictionary term cache doesn't update right away. + +To handle this, there's a new component system variable called [`component_masking_functions.dictionaries_flush_interval_seconds()`](data-masking-function-list.html#dictionaries_flush_interval_secondsinteger-unsigned) + +By default, it's set to 0. When you set it higher, the system starts a background process that refreshes the cache at your specified interval. This helps replicas stay in sync after receiving binary log updates. The value specifies the number of seconds between each sync. ## Data masking techniques @@ -8,5 +49,19 @@ The common data masking techniques are the following: | Technique | Description | | --- | --- | -| Custom string | Replaces sensitive data with a specific string, such as a phone number with XXX-XXX-XXXX | -| Data substitution | Replaces sensitive data with realistic alternative values, such as city name with another name from a dictionary | \ No newline at end of file +| Character substitution | Replaces sensitive data with a matching symbol (X,*). For example, a phone number becomes XXX-XXX-XXXX. | +| Value generation | Replaces sensitive data with realistic-looking alternative values. For example, for testing purposes, you can generate a realistic alternative United States Social Security Number. | + +## Additional resources + +Component: + +[Install the data masking component](install-data-masking-component.md) + +[Data masking component functions](data-masking-function-list.md) + +Plugin: + +[Install data masking plugin](install-data-masking-plugin.md) + +[Data masking plugin funtions](data-masking-plugin-functions.md)