如何解析Tor V3 Onion域名提取公钥校验和与版本信息

Tor V3 Onion域名采用特定的编码规则存储服务公钥、校验和以及版本信息，在PHP环境下解析这类域名需要遵循其官方定义的格式规范，逐步完成编码转换和字段拆分操作。

Tor V3 Onion域名结构说明

Tor V3 Onion域名的标准格式为56位base32编码字符串加上.onion后缀，去掉后缀后的56位字符串包含三个核心部分：

• 前52位是服务的Ed25519公钥编码结果
• 第53到54位是校验和，用于验证公钥的完整性
• 最后2位是版本号，固定为03表示V3版本

解析核心步骤

1. 预处理域名

首先需要将输入的域名统一转为小写，去掉.onion后缀，同时验证长度是否符合56位的要求。

<?php
function preprocessOnionDomain($domain) {
    // 转为小写并去除前后空格
    $domain = strtolower(trim($domain));
    // 验证是否以.onion结尾
    if (substr($domain, -6) !== '.onion') {
        throw new InvalidArgumentException('不是有效的Onion域名');
    }
    // 提取编码部分
    $encoded = substr($domain, 0, -6);
    // 验证编码长度是否为56位
    if (strlen($encoded) !== 56) {
        throw new InvalidArgumentException('Tor V3 Onion编码部分长度应为56位');
    }
    return $encoded;
}
?>

2. Base32解码

Tor V3使用标准的base32编码，解码后可以得到35字节的原始数据，对应公钥、校验和、版本三个字段的总长度。

<?php
function base32Decode($input) {
    $base32Chars = 'abcdefghijklmnopqrstuvwxyz234567';
    $input = strtolower($input);
    $output = '';
    $buffer = 0;
    $bufferBits = 0;
    for ($i = 0; $i < strlen($input); $i++) {
        $char = $input[$i];
        $charIndex = strpos($base32Chars, $char);
        if ($charIndex === false) {
            throw new InvalidArgumentException('包含无效的base32字符');
        }
        $buffer = ($buffer << 5) | $charIndex;
        $bufferBits += 5;
        if ($bufferBits >= 8) {
            $bufferBits -= 8;
            $output .= chr(($buffer >> $bufferBits) & 0xFF);
            $buffer &= (1 << $bufferBits) - 1;
        }
    }
    return $output;
}
?>

3. 拆分字段与校验

解码后的35字节数据中，前32字节是公钥，接下来2字节是校验和，最后1字节是版本号。校验和的计算规则是将公钥和固定字符串"3"拼接后进行SHA3-256哈希，取前两个字节作为预期校验和。

<?php
function parseTorV3Onion($domain) {
    $encoded = preprocessOnionDomain($domain);
    // base32解码得到35字节原始数据
    $raw = base32Decode($encoded);
    if (strlen($raw) !== 35) {
        throw new InvalidArgumentException('解码后数据长度不符合预期');
    }
    // 拆分字段
    $publicKey = substr($raw, 0, 32);
    $checksum = substr($raw, 32, 2);
    $version = ord(substr($raw, 34, 1));
    // 计算预期校验和
    $hashInput = $publicKey . '3';
    $hash = hash('sha3-256', $hashInput, true);
    $expectedChecksum = substr($hash, 0, 2);
    // 验证校验和
    if ($checksum !== $expectedChecksum) {
        throw new RuntimeException('校验和验证失败，域名可能损坏');
    }
    // 验证版本号
    if ($version !== 3) {
        throw new RuntimeException('不是Tor V3版本Onion域名');
    }
    return [
        'public_key' => bin2hex($publicKey),
        'checksum' => bin2hex($checksum),
        'version' => $version
    ];
}
?>

使用示例

调用上述解析函数即可得到对应的字段信息：

<?php
try {
    $domain = 'examplev3address12345678901234567890123456789012.onion';
    $result = parseTorV3Onion($domain);
    echo "公钥: " . $result['public_key'] . PHP_EOL;
    echo "校验和: " . $result['checksum'] . PHP_EOL;
    echo "版本号: " . $result['version'] . PHP_EOL;
} catch (Exception $e) {
    echo "解析失败: " . $e->getMessage() . PHP_EOL;
}
?>

注意事项

PHP环境需要开启sha3扩展才能使用hash函数的sha3-256算法，如果没有该扩展可以通过pecl安装或者自行实现SHA3-256逻辑。另外解析前一定要做好域名格式校验，避免无效输入导致解析异常。

Tor_V3_OnionPHP公钥提取校验和计算版本解析修改时间：2026-06-04 06:30:06