PharUtil 技术文档

PharUtil 是一套面向 Phar 归档文件的安全工具集。本文档将详细介绍如何安装和使用 PharUtil，以及如何通过其 API 进行操作。

1. 安装指南

依赖性

• PHP 版本需大于等于 5.2.0
• PHP 中编译进 OpenSSL (--with-openssl)，Windows 用户请查阅 PHP 手册
• Phar 版本需大于等于 2.0.0

如果使用 PHP 5.3.0 或更高版本，Phar 会自动包含。对于旧版本，必须从 pecl 中构建。

例如，在 Ubuntu 下，以下步骤用于构建和启用 Phar 扩展：

sudo apt-get install php5-dev
sudo pecl install pecl/phar
echo "extension=phar.so" | sudo tee /etc/php5/conf.d/phar.ini

配置 Phar

为了构建 Phar 归档，需要更改 php.ini 设置：phar.readonly=0。在 Ubuntu 下，执行以下命令：

echo "phar.readonly=0" | sudo tee -a /etc/php5/conf.d/phar.ini

如果只读取 Phar 归档，此步骤是可选的（不推荐）。

安装包

通过 PEAR 安装器安装库：

sudo pear channel-discover pear.kotowicz.net
sudo pear install kotowicz/PharUtil-beta

2. 项目的使用说明

PharUtil 提供了以下命令行工具：

• phar-build：用于构建和签名 Phar 归档
• phar-extract：用于提取/列出 Phar 归档内容
• phar-verify：用于验证 Phar 归档签名
• phar-generate-cert：用于生成用于签名 Phar 归档的 OpenSSL 证书
• phar-file-checksums：用于生成/检查文件校验和，以查看 Phar 归档是否与源文件同步

所有脚本都支持 -h 参数，用于显示使用方法。

构建 Phar 归档

1. 在 cert/ 目录下生成证书（将放在 priv.pem 和 pub.pem）

   mkdir cert/
   cd cert/
   phar-generate-cert
   

2. 创建 src/ 目录，并复制所有要构建归档的文件
3. 构建签名后的 Phar 归档

   phar-build --phar library.phar
   

提取 Phar 归档

phar-extract library.phar output-directory

验证 Phar 归档签名

phar-verify -P pub.pem http://example.com/library.phar

列出 Phar 归档内容

phar-extract -l library.phar output-directory

使用 Phar 归档

像使用普通 Phar 归档一样使用：

include_once 'phar://path/to/library.phar';

3. 项目 API 使用文档

PharUtil 提供了以下类和方法用于安全远程代码部署：

• PharUtil_RemotePharVerifier：用于安全检查 Phar 签名

以下是一个使用 PharUtil_RemotePharVerifier 的示例：

// 所有验证过的 Phar 将被复制到 lib/ 目录
$verifier = new PharUtil_RemotePharVerifier('/tmp', './lib', './cert/public.pem');
try {
    $verified_file = $verifier->fetch("http://example.com/library.phar");
} catch (Exception $e) {
    // 验证失败
    exit();
}

// $verified_file 包含已下载文件的绝对路径，并使用 './cert/public.pem' 验证签名
include_once $verified_file;
// 或者
include_once 'phar://' . $verified_file . '/some/file/within.php';
// 或者
echo file_get_contents('phar://' . $verified_file . '/readme.txt');

4. 项目安装方式

如上所述，项目可以通过 PEAR 安装器安装：

sudo pear channel-discover pear.kotowicz.net
sudo pear install kotowicz/PharUtil-beta