MySQL :: MySQL 8.3 Reference Manual :: 8.5.3.4 MySQL Enterprise Data Masking and De-Identification Plugin Function Descriptions

version 8.3

8.0 current

MySQL 8.3 Reference Manual / ... / MySQL Enterprise Data Masking and De-Identification Plugin Function Descriptions

8.5.3.4 MySQL 企业数据屏蔽和去标识插件函数描述

MySQL 企业数据屏蔽和去标识插件库包括多个函数，这些函数可以分为以下类别：

这些函数支持单字节 latin1 字符集的字符串参数和返回值。如果字符串返回值应该在不同的字符集中，需要将其转换。以下示例显示如何将 gen_rnd_email() 的结果转换为 utf8mb4 字符集：

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

也可能需要转换字符串参数，如使用屏蔽数据进行客户识别中所示。

如果从 mysql 客户端内部调用 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#####                         |
+---------------------------------+--------------------------------+

mask_pan(str)

掩盖付款卡主账号，并将号码与最后四位数字替换为'X'字符。

参数：

str：要掩盖的字符串。字符串必须是主账号的合适长度，但不进行其他检查。

返回值：

掩盖后的付款号码作为字符串。如果参数太短，返回原样。

示例：

mysql> SELECT mask_pan(gen_rnd_pan());
+-------------------------+
| mask_pan(gen_rnd_pan()) |
+-------------------------+
| XXXXXXXXXXXX9102        |
+-------------------------+
mysql> SELECT mask_pan(gen_rnd_pan(19));
+---------------------------+
| mask_pan(gen_rnd_pan(19)) |
+---------------------------+
| XXXXXXXXXXXXXXX8268       |
+---------------------------+
mysql> SELECT mask_pan('a*Z');
+-----------------+
| mask_pan('a*Z') |
+-----------------+
| a*Z             |
+-----------------+

mask_pan_relaxed(str)

掩盖付款卡主账号，并将号码与前六位和最后四位数字替换为'X'字符。前六位数字表明付款卡发行者。

参数：

str：要掩盖的字符串。字符串必须是主账号的合适长度，但不进行其他检查。

返回值：

掩盖后的付款号码作为字符串。如果参数太短，返回原样。

示例：

mysql> SELECT mask_pan_relaxed(gen_rnd_pan());
+---------------------------------+
| mask_pan_relaxed(gen_rnd_pan()) |
+---------------------------------+
| 551279XXXXXX3108                |
+---------------------------------+
mysql> SELECT mask_pan_relaxed(gen_rnd_pan(19));
+-----------------------------------+
| mask_pan_relaxed(gen_rnd_pan(19)) |
+-----------------------------------+
| 462634XXXXXXXXX6739               |
+-----------------------------------+
mysql> SELECT mask_pan_relaxed('a*Z');
+-------------------------+
| mask_pan_relaxed('a*Z') |
+-------------------------+
| a*Z                     |
+-------------------------+

mask_ssn(str)

掩盖美国社会保险号，并将号码与最后四位数字替换为'X'字符。

参数：

str：要掩盖的字符串。字符串必须是11个字符长。

返回值：

掩盖后的社会保险号码作为字符串，或者如果参数不是正确的长度，则返回错误。

示例：

mysql> SELECT mask_ssn('909-63-6922'), mask_ssn('abcdefghijk');
+-------------------------+-------------------------+
| mask_ssn('909-63-6922') | mask_ssn('abcdefghijk') |
+-------------------------+-------------------------+
| XXX-XX-6922             | XXX-XX-hijk             |
+-------------------------+-------------------------+
mysql> SELECT mask_ssn('909');
ERROR 1123 (HY000): Can't initialize function 'mask_ssn'; MASK_SSN: Error:
String argument width too small
mysql> SELECT mask_ssn('123456789123456789');
ERROR 1123 (HY000): Can't initialize function 'mask_ssn'; MASK_SSN: Error:
String argument width too large

随机数据生成插件函数

本节中的插件函数生成不同类型数据的随机值。尽可能地，生成的值具有演示或测试值的特征，以避免将它们误认为合法数据。例如，gen_rnd_us_phone()返回一个使用555区号的美国电话号码，该区号不用于实际使用的电话号码。个别函数描述将描述任何例外情况。

gen_range(lower, upper)

生成一个指定范围内的随机数字。

参数：

lower：一个指定范围下限的整数。
upper：一个指定范围上限的整数，必须不小于下限。

返回值：

从 lower 到 upper（包括）之间的随机整数，或者如果 upper 小于 lower 则为 NULL。

示例：

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])

生成一个随机的支付卡主账号。该号码通过 Luhn 检查（一种算法对校验数字进行验证）。

Warning

从 gen_rnd_pan() 返回的值仅供测试用途，不适合发布。不能保证某个返回值不被分配给合法的支付账户。如果需要发布 gen_rnd_pan() 结果，考虑使用 mask_pan() 或 mask_pan_relaxed() 进行掩码。

参数：

size：（可选）一个指定结果大小的整数。默认为 16，如果 size 未给出。如果给出，size 必须是一个介于 12 到 19 之间的整数。

返回值：

一个随机支付号码作为字符串，或者如果给定的 size 参数超出允许范围则为 NULL。

示例：

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)

用第二个字典中的术语替换第一个字典中的术语，并返回替换的术语。这通过替换屏蔽原始术语。该函数在 MySQL 8.0.23 中已弃用；请改用 gen_blocklist()。
gen_blocklist(str, dictionary_name, replacement_dictionary_name)

用第二个字典中的术语替换第一个字典中的术语，并返回替换后的术语。该函数将原始术语掩盖以进行替换。该函数从 MySQL 8.0.23 版本开始添加；请使用它代替 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 权限。

Important

词典不是持久的。任何应用程序使用的词典都必须在每次服务器启动时加载。

一旦加载到注册表中，词典将被使用，即使底层词典文件发生变化。要重新加载词典，首先使用 gen_dictionary_drop() 删除它，然后使用 gen_dictionary_load() 重新加载。

参数：
- dictionary_path：指定词典文件路径的字符串。
- dictionary_name：提供词典名称的字符串。
返回值：

指示加载操作是否成功的字符串。词典加载成功 表示成功。词典加载错误 表示失败。词典加载失败可能是由于多种原因，包括：
- 已经加载了同名词典。
- 找不到词典文件。
- 词典文件不包含任何术语。
- 设置了 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                   |
+-----------------------------------------+
```

PREV HOME UP NEXT