```html SG15加密工具使用指南｜PHP开发实战

SG15加密工具使用指南（PHP 实战篇）

SG15 是一款轻量级、国产开源的对称加密工具库，专为 PHP 8.0+ 设计，采用 AES-256-GCM 模式实现高性能加解密，具备认证加密（AEAD）能力，可有效防止篡改与重放攻击。本文将带你快速上手 SG15 的核心用法。

1. 安装与初始化

通过 Composer 安装（推荐）：

composer require sg15/sg15

初始化加密器（需提供 32 字节密钥）：

<?php
use SG15\Encryptor;

// 生成安全密钥（生产环境请存于配置中心或环境变量）
$key = random_bytes(32); // 或 hex2bin('your-32-byte-hex-key');

$encryptor = new Encryptor($key);
?>

2. 基础加解密示例

SG15 默认自动处理 nonce 生成与附加认证数据（AAD），开发者无需手动管理 IV：

<?php
$data = "用户敏感信息：身份证号 110101199003072***";
$ciphertext = $encryptor->encrypt($data);

echo "密文（Base64）：" . base64_encode($ciphertext) . "\n";

// 解密
$plaintext = $encryptor->decrypt($ciphertext);
echo "明文：" . $plaintext; // 输出原始数据
?>

3. 高级用法：带认证数据（AAD）

适用于需绑定上下文的场景（如用户ID + 订单号防篡改）：

<?php
$aad = ['user_id' => 10086, 'order_sn' => 'ORD20240520001'];
$ciphertext = $encryptor->encrypt($data, $aad);

// 解密时必须传入相同 AAD，否则抛出 AuthenticationException
try {
    $plaintext = $encryptor->decrypt($ciphertext, $aad);
} catch (SG15\Exception\AuthenticationException $e) {
    throw new Exception("数据已被篡改或 AAD 不匹配");
}
?>

4. 密钥安全建议

⚠️ 重要提醒： • 切勿硬编码密钥；推荐使用 openssl_random_pseudo_bytes(32) 生成并持久化至安全存储； • 同一密钥不宜长期使用，建议每季度轮换； • SG15 不内置密钥管理，可结合 Hashicorp Vault 或 AWS KMS 封装密钥获取逻辑。

SG15 已通过 PHPStan 严格类型检查，并覆盖全部加密边界用例（空字符串、Unicode、超长文本等）。其零依赖、无全局状态的设计，天然适配 Laravel、Symfony 等主流框架。

项目地址：https://github.com/sg15/sg15-php
文档与测试用例均开源可查，欢迎贡献 PR 与 Issue。

```