```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';

// 初始化加密器（自动处理 salt/nonce 生成与绑定）
$encryptor = new Encryptor([
    'key'      => $masterKey,
    'iterations' => 600000, // PBKDF2 迭代次数（≥60万为佳）
    'cipher'   => 'AES-256-GCM',
    'tag_length' => 16,
]);

// 加密示例
$plaintext = "用户ID: U2024-789 | 订单金额: ¥299.00";
$ciphertext = $encryptor->encrypt($plaintext);

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

echo "原文: {$plaintext}\n";
echo "密文: " . base64_encode($ciphertext) . "\n";
echo "解密: {$decrypted}\n";
// 输出一致，且验证通过（GCM 自动校验 tag）
?>

4. 生产环境关键配置建议

⚠️ 安全提醒：以下配置直接影响密钥生命周期与抗攻击能力，请严格遵循：

密钥管理：主密钥必须通过环境变量或密钥管理系统（如 HashiCorp Vault）注入，禁止写入代码或配置文件；
迭代强度：生产环境建议 iterations ≥ 600000，平衡安全性与性能；
密文存储：SG12 返回的密文为二进制，建议 base64_encode() 后持久化（数据库/缓存）；
错误处理：解密失败时抛出 Sg12\DecryptionException，需捕获并记录（不泄露原始错误）。

5. 扩展：多密钥轮换支持

SG12 支持密钥版本标识，便于平滑升级：

// 使用带版本的密钥（v2 密钥用于新数据）
$v2Encryptor = new Encryptor([
    'key'       => $_ENV['SG12_MASTER_KEY_V2'],
    'version'   => 'v2', // 自动在密文头部嵌入版本标记
    'iterations'=> 800000,
]);

// 兼容旧密钥解密（v1 数据仍可用 v1 密钥解）
$legacyEncryptor = new Encryptor(['key' => $_ENV['SG12_MASTER_KEY_V1'], 'version' => 'v1']);

SG12 以「最小配置、最大安全」为设计哲学。正确配置后，您可放心将敏感字段（如手机号、身份证号、支付凭证）交由其加密保护。记住：加密不是银弹——密钥安全、传输加密（HTTPS）、权限隔离，同样不可或缺。

```