本教程详细阐述了如何解析v3洋葱域名，以提取其核心组成部分：公钥、校验和及版本号。文章首先介绍了v3洋葱域名的结构规范，随后提供了基于php的编程实现步骤，包括base32解码、字节截取和校验和验证。通过具体示例代码，读者将学习如何从`.onion`地址中安全有效地提取这些关键信息，并理解校验和在确保域名完整性中的重要作用。
V3洋葱域名结构概述
V3洋葱域名（.onion地址）是Tor网络中隐藏服务的一种标识符，其设计旨在提供更高的安全性和可扩展性。一个V3洋葱地址并非随机字符串，而是由隐藏服务的身份公钥、一个版本字段和一个基本校验和经过Base32编码后生成。理解其内部结构是进行程序化解析的基础。
根据Tor项目规范（rend-spec-v3.txt，第4.3.6节），V3洋葱地址的结构定义如下：
onion_address = base32(PUBKEY | CHECKSUM | VERSION) + ".onion"
其中各组成部分的含义及长度为：
立即学习“PHP免费学习笔记（深入）”；
- PUBKEY (公钥)：32字节的Ed25519主公钥，用于标识隐藏服务。
- CHECKSUM (校验和)：2字节的校验和，用于验证地址的完整性。它的计算方式为 H(".onion checksum" | PUBKEY | VERSION) 的前两个字节。这里的 H 是一个哈希函数（在Tor的实现中通常是SHA3-256）。
- VERSION (版本)：1字节的版本字段，当前V3地址的默认值为 \x03。
将这三个部分按顺序连接（PUBKEY | CHECKSUM | VERSION）形成一个35字节的二进制串，然后对该串进行Base32编码，最后加上.onion后缀，便构成了完整的V3洋葱地址。
解析V3洋葱域名的步骤
要从一个V3洋葱域名中提取公钥、校验和和版本号，主要需要经过以下几个步骤：
- 移除.onion后缀：首先从完整的洋葱地址中去除末尾的.onion字符串，得到Base32编码的核心部分。
- Base32解码：对剩余的Base32编码字符串进行解码，将其转换回原始的二进制数据。解码后的数据长度应为35字节。
-
字节截取：根据V3洋葱地址的结构定义，从解码后的35字节二进制数据中截取各个组成部分：
- 公钥 (PUBKEY)：前32个字节。
- 校验和 (CHECKSUM)：第33和第34个字节。
- 版本 (VERSION)：最后一个字节（即第35个字节）。
- 校验和验证（可选但推荐）：为了确保解析出的数据是有效的且地址未被篡改，强烈建议重新计算校验和并与提取出的校验和进行比对。
PHP实现示例
以下PHP代码演示了如何解析V3洋葱域名并提取其组成部分。本示例假设您已经有一个可用的Base32解码器。
= 8) {
$bits -= 8;
$buffer .= chr(($value >> $bits) & 0xFF);
}
}
return $buffer;
}
}
/**
* 解析V3洋葱域名，提取公钥、校验和和版本号。
*
* @param string $onionAddress 完整的V3洋葱域名，例如 "pg6mmjiyjmcrsslvykfwnntlaru7p5svn6y2ymmju6nubxndf4pscryd.onion"
* @return array|null 包含 'publicKey', 'checksum', 'version' 的关联数组，或在解析失败时返回 null。
*/
function parseV3OnionDomain(string $onionAddress): ?array
{
// 1. 移除 .onion 后缀
if (!str_ends_with($onionAddress, '.onion')) {
echo "错误: 无效的洋葱地址格式，缺少 '.onion' 后缀。\n";
return null;
}
$domainBase32 = str_replace(".onion", "", $onionAddress);
// 2. Base32 解码
$decodedBinary = Base32::decode($domainBase32);
// 检查解码后的长度，V3地址应为35字节
if (strlen($decodedBinary) !== 35) {
echo "错误: Base32解码后的数据长度不正确，期望35字节，实际为 " . strlen($decodedBinary) . " 字节。\n";
return null;
}
// 3. 字节截取
$publicKey = substr($decodedBinary, 0, 32); // 前32字节是公钥
$checksum = substr($decodedBinary, 32, 2); // 紧随公钥的2字节是校验和
$version = substr($decodedBinary, 34, 1); // 最后一个字节是版本号
// 将二进制数据转换为可读的十六进制字符串
$publicKeyHex = bin2hex($publicKey);
$checksumHex = bin2hex($checksum);
$versionHex = bin2hex($version);
return [
'publicKey' => $publicKeyHex,
'checksum' => $checksumHex,
'version' => $versionHex,
'versionDecimal' => hexdec($versionHex) // 版本号的十进制表示
];
}
// 示例用法
$onionUrl = "pg6mmjiyjmcrsslvykfwnntlaru7p5svn6y2ymmju6nubxndf4pscryd.onion";
$parsedData = parseV3OnionDomain($onionUrl);
if ($parsedData) {
echo "成功解析V3洋葱域名: {$onionUrl}\n";
echo "公钥 (HEX): " . $parsedData['publicKey'] . "\n";
echo "校验和 (HEX): " . $parsedData['checksum'] . "\n";
echo "版本 (HEX): " . $parsedData['version'] . "\n";
echo "版本 (DEC): " . $parsedData['versionDecimal'] . "\n";
// 验证版本号是否为3
if ($parsedData['versionDecimal'] === 3) {
echo "版本号验证成功：为V3地址。\n";
} else {
echo "警告：版本号不是预期的V3。\n";
}
// --- 校验和验证示例 (需要一个SHA3-256库) ---
// 注意：PHP内置的hash函数不支持SHA3-256，需要引入第三方库或PECL扩展
// 例如：composer require phpseclib/phpseclib
// use phpseclib3\Crypt\Hash;
// $hash = new Hash('sha3-256');
// $inputForChecksum = ".onion checksum" . hex2bin($parsedData['publicKey']) . hex2bin($parsedData['version']);
// $calculatedChecksum = substr($hash->hash($inputForChecksum), 0, 2); // 取前两个字节
// if ($calculatedChecksum === hex2bin($parsedData['checksum'])) {
// echo "校验和验证成功！\n";
// } else {
// echo "校验和验证失败！地址可能无效或被篡改。\n";
// }
}
?>注意事项
- Base32解码器：上述代码包含了一个简化的Base32类，用于演示目的。在生产环境中，强烈建议使用经过充分测试和优化的第三方Base32解码库，以确保正确性和安全性。
- 校验和算法：Tor V3地址的校验和计算使用了特定的哈希函数 H。在Tor的C语言实现中，这个哈希函数是SHA3-256。PHP标准库目前不直接支持SHA3-256，您可能需要使用PECL扩展（如hash扩展的hash_algos()列表里如果包含sha3-256）或第三方密码学库（例如 phpseclib）来实现校验和的重新计算和验证。校验和验证是确保洋葱地址完整性和有效性的关键步骤。
- 错误处理：在实际应用中，需要更健壮的错误处理机制，例如处理无效的Base32字符串、不正确的长度或格式等。
总结
通过上述解析过程和PHP示例，我们能够准确地从V3洋葱域名中提取出其核心组件：公钥、校验和以及版本号。这一能力对于构建Tor相关的工具、分析隐藏服务信息或验证洋葱地址的合法性至关重要。理解并正确实现这些解析步骤，是与Tor网络进行更深层次交互的基础。务必注意在生产环境中使用可靠的Base32解码库和正确的哈希算法进行校验和验证，以确保数据的准确性和安全性。
