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

version 8.4

8.0 current

MySQL 8.4 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，则无右端字符保持不masked。
- mask_char：（可选）用于masking的单个字符。默认是 'X'，如果未指定mask_char。
  
  masking 字符必须是一个单字节字符。尝试使用多字节字符将产生错误。
返回值：

masked 字符串，或者如果两个边缘都为负则返回 NULL。

如果边缘和参数长度之和大于参数长度，则不进行masking，并返回原参数。

示例：
```
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])

将字符串的左端和右端mask，留下中间部分不masked，并返回结果。可以指定可选的masking 字符。

参数：

str：要mask 的字符串。
margin1：一个非负整数，指定字符串左端字符的数量。如果值为0，则无左端字符被mask。
margin2：一个非负整数，指定字符串右端字符的数量。如果值为0，则无右端字符被mask。
mask_char: (可选) 用于mask的单个字符。默认情况下，如果不提供mask_char，则使用 'X'。

masking 字符必须是单字节字符。尝试使用多字节字符将产生错误。

返回值：

masked 字符串，或者如果两个边缘值都为负则返回 NULL。

如果边缘值之和大于参数长度，则整个参数将被mask。

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)

将付款卡主账户号码mask，返回所有但最后四位数字被 'X' 字符替换。

参数：

str: 需要mask的字符串。该字符串必须是主账户号码的合适长度，但否则不进行检查。

返回值：

masked 付款号码作为字符串。如果参数短于要求，返回未变。

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)

将付款卡主账户号码mask，返回所有但第六位和最后四位数字被 'X' 字符替换。前六位数字表示付款卡发卡机构。

str: 需要mask的字符串。该字符串必须是Primary Account Number的合适长度，但否则不进行检查。

返回值：

masked payment number 作为字符串。如果参数短于要求，它将保持不变。

示例：

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)

将美国社会安全号码mask，返回所有但最后四位数字被'X'字符替换。

参数：

str: 需要mask的字符串。该字符串必须是11个字符长。

返回值：

masked 社会安全号码作为字符串，或者如果参数不是正确长度时报错。

示例：

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>。

返回值：

在<lower>到<upper>之间的随机整数，包括<upper>，或者如果<upper>小于<lower>则为<code class="literal">NULL</code>。

示例：

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必须在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     |
+--------------------+
```

本节中的插件函数根据词典来操作词典和执行生成和masking操作。这些函数中的一些需要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 中随机选择一个字符串，或者如果不在 dictionary_name 中，则选择 str，否则返回 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: 指定要删除的词典名称。

返回值：

一个字符串，表示drop操作是否成功。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: 一个字符串，提供字典的名称。
返回值：

一个字符串，指示加载操作是否成功。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                   |
+-----------------------------------------+
```

PREV HOME UP NEXT