```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_PASSWORD'] ?? 'MyS3cur3P@ss!2024';
$saltHex = $_ENV['SG12_SALT_HEX'] ?? 'a1b2c3d4e5f678901234567890abcdef1234567890abcdef1234567890abcdef';

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

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

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

echo "原文: {$plaintext}\n";
echo "密文: " . base64_encode($ciphertext) . "\n";
echo "解密: {$decrypted}\n";
// 输出一致，且解密失败时抛出 Sg12\Exception\DecryptionException
?>

4. 进阶配置建议

若需多租户隔离，可为不同业务生成独立 Encryptor 实例：

// 按租户 ID 动态生成盐值（仍需保证全局唯一性）
function getTenantSalt(string $tenantId): string {
    return substr(hash_hmac('sha256', $tenantId, 'SG12_GLOBAL_SEED'), 0, 32);
}

$tenantEncryptor = new Encryptor([
    'password' => $tenantKey,
    'salt'     => hex2bin(getTenantSalt('tenant_001')),
]);

结语

SG12 以“开箱即用的安全性”为目标，避免开发者手动处理 IV、AEAD 标签等易错环节。正确配置后，即可在用户凭证存储、API 密钥保护、数据库字段加密等场景中安全落地。记住核心原则：密钥不硬编、盐值要唯一、迭代够充分、异常必捕获。

更多细节请查阅 GitHub 官方仓库。

```