PHP Sodium secretstream 怎么分块加密大文件

PHP Sodium secretstream 可以把大文件逐块交给 push() 加密，解密端保留同一个 pull() 状态，按原始消息边界逐块还原。实现时要一起解决三件事：保存初始化生成的 header、记录每块密文长度、检查经过认证的 FINAL 标签。仅仅把文件读到 EOF，不能证明收到的是一个完整加密流。

PHP 官方地址：https://www.php.net/manual/en/book.sodium.php

算法官方文档：https://libsodium.gitbook.io/doc/secret-key_cryptography/secretstream

规模扩大后，先改掉整文件驻留内存的结构

一个几兆字节文件可以整读处理，文件增大后，同样的做法会同时保留明文、密文和字符串临时副本。这里讨论的是架构上的内存增长原因，并不声称某台机器已经测得特定峰值。分块方案让应用每次只处理有界的数据，同时保留很小的流状态。

secretstream 处理的是有顺序的消息序列。初始化一次加密状态，随后连续调用 push；解密时使用 header 和同一密钥初始化另一份状态，再连续调用 pull。不要每读一块就重新初始化，也不要让并行任务共同修改同一份状态。它并不提供任意密文偏移处的独立随机读取。

文件格式要同时保存 header 和消息边界

下面设计一个教学用容器 SS01，它不是 Sodium 规定的通用文件格式。开头是四字节格式标识 SS01 和 HEADERBYTES 长度的 header，后面是若干帧。每帧包含四字节大端无符号密文长度，以及相应长度的密文。长度前缀加格式标识同时作为 additional_data，解密时必须原样传回。

这里选择每块最多 64 KiB，仅是示例参数。密文长度是明文长度加 ABYTES，不能按明文块长直接切割密文。底层文件读取也可能短读，因此解密端必须循环读满一个帧，而不是把每次 fread 的返回内容都直接传给 pull。

用空 FINAL 帧统一处理文件结束

下面给出配套的加密、解密函数和读写辅助函数。前提是 PHP 已启用 Sodium，运行环境为 64 位 PHP，输入输出是调用方已打开的阻塞本地文件流；不要传网络、非阻塞流或同一个文件的读写句柄。函数本身不管理打开与关闭，也不管理密钥托管。代码未在本文中运行，属于原创实现示例。

 SS_CHUNK + $overhead) {
                throw new RuntimeException('密文帧长度越界');
            }
            $cipher = ssReadExact($in, $length);
            $decoded = sodium_crypto_secretstream_xchacha20poly1305_pull(
                $state, $cipher, SS_MAGIC . $prefix
            );
            if ($decoded === false) {
                throw new RuntimeException('密文认证失败');
            }
            [$plain, $tag] = $decoded;
            if ($tag === SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL) {
                // 本示例格式要求 FINAL 明文为空，且之后没有任何字节。
                if ($plain !== '') {
                    throw new RuntimeException('结束帧格式错误');
                }
                $tail = fread($in, 1);
                if ($tail === false || $tail !== '' || !feof($in)) {
                    throw new RuntimeException('结束帧之后仍有数据或读取失败');
                }
                return;
            }
            if ($tag !== SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE
                || $plain === '') {
                throw new RuntimeException('不支持的消息帧');
            }
            ssWriteAll($out, $plain);
        }
    } finally {
        sodium_memzero($state);
    }
}

加密端不需要猜最后一个非空块是不是文件末尾：所有数据块都使用 MESSAGE，读完后再写一条明文为空的 FINAL。空文件也会有结束帧，大小正好是 65536 的整数倍也不会漏掉结束标记。与把 FINAL 放在最后一条数据帧相比，这种约定多付出一个帧的长度字段和认证开销，换来更简单的结束逻辑。

密钥应是符合 KEYBYTES 长度的二进制字符串，可由 sodium_crypto_secretstream_xchacha20poly1305_keygen() 生成；不要直接把用户输入的普通口令当作密钥。加密端和解密端必须取得相同密钥，但密钥不能和 header 一起写进容器。本文不展开密钥分发或托管设计。

完整性由认证、FINAL 和文件尾约束共同表达

pull 返回 false 时立即失败，不能把失败块替换成空字符串继续拼接。返回成功后取出明文和标签；本容器只接受非空 MESSAGE 与空 FINAL。PUSH 标签表示一组消息结束，并不表示整个流结束，因此不把它当作 FINAL。REKEY 等标签也不属于本示例容器的允许集合。

一个被截断的文件可能包含多条认证成功的前缀消息，因此“已经解出一些内容”与“整个文件完整”是两件事。代码在 FINAL 之前遇到 EOF 会抛出异常；FINAL 之后存在额外字节也会失败。这是容器的明确约定，不允许把多个 secretstream 文件直接拼接当成同一个文件。

解密输出必须先写入调用方控制的私有暂存文件，只有 ssDecrypt 正常返回、写入刷新和关闭成功后，才交给业务使用或移到最终位置。任何异常都应废弃并清理暂存内容；不要把尚未确认 FINAL 的前缀直接覆盖到正式文件，也不要在该阶段向用户持续输出。加密失败时留下的半成品密文同样不应标成完成。打开的资源应由调用方在 finally 中关闭；暂存目录权限、目标替换规则和磁盘持久化策略由应用部署约定。

落地时观察哪些信号，哪些结论不能提前下

分块设计使代码缓冲规模随块上限变化，而不是随整个文件长度变化；PHP 字符串复制和运行时开销仍存在，不能把 64 KiB 当作进程内存峰值。应用可记录输入字节数、输出字节数、消息帧数、认证失败次数、缺少 FINAL 次数以及暂存写入失败次数，避免记录密钥、状态或明文。

这些是建议观察的运行信号，本文没有上线测量数据。调整块大小时，需要结合调用开销、存储吞吐与内存预算判断；帧上限属于格式约定，读写端必须一起变更。读取中的源文件应保持稳定，secretstream 本身不会替应用创建文件系统快照，也不会使不稳定源文件自动具有一致版本。

header 丢了，只有密钥还能解密吗？

本接口解密初始化需要与该流对应的 header。应把它作为容器必要部分保存；它不需要像密钥那样保密，但必须正确对应这一份流。

每次 fread 都固定读 65536 字节，可以不写长度吗？

只有容器另外明确规定且可靠保留每条消息边界时才可采用其他封装。本文允许数据块短读，因此显式保存长度；不能把一次读取调用的边界当作加密消息边界。

收到 FINAL 后还能继续调用 push 吗？

FINAL 表示这一条流的结束。新文件应重新初始化独立状态和 header；不要继续复用已结束的状态，也不要在同一解密状态上接受额外消息。

参考资料：libsodium 加密流文档、PHP 初始化加密状态、PHP push、PHP pull。