PHP项目如何实现文件加密存储？

wen PHP项目 2026-06-17 5

本文目录导读：

PHP项目如何实现文件加密存储？

核心原则
使用 OpenSSL 扩展实现 AES-256-GCM
使用 libsodium 扩展（推荐，更现代）
处理大文件（流式加密）
密钥存储与轮换
文件完整性校验
安全注意事项
完整示例：Web上传加密文件

在PHP项目中实现文件加密存储,通常涉及加密算法选择、密钥管理、加密/解密流程以及完整性校验，以下是几种常见的实现方案和最佳实践。

核心原则

不要使用过时算法：如MD5、SHA1（仅用于完整性校验）、RC4、DES。
推荐算法：
- 对称加密：AES-256-GCM（推荐，自带认证加密）、AES-256-CBC + HMAC。
- 非对称加密：RSA（用于加密对称密钥，而非直接加密大文件）。
密钥管理：密钥不能硬编码在代码中，应存储在环境变量、密钥管理服务（如AWS KMS、HashiCorp Vault）或加密配置文件中。
完整性校验：使用认证加密模式（如GCM）或附加HMAC，防止密文被篡改。

使用 OpenSSL 扩展实现 AES-256-GCM

PHP 的 openssl_encrypt / openssl_decrypt 是首选方案。

加密文件

<?php
function encryptFile(string $inputFile, string $outputFile, string $key): bool
{
    $plaintext = file_get_contents($inputFile);
    if ($plaintext === false) {
        return false;
    }
    $iv = openssl_random_pseudo_bytes(12); // GCM标准IV长度12字节
    $tag = '';
    $ciphertext = openssl_encrypt(
        $plaintext,
        'aes-256-gcm',
        $key,
        OPENSSL_RAW_DATA,
        $iv,
        $tag,
        '',
        16 // tag长度
    );
    if ($ciphertext === false) {
        return false;
    }
    // 存储格式：IV(12字节) + Tag(16字节) + 密文
    $encryptedData = $iv . $tag . $ciphertext;
    return file_put_contents($outputFile, $encryptedData) !== false;
}

解密文件

<?php
function decryptFile(string $inputFile, string $outputFile, string $key): bool
{
    $encryptedData = file_get_contents($inputFile);
    if ($encryptedData === false) {
        return false;
    }
    // 提取IV、Tag和密文
    $iv = substr($encryptedData, 0, 12);
    $tag = substr($encryptedData, 12, 16);
    $ciphertext = substr($encryptedData, 28);
    $plaintext = openssl_decrypt(
        $ciphertext,
        'aes-256-gcm',
        $key,
        OPENSSL_RAW_DATA,
        $iv,
        $tag
    );
    if ($plaintext === false) {
        return false; // 解密失败或数据被篡改
    }
    return file_put_contents($outputFile, $plaintext) !== false;
}

使用示例

// 生成一个256位（32字节）密钥
$key = random_bytes(32); // 实际应安全存储此密钥
encryptFile('/path/to/uploaded/file.pdf', '/path/to/encrypted/file.enc', $key);
decryptFile('/path/to/encrypted/file.enc', '/path/to/decrypted/file.pdf', $key);

使用 libsodium 扩展（推荐，更现代）

PHP 7.2+ 内置了 sodium 扩展，提供了更安全的加密 API。

加密文件

<?php
function sodiumEncryptFile(string $inputFile, string $outputFile, string $key): bool
{
    $plaintext = file_get_contents($inputFile);
    if ($plaintext === false) {
        return false;
    }
    $nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
    $ciphertext = sodium_crypto_secretbox($plaintext, $nonce, $key);
    // 存储：nonce + 密文
    $encryptedData = $nonce . $ciphertext;
    return file_put_contents($outputFile, $encryptedData) !== false;
}
function sodiumDecryptFile(string $inputFile, string $outputFile, string $key): bool
{
    $encryptedData = file_get_contents($inputFile);
    if ($encryptedData === false) {
        return false;
    }
    $nonceLength = SODIUM_CRYPTO_SECRETBOX_NONCEBYTES;
    $nonce = substr($encryptedData, 0, $nonceLength);
    $ciphertext = substr($encryptedData, $nonceLength);
    $plaintext = sodium_crypto_secretbox_open($ciphertext, $nonce, $key);
    if ($plaintext === false) {
        return false; // 数据被篡改或密钥错误
    }
    return file_put_contents($outputFile, $plaintext) !== false;
}

密钥生成（libsodium）

// libsodium的secretbox密钥长度固定为32字节
$key = sodium_crypto_secretbox_keygen();
// 或者从已有密码派生：sodium_crypto_pwhash()

处理大文件（流式加密）

当文件超过内存限制时,需要分块加密/解密。

流式 AES-256-CTR（无认证，需额外HMAC）

<?php
function streamEncrypt(string $inputFile, string $outputFile, string $key): bool
{
    $iv = openssl_random_pseudo_bytes(16);
    $handleIn = fopen($inputFile, 'rb');
    $handleOut = fopen($outputFile, 'wb');
    // 先写入IV（用于解密时恢复）
    fwrite($handleOut, $iv);
    // 初始化HMAC（可选，用于完整性校验）
    $hmacKey = hash_hkdf('sha256', $key, 32, 'hmac-key', $iv);
    $hmac = hash_init('sha256', HASH_HMAC, $hmacKey);
    while (!feof($handleIn)) {
        $chunk = fread($handleIn, 8192);
        $encryptedChunk = openssl_encrypt(
            $chunk,
            'aes-256-ctr',
            $key,
            OPENSSL_RAW_DATA,
            $iv
        );
        // CTR模式每块使用相同IV（安全），但通常使用递增计数器更安全
        fwrite($handleOut, $encryptedChunk);
        hash_update($hmac, $encryptedChunk);
    }
    // 写入最后的HMAC标签（固定长度32字节）
    fwrite($handleOut, hash_final($hmac, true));
    fclose($handleIn);
    fclose($handleOut);
    return true;
}

密钥存储与轮换

环境变量（.env 文件，生产环境使用系统环境变量）：
```
ENCRYPTION_KEY=base64:AbCdEf123456...   # 实际为32字节base64编码
```
在PHP中读取：$key = base64_decode(env('ENCRYPTION_KEY'));
密钥加密密钥（KEK）：使用更高级的密钥（如存储在HSM或KMS）来加密实际加密密钥。
密钥轮换：对每个文件保存加密时所用的密钥标识（如版本号），轮换时对文件重新加密（或使用信封加密：用新密钥加密文件，但保留旧密钥用于历史文件解密）。

文件完整性校验

使用 AES-GCM 模式（自带认证）。
使用 AES-CBC + HMAC（先加密，再对密文计算HMAC）。
存储文件的 SHA-256哈希（加密前的明文或加密后的密文均可，取决于需求）。

安全注意事项

风险点	应对措施
密钥泄露	使用HSM/KMS；限制密钥生命周期；轮换密钥
IV重复使用	每次加密生成随机IV（GCM 12字节，CBC 16字节）
填充预言攻击	使用GCM模式（无需填充）或CBC + HMAC
时序攻击	使用 `hash_equals()` 比较HMAC或认证标签
文件泄露到存储	加密后存储，解密后仅存在内存中（及时销毁）

完整示例：Web上传加密文件

<?php
// upload.php
if ($_SERVER['REQUEST_METHOD'] === 'POST' && isset($_FILES['file'])) {
    $uploadedFile = $_FILES['file']['tmp_name'];
    $safeName = bin2hex(random_bytes(16)) . '.enc'; // 避免信息泄露
    // 密钥从安全存储获取（示例仅用硬编码，生产勿用！）
    $key = hex2bin('ab12...32个十六进制字符...');
    // 加密
    if (encryptFile($uploadedFile, '/storage/' . $safeName, $key)) {
        echo "文件已安全存储";
        // 将$safeName存入数据库，关联用户
    } else {
        echo "加密失败";
    }
}

小文件：直接使用 openssl_encrypt 配合 AES-256-GCM。
大文件：使用流式加密（CTR/GCM）并分块处理。
最安全易用：libsodium 扩展的 crypto_secretbox 或 crypto_aead_aes256gcm。
业务公共云环境：利用 AWS KMS / Azure Key Vault 管理密钥，结合信封加密。

加密本身并不能保证安全,密钥管理和安全实践才是关键。