```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 构造函数注入，保障环境隔离性：

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

use Sg12\Encryptor;

// ✅ 推荐：从环境变量加载主密钥（避免硬编码）
$masterKey = $_ENV['SG12_MASTER_KEY'] ?? 'your-32-byte-secret-key-here-123456789012';

// 配置选项（全部可选，默认已优化安全参数）
$options = [
    'cipher'     => 'AES-256-GCM',      // 加密算法（固定）
    'key_length' => 32,                 // 密钥长度（字节）
    'iterations' => 600_000,            // PBKDF2 迭代次数（≥300k）
    'salt_bytes' => 16,                 // 盐值长度
    'nonce_bytes'=> 12,                 // GCM nonce 长度（RFC 8452 推荐）
];

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

4. 加密与解密示例

SG12 自动处理 salt、nonce 与认证标签（auth tag），输出为 Base64 编码的 JSON 字符串，便于存储或传输：

// 加密敏感数据
$plaintext = "user_id=1024&token=abcxyz&exp=1717023600";
$ciphertext = $sg12->encrypt($plaintext);

echo "🔐 加密结果：\n" . $ciphertext . "\n";

// 解密（自动验证完整性与防篡改）
$decrypted = $sg12->decrypt($ciphertext);
echo "🔓 解密结果：\n" . $decrypted . "\n";

// 输出一致且无异常 → 配置正确 ✅
assert($decrypted === $plaintext);

⚠️ 安全提示： • 生产环境务必使用 openssl_random_pseudo_bytes() 或 random_bytes() 生成强随机密钥； • 主密钥应通过环境变量或密钥管理服务（如 HashiCorp Vault）注入，严禁写入代码或 Git； • 建议定期轮换密钥，并保留旧密钥用于历史数据解密（SG12 支持多密钥上下文）。

5. 进阶：多密钥策略配置

适用于微服务场景下的密钥分域管理：

$encryptor = new Encryptor($masterKey, [
    'key_context' => 'payment_v2', // 生成唯一派生密钥
    'iterations'  => 1_000_000,
]);

至此，SG12 已在您的 PHP 应用中安全就绪。其零配置默认值兼顾易用性与安全性，是替代自研加密逻辑的理想选择。

—— 文章完｜SG12 v1.2.x · 2024 更新

```