PGP 文件 Web 自动解密完整实践指南-php教程-PHP中文网

PGP 文件 Web 自动解密完整实践指南

本文详解如何在 Linux 服务器上通过 PHP Web 接口安全、可靠地调用 GPG 解密 PGP 加密文件，涵盖密钥环迁移、权限配置、--pinentry-mode loopback 关键参数使用及进程级错误捕获方案。

本文详解如何在 linux 服务器上通过 php web 接口安全、可靠地调用 gpg 解密 pgp 加密文件，涵盖密钥环迁移、权限配置、`--pinentry-mode loopback` 关键参数使用及进程级错误捕获方案。

在构建面向 GDPR 敏感数据的自动化处理流程时，让非技术用户（如业务直报人员）通过 Web 界面上传并解密 PGP 加密文件，是一项常见但极具挑战性的任务。核心难点不在于 GPG 命令本身，而在于Web 服务用户（如 www-data）与 GPG 密钥环境、密码输入机制及权限模型之间的深度适配。直接复用终端成功命令（如 gpg --decrypt）在 Web 环境中几乎必然失败——原因包括：密钥不可见、gpg-agent 缺失交互支持、默认 pinentry 模式阻塞、以及 system() 调用无法捕获详细错误。

✅ 正确路径：隔离密钥环境 + 显式进程控制 + 安全参数

1. 迁移并授权密钥环（Keyring）

GPG 默认从 ~/.gnupg/ 读取私钥。Web 进程以 www-data 用户运行，其主目录无有效密钥环。必须显式复制并授权：

# 以拥有私钥的用户（如 pi）执行：
cp -a ~/.gnupg/ /var/www/.gnupg/
sudo chown -R www-data:www-data /var/www/.gnupg/
sudo find /var/www/.gnupg -type f -exec chmod 600 {} \;
sudo find /var/www/.gnupg -type d -exec chmod 700 {} \;

⚠️ 注意：切勿将私钥保留在 Web 可访问目录（如 /var/www/html/），/var/www/.gnupg/ 是安全的系统级路径，仅对 www-data 可读写。

2. 强制启用 `loopback` pinentry 模式（关键！）

GPG 8.0+ 默认禁用 --passphrase-fd 的密码输入，除非显式启用 --pinentry-mode loopback 并配置 gpg-agent。此模式允许脚本化密码传递，是 Web 自动化的基石：

# 编辑 /var/www/.gnupg/gpg-agent.conf（确保存在）
echo "allow-loopback-pinentry" | sudo tee -a /var/www/.gnupg/gpg-agent.conf
echo "pinentry-program /usr/bin/pinentry-loopback" | sudo tee -a /var/www/.gnupg/gpg-agent.conf

# 重启 agent（或重启 gpg-agent 进程）
sudo -u www-data gpg-connect-agent reloadagent /bye

✅ 验证：sudo -u www-data gpg --list-secret-keys 应正常输出密钥信息。

3. 使用 `proc_open()` 替代 `system()`（推荐）

system() 无法捕获标准错误（stderr），导致“零长度文件”等静默失败。proc_open() 提供完整 I/O 控制，便于调试：

<?php putenv('GNUPGHOME=/var/www/.gnupg'); // 指向专用密钥环
$passphrase = 'your_secure_passphrase';
$pgpDir = '/var/www/pgp/';
$encryptedFile = $pgpDir . 'encrypted_20220624.csv';
$decryptedFile = $pgpDir . 'decrypted_' . basename($encryptedFile);

$descriptorspec = [
    0 => ['pipe', 'r'], // stdin
    1 => ['pipe', 'w'], // stdout
    2 => ['pipe', 'w'], // stderr
];

// 构建命令（注意：--pinentry-mode loopback 是必需的）
$command = "echo '" . escapeshellarg($passphrase) . "' | " .
           "gpg --batch --quiet --yes --pinentry-mode loopback " .
           "--passphrase-fd 0 --decrypt " . escapeshellarg($encryptedFile) . 
           " > " . escapeshellarg($decryptedFile);

$process = proc_open($command, $descriptorspec, $pipes);

if (!is_resource($process)) {
    throw new RuntimeException("Failed to start GPG process");
}

// 写入密码（虽然 echo 已处理，但此处可作备用）
if (isset($pipes[0])) {
    fwrite($pipes[0], $passphrase . "\n");
    fclose($pipes[0]);
}

// 读取输出与错误
$output = stream_get_contents($pipes[1]);
$stderr = stream_get_contents($pipes[2]);
fclose($pipes[1]);
fclose($pipes[2]);

$exitCode = proc_close($process);

if ($exitCode !== 0) {
    error_log("GPG decryption failed (code $exitCode): $stderr");
    throw new RuntimeException("Decryption failed: " . trim($stderr));
}

// 验证解密结果
if (!file_exists($decryptedFile) || filesize($decryptedFile) === 0) {
    throw new RuntimeException("Decrypted file is empty or missing");
}

echo "Success! Decrypted to: " . basename($decryptedFile);
?>

? 安全增强建议

密码管理：避免硬编码密码。改用环境变量（getenv('PGP_PASSPHRASE')）或加密配置文件。
文件清理：解密后立即删除临时加密文件（unlink($encryptedFile)），防止堆积。
上传校验：在 UploadValidationProd::DoValidation() 中，move_uploaded_file() 应指定绝对安全路径（如 /var/www/pgp/uploads/），而非当前目录。
权限最小化：/var/www/pgp/ 目录应仅对 www-data 可写，禁止 Web 访问（通过 Nginx/Apache 配置 location ~ ^/pgp/ { deny all; }）。

✅ 最终验证要点

检查项	命令/方法	预期结果
密钥可见性	`sudo -u www-data gpg --list-secret-keys`	显示你的私钥
Pinentry 模式	`sudo -u www-data gpg --pinentry-mode loopback --decrypt test.gpg 2>&1`	不卡住，输出解密内容或明确错误
文件权限	`ls -la /var/www/.gnupg/`	所有文件 `600`，目录 `700`，属主 `www-data`