8.5.3.4 MySQL Enterprise Data Masking and De-Identification Plugin Function Descriptions — MySQL 8.4

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

Библиотека плагина маскирования и обезличивания данных MySQL Enterprise содержит несколько функций, которые можно сгруппировать в следующие категории:

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

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

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

Если функция маскирования данных MySQL Enterprise вызывается из клиента mysql, результаты бинарных строк отображаются в шестнадцатеричном формате, в зависимости от значения опции --binary-as-hex. Дополнительную информацию об этой опции см. в разделе 6.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])

Генерирует случайный номер платежной карты Primary Account Number. Число проходит проверку Луна (алгоритм проверки контрольной суммы по контрольной цифре).

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

Значения, возвращаемые 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)

Заменяет термин, присутствующий в одном словаре, термином из второго словаря и возвращает заменяющий термин. Это маскирует исходный термин заменой. Эта функция устарела; используйте gen_blocklist() вместо неё.
gen_blocklist(str, dictionary_name, replacement_dictionary_name)

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

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

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

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

Пример:
```
mysql> SELECT gen_blocklist('Berlin', 'DE_Cities', 'US_Cities');
+---------------------------------------------------+
| gen_blocklist('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                   |
+-----------------------------------------+
```