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，可调高增强抗暴力能力）

示例配置代码：

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

use Sg12\Encryptor;

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

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

// 加密示例
$plaintext = "用户ID: U-2024-789 | 订单金额: ¥1,299.00";
$ciphertext = $encryptor->encrypt($plaintext);
echo "密文（Base64）: " . base64_encode($ciphertext) . "\n";

// 解密验证
$decrypted = $encryptor->decrypt($ciphertext);
echo "解密结果: " . $decrypted . "\n";
// 输出一致：用户ID: U-2024-789 | 订单金额: ¥1,299.00
?>

4. 生产环境最佳实践

SG12_MASTER_PASS=Zx9#kL2$mQv@pR8t
SG12_SALT_HEX=4a7f1c...（32字节随机生成）

生成安全盐值推荐命令：

php -r "echo bin2hex(random_bytes(32)); echo \"\n\";"

5. 高级配置（可选）

如需自定义 AEAD 关联数据（AAD），可传入第四个参数：

$ciphertext = $encryptor->encrypt($data, $aad = ['context' => 'payment_v2', 'tenant_id' => 'T-001']);

该 AAD 将参与 GCM 认证，任何篡改均导致解密失败（抛出 Sg12\DecryptionException）。

SG12 设计简洁、零依赖、严格遵循 RFC 5116，是替代简单 openssl_encrypt() 调用的理想选择。正确配置后，即可在数据库字段加密、API 请求体保护、配置文件敏感项隐藏等场景中安全落地。