6.5.5 MySQL Enterprise Data Masking and De-Identification Function Descriptions — MySQL 5.7

6.5.5 Описания функций маскирования и обезличивания данных MySQL Enterprise

Библиотека плагинов MySQL Enterprise Data Masking and De-Identification содержит несколько функций, которые можно разделить на следующие категории:

Эти функции обрабатывают строковые аргументы как двоичные строки (то есть не различают регистр букв), а строковые значения возврата являются двоичными строками. Если строковое значение возврата должно быть в другом наборе символов, преобразуйте его. Следующий пример демонстрирует, как преобразовать результат gen_rnd_email() в набор символов utf8mb4:

SET @email = CONVERT(gen_rnd_email() USING utf8mb4);

Также может потребоваться преобразовать строковые аргументы, как показано в Использовании замаскированных данных для идентификации клиентов.

Если функция MySQL Enterprise Data Masking and De-Identification вызывается из клиента mysql, двоичные строковые результаты отображаются в шестнадцатеричном формате, в зависимости от значения параметра --binary-as-hex. Дополнительную информацию об этом параметре см. в разделе 4.5.1, «mysql — Клиент командной строки MySQL».

Функции маскирования

Каждая функция в этом разделе выполняет операцию маскирования своего строкового аргумента и возвращает замаскированный результат.

mask_inner(str, margin1, margin2 [, mask_char])

Маскирует внутреннюю часть строки, оставляя концы нетронутыми, и возвращает результат. Можно указать необязательный символ маскирования.

Аргументы:
- str: Строка для маскирования.
- margin1: Неотрицательное целое число, определяющее количество символов слева от строки, которые не будут замаскированы. Если значение равно 0, не будет замаскированных символов слева.
- margin2: Неотрицательное целое число, определяющее количество символов справа от строки, которые не будут замаскированы. Если значение равно 0, не будет замаскированных символов справа.
- mask_char: (Необязательно) Одиночный символ для маскирования. По умолчанию используется 'X', если mask_char не указан.
  
  Символ маскирования должен быть символом с одним байтом. Попытка использования символа с несколькими байтами приводит к ошибке.
Значение возврата:

Замаскированная строка или NULL, если любой из отступов отрицательный.

Если сумма отступов больше длины аргумента, маскирование не выполняется, и аргумент возвращается без изменений.

Пример:
```
mysql> SELECT mask_inner('abcdef', 1, 2), mask_inner('abcdef',0, 5);
+----------------------------+---------------------------+
| mask_inner('abcdef', 1, 2) | mask_inner('abcdef',0, 5) |
+----------------------------+---------------------------+
| aXXXef                     | Xbcdef                    |
+----------------------------+---------------------------+
mysql> SELECT mask_inner('abcdef', 1, 2, '*'), mask_inner('abcdef',0, 5, '#');
+---------------------------------+--------------------------------+
| mask_inner('abcdef', 1, 2, '*') | mask_inner('abcdef',0, 5, '#') |
+---------------------------------+--------------------------------+
| a***ef                          | #bcdef                         |
+---------------------------------+--------------------------------+
```
mask_outer(str, margin1, margin2 [, mask_char])

Маскирует левые и правые концы строки, оставляя внутреннюю часть не замаскированной, и возвращает результат. Можно указать необязательный символ маскирования.

Аргументы:
- str: Строка для маскирования.
- margin1: Неотрицательное целое число, определяющее количество символов слева от строки, которые будут замаскированы. Если значение равно 0, не будет замаскированных символов слева.
- margin2: Неотрицательное целое число, определяющее количество символов справа от строки, которые будут замаскированы. Если значение равно 0, не будет замаскированных символов справа.
- mask_char: (Необязательно) Одиночный символ для маскирования. По умолчанию используется 'X', если mask_char не указан.
  
  Символ маскирования должен быть символом с одним байтом. Попытка использования символа с несколькими байтами приводит к ошибке.
Значение возврата:

Замаскированная строка, или NULL, если любой из отступов отрицательный.

Если сумма отступов больше длины аргумента, весь аргумент маскируется.

Пример:
```
mysql> SELECT mask_outer('abcdef', 1, 2), mask_outer('abcdef',0, 5);
+----------------------------+---------------------------+
| mask_outer('abcdef', 1, 2) | mask_outer('abcdef',0, 5) |
+----------------------------+---------------------------+
| XbcdXX                     | aXXXXX                    |
+----------------------------+---------------------------+
mysql> SELECT mask_outer('abcdef', 1, 2, '*'), mask_outer('abcdef',0, 5, '#');
+---------------------------------+--------------------------------+
| mask_outer('abcdef', 1, 2, '*') | mask_outer('abcdef',0, 5, '#') |
+---------------------------------+--------------------------------+
| *bcd**                          | a#####                         |
+---------------------------------+--------------------------------+
```

Функции генерации случайных данных

Функции в этом разделе генерируют случайные значения для различных типов данных. В возможных случаях сгенерированные значения обладают характеристиками, предназначенными для демонстрации или тестовых значений, чтобы избежать их ошибочного восприятия как реальных данных. Например, gen_rnd_us_phone() возвращает номер телефона США, использующий код области 555, который не присваивается номерам телефонов в реальном использовании. Подробные описания функций описывают все исключения из этого принципа.

gen_range(lower, upper)

Генерирует случайное число, выбранное из заданного диапазона.

Аргументы:
- lower: Целое число, определяющее нижнюю границу диапазона.
- upper: Целое число, определяющее верхнюю границу диапазона, которая не должна быть меньше нижней границы.
Возвращаемое значение:

Случайное целое число в диапазоне от lower до upper включительно, или NULL, если аргумент upper меньше lower.

Пример:
```
mysql> SELECT gen_range(100, 200), gen_range(-1000, -800);
+---------------------+------------------------+
| gen_range(100, 200) | gen_range(-1000, -800) |
+---------------------+------------------------+
|                 177 |                   -917 |
+---------------------+------------------------+
mysql> SELECT gen_range(1, 0);
+-----------------+
| gen_range(1, 0) |
+-----------------+
|            NULL |
+-----------------+
```
gen_rnd_email()

Генерирует случайный адрес электронной почты в домене example.com.

Аргументы:

Нет.

Возвращаемое значение:

Случайный адрес электронной почты в виде строки.

Пример:
```
mysql> SELECT gen_rnd_email();
+---------------------------+
| gen_rnd_email()           |
+---------------------------+
| ijocv.mwvhhuf@example.com |
+---------------------------+
```
gen_rnd_pan([size])

Генерирует случайный номер первичного счёта платёжной карты. Число проходит проверку Луна (алгоритм, выполняющий проверку контрольной суммы по контрольной цифре).

Предупреждение

Значения, возвращаемые функцией gen_rnd_pan(), должны использоваться только в тестовых целях и не подходят для публикации. Нет гарантии, что заданное возвращаемое значение не присвоено реальному платёжному счёту. Если необходимо опубликовать результат gen_rnd_pan(), рассмотрите возможность маскировки с помощью mask_pan() или mask_pan_relaxed().

Аргументы:
- size: (Необязательно) Целое число, определяющее размер результата. По умолчанию 16, если size не задано. Если задано, size должно быть целым числом в диапазоне от 12 до 19.
Возвращаемое значение:

Случайный платёжный номер в виде строки или NULL, если аргумент size находится вне допустимого диапазона.

Пример:
```
mysql> SELECT mask_pan(gen_rnd_pan());
+-------------------------+
| mask_pan(gen_rnd_pan()) |
+-------------------------+
| XXXXXXXXXXXX5805        |
+-------------------------+
mysql> SELECT mask_pan(gen_rnd_pan(19));
+---------------------------+
| mask_pan(gen_rnd_pan(19)) |
+---------------------------+
| XXXXXXXXXXXXXXX5067       |
+---------------------------+
mysql> SELECT mask_pan_relaxed(gen_rnd_pan());
+---------------------------------+
| mask_pan_relaxed(gen_rnd_pan()) |
+---------------------------------+
| 398403XXXXXX9547                |
+---------------------------------+
mysql> SELECT mask_pan_relaxed(gen_rnd_pan(19));
+-----------------------------------+
| mask_pan_relaxed(gen_rnd_pan(19)) |
+-----------------------------------+
| 578416XXXXXXXXX6509               |
+-----------------------------------+
mysql> SELECT gen_rnd_pan(11), gen_rnd_pan(20);
+-----------------+-----------------+
| gen_rnd_pan(11) | gen_rnd_pan(20) |
+-----------------+-----------------+
| NULL            | NULL            |
+-----------------+-----------------+
```
gen_rnd_ssn()

Генерирует случайный номер социального страхования США в формате AAA-BB-CCCC. Часть AAA больше 900, а часть BB меньше 70, что не характерно для действительных номеров социального страхования.

Аргументы:

Нет.

Возвращаемое значение:

Случайный номер социального страхования в виде строки.

Пример:
```
mysql> SELECT gen_rnd_ssn();
+---------------+
| gen_rnd_ssn() |
+---------------+
| 951-26-0058   |
+---------------+
```
gen_rnd_us_phone()

Генерирует случайный номер телефона США в формате 1-555-AAA-BBBB. Код области 555 не используется для реальных номеров телефонов.

Аргументы:

Нет.

Возвращаемое значение:

Случайный номер телефона США в виде строки.

Пример:
```
mysql> SELECT gen_rnd_us_phone();
+--------------------+
| gen_rnd_us_phone() |
+--------------------+
| 1-555-682-5423     |
+--------------------+
```

Функции, основанные на словарях случайных данных

Функции в этом разделе манипулируют словарями терминов и выполняют операции генерации и маскирования на их основе. Некоторые из этих функций требуют привилегии SUPER.

При загрузке словаря он становится частью реестра словарей и получает имя, используемое другими функциями словарей. Словари загружаются из текстовых файлов, содержащих по одному термину в строке. Пустые строки игнорируются. Для валидности файл словаря должен содержать как минимум одну ненулевую строку.

gen_blacklist(str, dictionary_name, replacement_dictionary_name)

Заменяет термин, присутствующий в одном словаре, термином из второго словаря и возвращает заменяющий термин. Это маскирует исходный термин заменой.

Аргументы:
- str: Строка, указывающая термин для замены.
- dictionary_name: Строка, которая называет словарь, содержащий термин для замены.
- replacement_dictionary_name: Строка, которая называет словарь, из которого выбирать заменяющий термин.
Возвращаемое значение:

Случайная строка, выбранная из replacement_dictionary_name, как замена str, или str, если он не появляется в dictionary_name, или NULL, если ни одно из имён словарей не находится в реестре словарей.

Если термин для замены встречается в обоих словарях, возможно, что возвращаемое значение будет тем же термином.

Пример:
```
mysql> SELECT gen_blacklist('Berlin', 'DE_Cities', 'US_Cities');
+---------------------------------------------------+
| gen_blacklist('Berlin', 'DE_Cities', 'US_Cities') |
+---------------------------------------------------+
| Phoenix                                           |
+---------------------------------------------------+
```
gen_dictionary(dictionary_name)

Возвращает случайный термин из словаря.

Аргументы:
- dictionary_name: Строка, которая называет словарь, из которого выбрать термин.
Возвращаемое значение:

Случайный термин из словаря в виде строки или NULL, если имя словаря отсутствует в реестре словарей.

Пример:
```
mysql> SELECT gen_dictionary('mydict');
+--------------------------+
| gen_dictionary('mydict') |
+--------------------------+
| My term                  |
+--------------------------+
mysql> SELECT gen_dictionary('no-such-dict');
+--------------------------------+
| gen_dictionary('no-such-dict') |
+--------------------------------+
| NULL                           |
+--------------------------------+
```
gen_dictionary_drop(dictionary_name)

Удаляет словарь из реестра словарей.

Для этой функции требуется привилегия SUPER.

Аргументы:
- dictionary_name: Строка, которая называет словарь для удаления из реестра словарей.
Возвращаемое значение:

Строка, которая указывает, успешно ли выполнена операция удаления. Dictionary removed означает успех. Dictionary removal error означает неудачу.

Пример:
```
mysql> SELECT gen_dictionary_drop('mydict');
+-------------------------------+
| gen_dictionary_drop('mydict') |
+-------------------------------+
| Dictionary removed            |
+-------------------------------+
mysql> SELECT gen_dictionary_drop('no-such-dict');
+-------------------------------------+
| gen_dictionary_drop('no-such-dict') |
+-------------------------------------+
| Dictionary removal error            |
+-------------------------------------+
```
gen_dictionary_load(dictionary_path, dictionary_name)

Загружает файл в реестр словарей и присваивает словарю имя для использования с другими функциями, требующими аргумент имени словаря.

Для этой функции требуется привилегия SUPER.

Важно

Словари не сохраняются. Любой словарь, используемый приложениями, должен загружаться для каждого запуска сервера.

После загрузки в реестр словарь используется как есть, даже если базовый файл словаря изменится. Для перезагрузки словаря сначала удалите его с помощью gen_dictionary_drop(), а затем загрузите его снова с помощью gen_dictionary_load().

Аргументы:
- dictionary_path: Строка, определяющая имя файла словаря.
- dictionary_name: Строка, предоставляющая имя для словаря.
Возвращаемое значение:

Строка, указывающая, прошла ли операция загрузки успешно. Dictionary load success означает успех. Dictionary load error означает неудачу. Неудачу загрузки словаря могут вызвать несколько причин, включая:
- Словарь с заданным именем уже загружен.
- Файл словаря не найден.
- Файл словаря не содержит терминов.
- Переменная системы secure_file_priv задана, и файл словаря не находится в каталоге, указанном переменной.
Пример:
```
mysql> SELECT gen_dictionary_load('/usr/local/mysql/mysql-files/mydict','mydict');
+---------------------------------------------------------------------+
| gen_dictionary_load('/usr/local/mysql/mysql-files/mydict','mydict') |
+---------------------------------------------------------------------+
| Dictionary load success                                             |
+---------------------------------------------------------------------+
mysql> SELECT gen_dictionary_load('/dev/null','null');
+-----------------------------------------+
| gen_dictionary_load('/dev/null','null') |
+-----------------------------------------+
| Dictionary load error                   |
+-----------------------------------------+
```