```html

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

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

1. 安装与环境准备

确保已安装 OpenSSL 扩展（PHP 默认启用），并通过 Composer 安装 SG15：

composer require sg15/sg15:dev-main

⚠️ 注意：SG15 当前处于活跃开发阶段（v0.3.x），建议锁定版本或关注其 GitHub 仓库：github.com/sg15/sg15-php

2. 基础用法示例

以下代码演示如何使用随机密钥加密敏感数据，并安全导出密文与初始化向量（IV）：

<?php
require_once 'vendor/autoload.php';

use SG15\SG15;

// 生成 32 字节主密钥（生产环境请使用安全随机源，如 sodium_crypto_secretbox_keygen()）
$masterKey = random_bytes(32);

// 实例化加密器（自动选择 AES-256-GCM + HKDF 密钥派生）
$sg = new SG15($masterKey);

// 加密字符串（返回关联数组：['ciphertext', 'iv', 'tag', 'salt']）
$encrypted = $sg->encrypt("用户支付金额：¥299.00 | 订单ID: ORD-2024-7890");

echo "密文（Base64）：" . base64_encode($encrypted['ciphertext']) . "\n";
echo "认证标签（Tag）：" . bin2hex($encrypted['tag']) . "\n";

// 解密验证
try {
    $decrypted = $sg->decrypt($encrypted);
    echo "解密结果：" . $decrypted; // 输出原始明文
} catch (Exception $e) {
    echo "解密失败：{$e->getMessage()}";
}
?>

3. 生产环境最佳实践

示例：从环境变量读取密钥并启用自动盐值管理：

$keyFromEnv = $_ENV['SG15_MASTER_KEY'] ?? '';
if (empty($keyFromEnv)) {
    throw new RuntimeException('SG15_MASTER_KEY 未配置');
}
$sg = new SG15(hex2bin($keyFromEnv), [
    'auto_salt' => true,   // 自动为每次加密生成唯一 salt（增强抗彩虹表能力）
    'ttl'       => 3600,   // 可选：设置密文有效期（秒），decrypt 时自动校验时间戳
]);

4. 与其他系统的互操作性

SG15 兼容标准 AES-GCM 格式，输出结构符合 RFC 5116。若需与 Node.js 或 Python（PyCryptodome）互通，只需确保：

• 使用相同密钥、IV 长度（12 字节）、认证标签长度（16 字节）
• 明文编码统一为 UTF-8
• 盐值（salt）和附加认证数据（AAD）字段保持一致

SG15 是注重安全与易用性的现代 PHP 加密方案。它不替代 OpenSSL 扩展，而是以更高层 API 封装最佳实践，助你规避常见陷阱——如 ECB 模式误用、IV 重用、缺少完整性校验等。

🔐 安全无小事，加密有规范。从今天起，让 SG15 成为你 PHP 应用的数据守门人。

```