```html

SG12加密工具配置方法（PHP 实战指南）

SG12 是一款轻量级、面向企业级数据安全的对称加密工具，采用 AES-256-GCM 模式，内置密钥派生（PBKDF2-SHA256）、自动 nonce 管理与完整性校验。本文将手把手演示如何在 PHP 项目中完成 SG12 的安装、初始化与安全配置。

1. 环境准备

确保 PHP ≥ 7.4，启用 openssl 和 mbstring 扩展：

# 检查扩展
php -m | grep -E "openssl|mbstring"

2. 安装 SG12（推荐 Composer 方式）

执行以下命令安装官方维护的封装库：sg12/encryptor：

composer require sg12/encryptor:^1.2

3. 基础配置与初始化

SG12 不依赖全局状态，所有配置通过 Sg12\Encryptor 构造函数传入。关键参数如下：

• password：主密码（建议 ≥ 16 字符，含大小写字母+数字+符号）
• salt：固定盐值（32 字节十六进制字符串，用于 PBKDF2）
• iterations：密钥派生迭代次数（默认 600,000，≥ 100,000）

完整配置示例：

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

use Sg12\Encryptor;

// ✅ 推荐：从环境变量读取敏感配置
$masterPassword = $_ENV['SG12_MASTER_PASS'] ?? 'MyS3cur3P@ssw0rd!2024';
$saltHex = $_ENV['SG12_SALT'] ?? 'a1b2c3d4e5f678901234567890abcdef1234567890abcdef1234567890abcdef';

// 初始化加密器（自动处理密钥派生与上下文隔离）
$encryptor = new Encryptor([
    'password'   => $masterPassword,
    'salt'       => hex2bin($saltHex), // 必须为二进制格式
    'iterations' => 600000,
]);

// 加密敏感数据
$plaintext = "user_id=12345&token=abcde-fghij-klmno";
$ciphertext = $encryptor->encrypt($plaintext);

// 解密验证
$decrypted = $encryptor->decrypt($ciphertext);

echo "原文: " . substr($plaintext, 0, 40) . "...\n";
echo "密文长度: " . strlen($ciphertext) . " 字节\n";
echo "解密成功: " . ($decrypted === $plaintext ? "✅" : "❌") . "\n";
?>

4. 生产环境最佳实践

示例 .env 配置：

SG12_MASTER_PASS=V3ry$tr0ngK3y!2024#Prod
SG12_SALT=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

5. 高级配置（可选）

如需自定义 GCM 标签长度（默认 16 字节）或禁用自动 base64 编码（返回原始二进制），可传入额外选项：

$encryptor = new Encryptor([
    'password' => $pwd,
    'salt'     => hex2bin($salt),
    'options'  => [
        'tag_length' => 16,      // 12–16 字节（GCM 标准）
        'encode'     => false,   // 返回 raw binary，适合数据库 BLOB 存储
    ]
]);

SG12 默认输出 Base64 编码的密文（便于 JSON/HTTP 传输），生产中可根据存储场景灵活选择。

掌握以上配置，即可在 Laravel、ThinkPHP 或原生 PHP 项目中安全集成 SG12。记住：加密不是银弹——密钥生命周期管理、访问控制与审计日志同样关键。

```