隐私

概览

NextPDF Enterprise Privacy 检测与所配置 PII 模式匹配的文本，并对其进行遮罩、抑制包含它的那些行，或将其替换为由一份加密静态映射支撑的可逆确定性假名。它移除与所配置规则匹配的内容，一如所测试的那样。它不保证 PII 被完全移除，也不是对监管合规的陈述。

可用性与授权

此能力随 NextPDF Enterprise（nextpdf/enterprise）发行，并以一份 Enterprise 层级的授权信封激活。一个没有该权益的部署不会加载此能力的类。对比各版本并获取授权。

安装

composer require nextpdf/enterprise:^3

概念概述

检测是基于模式的。一个检测器针对一个正则表达式模式注册表扫描文本，并内置了用于电子邮件地址、电话号码、美国社会安全号码、信用卡号码与台湾身份证号码的模式。部署可以注册额外的模式。检测只发现所配置的类型；一个没有任何模式匹配的值不会被检测到，而一个没有文本层的扫描页面不会产生任何匹配。

一个遮罩策略控制行为。在仅检测模式下，引擎返回发现项而不改变内容。在遮罩模式下，它将每个匹配的跨度替换为一个黑框、白框或文本替换。去标识器增加了一个抑制策略，移除包含匹配的整行，而不是遮罩各个跨度。每次运行返回原始文本的 SHA-256、被修改后的内容、一份逐项报告，以及一个被修改标志。

假名化按设计是可逆的。引擎将检测到的实体替换为确定性的、格式感知的假名，这些假名由对原始值与一个每会话种子求 HMAC 而派生，因此同一个值在一个会话内一致地映射，而不同会话之间的这些标记不会按确定性相等而关联。原始值到假名的映射会被序列化，并以 AES-256-GCM 与一个带版本的密钥在静态时加密，支持密钥轮换。再水化（rehydration）能还原原始值，但只有在使用正确的密钥与匹配的加密映射时才行；缺少它们，仅凭假名化后的文本无法还原原始值。

这些操作实现了去标识，它移除数据与人之间的关联——ISO/IEC 29100:2024 §2。假名化将一个标识符替换为一个别名，并且按定义，在单独持有映射的情况下是可逆的——ISO/IEC 29100:2024 §2。匿名化旨在不可逆地阻止识别——ISO/IEC 29100:2024 §2；本 Enterprise 表面执行的是模式范围内的遮罩、抑制与可逆假名化，而非匿名化。残余的再识别风险取决于去标识之后所剩余的属性——ISO/IEC 29100:2024 §2，而去标识降低但不消除该风险——ISO/IEC 29151:2017。请将输出视为“与所配置规则匹配的内容被移除或替换，一如所测试的那样”，而不是对 PII 被完全移除、不可逆性或监管合规的保证。

为何如此设计

可逆性是承重的选择。假名是对原始值与一个每会话种子求得的 HMAC-SHA256 输出，因此同一个值在一个会话中始终映射到同一个标记，文档的内部关系得以保留。每会话一个全新的随机种子意味着同一个值在不同会话之间不会映射到同一个标记，因此这些假名不会跨会话按确定性标记相等而关联，这在无需中央查表的情况下降低了确定性可链接性。该映射被有意保留——以 AES-256-GCM 在静态时加密——以便经授权的再水化能还原原始值；正是那份可逆性使这在 ISO/IEC 29100:2024 §2 之下成为假名化，而非匿名化。这一权衡是被接受的：成为敏感制品的是加密映射，而非假名化后的文本，因此机密性归结为密钥保管。格式感知的标记保留了每个实体的形状，因此下游解析器继续工作，代价是校验和验证器可能拒绝一个有形状但合成的值。

设计背景：遮罩不是一个黑色矩形。

API 表面

类型	种类	角色	稳定性	自
PiiDetector	class	基于模式的 PII 检测；支持自定义模式注册	stable	2.2.0
RedactionEngine	class	按策略进行仅检测或破坏性文本遮罩	stable	2.2.0
DeIdentifier	class	遮罩或行抑制策略分派	stable	2.2.0
RedactionPolicy	class	目标实体类型、遮罩开关、替换样式	stable	2.2.0
PseudonymizationEngine	class	确定性、格式感知的假名替换	stable	2.2.0
PrivacyGateway	class	文档范围内带审计的假名化/再水化	stable	2.2.0
RehydrationService	class	从一份加密映射还原原始值	stable	2.2.0
EncryptedMapSerializer	class	带密钥版本控制的 AES-256-GCM 静态映射序列化	stable	2.2.0
PrivacyAuditTrail	class	假名化/再水化操作的仅追加日志	stable	2.2.0
EntityType / RedactionStyle / DeIdentificationStrategy	enums	实体、样式与策略词汇	stable	2.2.0

按契约，审计轨迹是仅追加的：它记录一个会话 id、操作、实体计数、一个策略哈希、一个时间戳，以及一个租户 id。它不记录被检测到的值。

代码示例——快速开始

Detect and redact configured PII

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Enterprise\Privacy\PiiDetector;
use NextPDF\Enterprise\Privacy\RedactionEngine;
use NextPDF\Enterprise\Privacy\RedactionPolicy;

/**
 * Redact every configured entity type from text content.
 *
 * @param string $content The text to process.
 *
 * @return string The redacted text.
 */
function redactAll(string $content): string
{
    $engine = new RedactionEngine(new PiiDetector());

    return $engine->redact($content, RedactionPolicy::allEntities())
        ->redactedContent;
}

RedactionPolicy::allEntities() 以内置类型为目标。一个没有任何所配置模式匹配的值不会被遮罩。

代码示例——生产环境

Reversible pseudonymization with audit and safe logging

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Enterprise\Privacy\PrivacyGateway;
use NextPDF\Enterprise\Privacy\PrivacyPolicy;
use NextPDF\Enterprise\Privacy\EntityType;
use Psr\Log\LoggerInterface;

final readonly class DocumentDeidentifier
{
    public function __construct(
        private PrivacyGateway $gateway,
        private LoggerInterface $logger,
    ) {}

    /**
     * Pseudonymize a document and return the encrypted reversal map.
     *
     * @param non-empty-string                                      $text     Document text.
     * @param list<array{text: non-empty-string, type: EntityType}> $entities Detected entities.
     *
     * @return array{text: string, encrypted_map: non-empty-string}
     */
    public function process(string $text, array $entities): array
    {
        $policy = PrivacyPolicy::piiOnly('session-' . bin2hex(random_bytes(6)));
        $result = $this->gateway->pseudonymize($text, $entities, $policy);

        $this->logger->info('Pseudonymization complete', [
            'entityCount' => $result['entity_count'],
        ]);

        return ['text' => $result['text'], 'encrypted_map' => $result['encrypted_map']];
    }
}

日志记录只携带一个计数。它不携带文档文本、被检测到的值，或加密映射。

边界情况与陷阱

• 检测是模式范围内的。一个没有任何模式匹配的值不会被检测到。引擎不主张找到了所有个人数据，且结果不是一项 PII 被完全移除的保证。
• 扫描页面没有文本层。文本模式检测不产生任何匹配；如果需要先有文本，请与 Intelligence 可搜索叠加层表面结合使用。
• 假名化按定义是可逆的。任何持有正确密钥与匹配加密映射的人都能还原原始值。这不是匿名化；请勿将假名化的输出呈现为不可逆的。
• 格式感知的假名会保留一种形状（例如，一个类 ID 或类电子邮件的标记）。一个校验校验和的下游系统可能拒绝一个假名；这是预期之中的。
• 加密映射是那个敏感的制品。丢失它会使再水化变得不可能；连同其密钥泄露它，会使假名化可被第三方逆转。请将密钥保管与映射存储视为一项部署责任。
• 遮罩作用于传递给它的文本内容。它本身不会展平一张图像、移除一个缩略图，或剥除文档元数据；请相应地界定管线范围。

性能

检测成本随模式数量与文本长度而扩展。假名化为每个唯一实体增加一次 HMAC，并对映射加一道 AES-256-GCM 封装。1500 ms 的挂钟预算覆盖一份典型的商务文档。可复现性配置文件是 structural：假名对于固定种子是确定性的，但审计时间戳与随机会话种子在不同运行之间有所不同，因此两次运行在这些字段上会有差异。

安全说明

静态映射使用经过认证的加密。该映射以 AES-256-GCM 与一个带版本的密钥封装；缺少正确的密钥版本，再水化是不可能的。密钥生成、保管与轮换是部署的责任；库消费一个密钥，它不管理一个密钥库。审计轨迹是仅追加的，记录的是元数据，绝不记录被检测到的值。每一个规范性来源都被意译，且无一被复现。

数据驻留与 PII 缓解

检测、遮罩与假名化在宿主上的进程内运行。对于这些操作中的任何一项，文档内容都不会离开宿主。加密映射与任何再水化后的输出都是个人数据；它们存储在何处、由哪个司法管辖区处理，是库边界之外的部署责任。库执行模式范围内的去标识，一如所测试的那样；它不认证 GDPR、HIPAA 或任何其他监管合规，也不执行匿名化。残余的再识别风险取决于所剩余的属性——ISO/IEC 29151:2017。

安全遥测与日志清洗

库会抛出带结构化消息的带类型异常，且绝不会将被检测到的值、文档字节或加密映射放入异常文本。在此表面周围记录日志的部署必须记录计数与策略哈希——如生产环境示例所示——且不得将原始 PDF 载荷、被检测到的实体文本或假名映射记录到日志或 APM 后端。仅追加的审计轨迹是可安全保留的记录。

FIPS 模式行为

静态映射经由平台加密提供方使用 AES-256-GCM。当宿主运行一个经 FIPS 验证的提供方时，该操作在已验证的边界内运行。NextPDF Enterprise 执行结构化组装，其本身不是一个经 FIPS 验证的密码学模块，也不作任何 FIPS 认证主张。

符合性

主张	标准	条款
去标识移除数据与人之间的关联。	ISO/IEC 29100:2024	§2
假名化将一个标识符替换为一个别名，并在单独的映射下可逆。	ISO/IEC 29100:2024	§2
匿名化旨在不可逆地阻止识别（本表面不进行匿名化）。	ISO/IEC 29100:2024	§2
残余的再识别风险取决于所剩余的属性。	ISO/IEC 29100:2024	§2
隐私控制被施加于 PII。	ISO/IEC 29100:2024	§6.5
去标识降低但不消除残余风险。	ISO/IEC 29151:2017	de-identification controls
最小化去标识数据的可链接性。	ISO/IEC 29151:2017	PII minimization
施加控制以保护 PII。	ISO/IEC 29151:2017	controls

所有条款均为意译。NextPDF 不复现规范性文本。权威措辞请查阅已发布的标准。NextPDF 不作任何隐私法规合规主张；本页陈述的是所测试的去标识行为及其边界，而非一项经认证的合规状态。

行为契约

• 检测是模式范围内的：它只发现所配置的类型；一个没有任何模式匹配的值不会被检测到，而一个没有文本层的页面不会产生任何匹配。
• 一个遮罩策略选择仅检测、跨度替换（黑框/白框/文本）或整行抑制；每次运行返回原始文本的 SHA-256、被修改后的内容、一份逐项报告，以及一个被修改标志。
• 假名化按设计是可逆的：确定性的、由 HMAC 派生的假名在一个会话内一致，而再水化需要正确的密钥版本与匹配的 AES-256-GCM 静态映射。
• 仅追加的审计轨迹记录会话 id、操作、实体计数、策略哈希、时间戳，以及租户 id——绝不记录被检测到的值。
• 输出是“与所配置规则匹配的内容被移除或替换，一如所测试的那样”，而不是对 PII 被完全移除、不可逆性或监管合规的保证。

发布边界

本页仅记述外部可观察的行为与受支持的公共 API 表面。内部命名空间路径、辅助类、机制表、运行手册文件名，以及工单前缀不在范围之内。

Core 回退

NextPDF Core（Apache-2.0）没有 PII 检测、遮罩或假名化表面——没有；此能力没有 Core 层级的等价物。

Pro 回退

NextPDF Pro 发行一个文本层 PII 检测表面与生成时遮罩；它不提供可逆假名化、加密的静态映射、行抑制，或仅追加的审计轨迹。那些仅发行于 nextpdf/enterprise 软件包中。

Enterprise 边界说明

检测、遮罩、抑制与假名化在行为层面描述。库消费一个加密密钥；它不管理一个密钥库，且密钥生成、保管与轮换的内部实现不在公共表面的范围内。

部署边界

加密映射与任何再水化后的输出都是个人数据；它们存储在何处、由哪个司法管辖区处理，是库边界之外的部署责任。密钥生成、保管与轮换是部署的责任——库消费一个密钥版本，它不管理一个密钥库。丢失该映射会使再水化变得不可能；连同其密钥泄露它，会使假名化可被第三方逆转。

法律合规边界

静态映射使用经过认证的加密。库执行模式范围内的去标识，一如所测试的那样，且不认证 GDPR、HIPAA 或任何其他监管合规，也不执行匿名化。本文档不是法律意见；请咨询你自己的合规与法律顾问。

另请参阅

• Privacy reference——Privacy 模块的完整公共 API 表面。
• Pro security——Pro 遮罩与文本层 PII 检测。
• Forensics——只读的修订历史分析。
• NextPDF Enterprise——完整的 Enterprise 功能表面。
• Privacy policy——文档项目自身的数据处理。
• PII · Pseudonymization · De-identification · AES-GCM——术语表条目。