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

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@ss!2024';
$saltHex = 'a1b2c3d4e5f678901234567890abcdef0123456789abcdef0123456789abcdef'; // 64字符 hex

try {
    $sg12 = new Encryptor([
        'password'   => $masterPassword,
        'salt'       => hex2bin($saltHex), // 必须为二进制格式（32字节）
        'iterations' => 600000,
        'tag_length' => 16, // GCM 认证标签长度（默认16）
    ]);

    echo "✅ SG12 初始化成功\n";
} catch (Exception $e) {
    throw new RuntimeException("SG12 配置失败：" . $e->getMessage());
}
?>

4. 加密与解密实战

SG12 返回标准 Base64 编码的密文（含 nonce + ciphertext + auth tag），解密时自动验证完整性：

<?php
$data = "用户敏感信息：身份证号 110101199003072XXX，手机号 138****1234";

// 🔐 加密
$ciphertext = $sg12->encrypt($data);
echo "密文：" . $ciphertext . "\n"; // 例：ZjYzYTU...（约120字符）

// 🔓 解密（自动校验，失败抛出 Sg12\DecryptionException）
$plaintext = $sg12->decrypt($ciphertext);
echo "明文：" . $plaintext . "\n"; // 输出原始数据
?>

⚠️ 安全提示： • salt 必须全局唯一且长期固定，切勿每次生成新 salt； • 密码严禁硬编码，生产环境务必使用 dotenv 或密钥管理服务（如 HashiCorp Vault）； • SG12 默认禁用弱密码检测，建议在初始化前校验密码强度（如用 zxcvbn-php）。

SG12 以简洁 API 实现工业级加密能力。正确配置后，可无缝集成至用户认证、数据库字段加密、API 请求签名等场景。更多高级用法（如自定义 AEAD 参数、密钥轮换策略），请参考 GitHub 官方仓库。

```