PHP 8.4怎么实现API接口数据加密传输-平芜编程栈

前言

先澄清一个常见误解：把请求体加密并不等于「传输安全」。HTTPS（TLS）解决的恰恰就是传输安全——防窃听、防篡改、防中间人。如果只做应用层加密却不上 HTTPS，中间人完全可以降级、替换公钥、重放到你的接口。

那应用层再加密一层有什么用？在真实项目里它解决的是 TLS 管不到的地方：

链路终点之后的明文：TLS 在网关处终止，之后再转发的一段通常是明文，日志系统、APM、反向代理都可能记录完整报文。
字段级合规要求：某些行业规范要求敏感字段（证件号、银行卡、健康数据）在「报文层面」就必须是密文，而不是只依赖链路。
跨系统对账留痕：加密信封能证明某个字段在传输过程中没有被任何中间环节改写。

本文讲的是信封加密（envelope encryption）：用 AES-256-GCM 加密业务数据，再用接收方的 RSA 公钥包裹这把临时对称密钥。它的好处是既能加密大报文（对称算法快），又不需要在发送方存放对称密钥（只有接收方能解开）。

关于版本：标题里的 PHP 8.4 指的是运行环境版本，不是加密能力的引入版本。openssl_*系列函数和sodium_*系列函数早在 8.4 之前就存在，加密算法本身与 PHP 版本无关；8.4 带来的是写起来更舒服的语法——属性钩子（property hooks）、非对称可见性（asymmetric visibility）、array_find()。文中代码最低要求PHP 8.4。

一、方案选型：三种做法，只有一种该用

方案	用什么	密钥管理	适用场景	评价
只签名不加密	`hash_hmac('sha256', ...)`	双方共享一个密钥	防篡改，不要求保密	需要「可验证但不必保密」时够用
纯对称加密	`openssl_encrypt`+ 共享密钥	双方共享同一个 AES 密钥	系统间点对点、运维可控	密钥分发是弱点，成员一多就失控
信封加密	AES-256-GCM + RSA-OAEP	发送方只有公钥	面向不特定客户端、字段级加密	本文主推

信封加密的密钥分发是单向的：接收方公布公钥，私钥不出服务器。发送方每次请求临时生成一把对称密钥，用完即弃。即使公钥被替换，攻击者也无法解密——但前提是你通过可信渠道获取公钥，这也是纯应用层加密无法摆脱的信任起点问题，所以公钥要么硬编码在客户端，要么由已受 TLS 保护的接口下发。

还要明确一点：GCM 已经自带完整性认证（AEAD，authenticated encryption with associated data），解密时如果密文被改过，openssl_decrypt会直接返回false，所以不需要「先加密再额外 HMAC 一遍」；如果一定要额外加签名，绝不能复用同一把密钥。

二、PHP 8.4 里写起来更顺的部分

三处 8.4 的语法改进在这里特别顺手：

非对称可见性用来保护私钥：外部只能读，只有类自己内部的构造函数能写。

属性钩子把「base64 解码」这一步藏进读属性的动作里，调用方写$envelope->ciphertext拿到的就是解码后的二进制，不必到处写base64_decode。

<?php declare(strict_types=1); // 需要 PHP >= 8.4 final class KeyPair { // PHP 8.4 非对称可见性：外部只读，内部可写 public private(set) string $secretKey; // PHP 8.1 的 readonly 在这里正好 public readonly string $publicKey; public function __construct() { $res = openssl_pkey_new([ 'private_key_bits' => 2048, 'private_key_type' => OPENSSL_KEYTYPE_RSA, ]); if ($res === false) { throw new RuntimeException('生成密钥对失败'); } if (!openssl_pkey_export($res, $priv)) { throw new RuntimeException('导出私钥失败'); } $details = openssl_pkey_get_details($res); if ($details === false) { throw new RuntimeException('读取公钥失败'); } $this->secretKey = $priv; $this->publicKey = $details['key']; } }

三、完整可运行的信封加密实现

下面这份代码可以直接保存为envelope_demo.php运行，不需要任何 Composer 包，只需要openssl扩展：

<?php declare(strict_types=1); // 需要 PHP >= 8.4，扩展 openssl // 用法: php envelope_demo.php final class Sealed { public function __construct( public readonly string $ivB64, public readonly string $tagB64, public readonly string $ctB64, public readonly string $wrappedB64, ) {} public function toJson(): string { return json_encode([ 'v' => 1, 'alg' => 'AES-256-GCM+RSA-OAEP', 'iv' => $this->ivB64, 'tag' => $this->tagB64, 'ct' => $this->ctB64, 'key' => $this->wrappedB64, ], JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES); } } /** * PHP 8.4 属性钩子：读的时候自动 base64 解码， * 解码失败直接抛异常，而不是悄悄返回空串。 * 只带 get 钩子的属性是「虚属性」，不占存储，只能读不能写。 */ final class Envelope { public string $ciphertext { get => base64_decode($this->ctB64, true) ?: throw new RuntimeException('密文不是合法 base64'); } public string $nonce { get => base64_decode($this->ivB64, true) ?: throw new RuntimeException('IV 不是合法 base64'); } public string $tag { get => base64_decode($this->tagB64, true) ?: throw new RuntimeException('tag 不是合法 base64'); } public function __construct( private string $ctB64, private string $ivB64, private string $tagB64, ) {} } final class EnvelopeCrypto { private const CIPHER = 'aes-256-gcm'; private const IV_LEN = 12; // GCM 推荐 96 bit private const AAD = 'api-payload-v1'; // 附加认证数据：参与校验但不加密 /** 发送方：加密 + 包裹密钥 */ public function seal(string $plaintext, string $publicKeyPem): string { $aesKey = random_bytes(32); // 每次请求新生成，绝不复用 $iv = random_bytes(self::IV_LEN); // 每次请求新 IV，绝不复用 $tag = ''; $ct = openssl_encrypt( $plaintext, self::CIPHER, $aesKey, OPENSSL_RAW_DATA, $iv, $tag, self::AAD, 16 ); if ($ct === false) { throw new RuntimeException('对称加密失败: ' . (openssl_error_string() ?: 'unknown')); } $wrapped = ''; if (!openssl_public_encrypt($aesKey, $wrapped, $publicKeyPem, OPENSSL_PKCS1_OAEP_PADDING)) { throw new RuntimeException('包裹密钥失败: ' . (openssl_error_string() ?: 'unknown')); } return (new Sealed( base64_encode($iv), base64_encode($tag), base64_encode($ct), base64_encode($wrapped), ))->toJson(); } /** 接收方：解包密钥 + 认证解密 */ public function open(string $json, string $privateKeyPem): string { $data = json_decode($json, true, 512, JSON_THROW_ON_ERROR); foreach (['iv', 'tag', 'ct', 'key'] as $field) { if (!isset($data[$field]) || !is_string($data[$field])) { throw new RuntimeException("信封缺少字段: {$field}"); } } $env = new Envelope($data['ct'], $data['iv'], $data['tag']); $wrappedKey = base64_decode($data['key'], true); if ($wrappedKey === false) { throw new RuntimeException('包裹密钥不是合法 base64'); } $aesKey = ''; if (!openssl_private_decrypt($wrappedKey, $aesKey, $privateKeyPem, OPENSSL_PKCS1_OAEP_PADDING)) { throw new RuntimeException('解包密钥失败：私钥不匹配或信封被改过'); } $plain = openssl_decrypt( $env->ciphertext, self::CIPHER, $aesKey, OPENSSL_RAW_DATA, $env->nonce, $env->tag, self::AAD ); if ($plain === false) { // 走到这里通常意味着：密文/tag/IV/AAD 任一项被改动 throw new RuntimeException('认证解密失败：数据完整性问题'); } return $plain; } } // ---------- 演示 ---------- $keys = new KeyPair(); $crypt = new EnvelopeCrypto(); $payload = json_encode([ 'user_id' => 10086, 'id_card' => '11010119900307XXXX', 'amount' => 199.00, ], JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR); $envelopeJson = $crypt->seal($payload, $keys->publicKey); echo "信封（可以直接放进请求体或 HTTP 头）:\n"; echo $envelopeJson . "\n\n"; $plain = $crypt->open($envelopeJson, $keys->secretKey); echo "解密结果:\n" . $plain . "\n"; echo $plain === $payload ? "往返一致 ✅\n" : "往返不一致 ❌\n"; // 篡改演示：改一个字符再解，必须失败 $tampered = substr_replace($envelopeJson, 'X', 60, 1); try { $crypt->open($tampered, $keys->secretKey); echo "篡改后仍能解密 ❌（说明校验有问题）\n"; } catch (RuntimeException $e) { echo "篡改被拦截 ✅: " . $e->getMessage() . "\n"; }

需要说明的是，openssl_public_encrypt用 OAEP 填充时，单次能包裹的明文长度受密钥长度限制（2048 位密钥下上限是两百多字节，远大于 32 字节的 AES 密钥）。不要用它去加密业务数据本身——业务数据必须走对称算法。

如果服务器装了sodium扩展，sodium_crypto_box_seal()/sodium_crypto_box_seal_open()提供匿名公钥加密，发送方不需要自己的密钥对，具体接口请以官方文档为准。

四、防重放：加密解决不了的第三件事

信封加密保证了机密性和完整性，但拦截下来的密文可以原样重放。所以还需要在信封外层加两个字段：

<?php declare(strict_types=1); final class ReplayGuard { /** 允许的时间窗口（秒） */ public function __construct(private int $windowSec = 300) {} public function build(array $payload, string $sharedSecret): array { $payload['_ts'] = time(); $payload['_nonce'] = bin2hex(random_bytes(16)); // 服务端需要用它去重 $payload['_sig'] = $this->sign($payload, $sharedSecret); return $payload; } public function verify(array $payload, string $sharedSecret): void { $sig = $payload['_sig'] ?? ''; unset($payload['_sig']); // 1) 恒定时间比较，避免时序侧信道 if (!hash_equals($this->sign($payload, $sharedSecret), (string) $sig)) { throw new RuntimeException('签名不匹配'); } // 2) 时间窗口 $ts = (int) ($payload['_ts'] ?? 0); if (abs(time() - $ts) > $this->windowSec) { throw new RuntimeException('时间戳超出允许窗口'); } // 3) nonce 去重（生产环境用 Redis SET NX 加 TTL） // 这里用文件仅作演示 $seen = sys_get_temp_dir() . '/nonce_' . md5((string) $payload['_nonce']); if (file_exists($seen)) { throw new RuntimeException('nonce 已被使用，疑似重放'); } file_put_contents($seen, '1', LOCK_EX); } private function sign(array $payload, string $secret): string { ksort($payload); // 顺序必须稳定，否则两端算出的签名不同 $data = json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES); return hash_hmac('sha256', (string) $data, $secret); } }

三点必须注意：ksort保证两端字段顺序一致；比较签名用hash_equals而不是==；nonce 的去重存储必须带过期时间，否则这个集合会无限膨胀。

常见坑点

1. 认为「加密了就不用 HTTPS」

❌ 内网接口用 HTTP，靠应用层 AES 保证安全。 ✅ 底层永远先上 TLS，应用层加密作为叠加的纵深防御。

没有 TLS，攻击者可以中间人替换公钥，之后你加密的所有内容他都能解。应用层加密的前提是公钥获取渠道可信，而这个可信度本身就建立在 TLS 上。

2. 复用 IV

❌ 用固定 IV，或把 IV 设成str_repeat('0', 12)。 ✅ 每次加密都random_bytes(12)生成新 IV，并随密文一起传输。

GCM 模式下 IV 复用是灾难性的：同一密钥下重复使用 IV 会导致密钥流重叠，攻击者可以通过异或两条密文恢复明文，甚至可以伪造认证标签。这是 AES-GCM 最严重的误用。

3. 用==比较签名

❌if ($computed === $received) { /* 通过 */ }✅if (hash_equals($computed, $received)) { /* 通过 */ }

普通字符串比较遇到第一个不同字符就返回，攻击者可以通过测量响应时间逐字节猜出签名。hash_equals是恒定时间比较。

4. 加密密钥和认证密钥共用一把

❌ 用同一个密钥既做 AES 加密又做 HMAC。 ✅ 两者的密钥必须独立派生。

在 GCM 场景下这条其实是多余的——GCM 已提供认证。如果要额外签名，用不同密钥。同密钥叠加加密与认证，在密码学上是明确的错误用法。

5. 私钥放在 Web 可访问目录

❌ 把private.pem放在public/或项目根目录。 ✅ 放在 Web 根目录之外，文件权限设成仅服务账户可读。

放在 Web 根下的.pem很容易因为没有 Nginx 的location ~ \.pem$拦截规则而被直接下载。这类泄露往往很久都发现不了。

6. 把解密后的明文写进日志

❌ 在中间件里记录解密后的完整请求体，方便排查问题。 ✅ 只记录字段名、长度、业务主键；敏感字段打码。

应用层加密的初衷就是躲开日志系统的明文残留，结果自己又把它记了一份，这个方案就白做了。

7. 不检查openssl_encrypt的返回值

❌$ct = openssl_encrypt(...); return base64_encode($ct);✅ 检查=== false，并把openssl_error_string()记进日志。

加密失败会返回false，base64_encode(false)会得到空串，于是你把一个空信封发出去，接收方报「解密失败」，排查方向完全被带偏。

总结

环节	该用什么	不该用什么	关键点
链路安全	TLS	只靠应用层加密	应用层加密不能替代 HTTPS
数据加密	AES-256-GCM	ECB、复用的 IV	IV 每次必须随机
密钥传递	RSA-OAEP 包裹临时密钥	双方硬编码同一 AES 密钥	私钥不出服务器
完整性	GCM 的认证标签	MD5、明文拼接做摘要	加密与认证密钥要独立
签名比较	`hash_equals`	`==`/`===`	防时序侧信道
防重放	时间戳 + nonce + TTL	只靠加密	密文本身可以原样重放
日志	字段名与长度	解密后的明文	别自己制造明文残留