arti-client

作为客户端访问Tor网络的高级功能。

概述

arti-client crate旨在为想要使用Tor网络匿名化其流量的应用程序提供安全、易于使用的API。

该crate是Arti项目的一部分，该项目旨在使用Rust实现Tor。它是Arti中最高级的库crate，几乎所有仅客户端的程序都应该使用它。其大部分功能由Arti中的底层crate提供。

API的结构和与其他crate的关系

如果您正在使用异步Rust构建应用程序并希望将Tor连接作为异步流（AsyncRead/AsyncWrite），这里的API非常棒。

如果您正在尝试将Arti连接到其他编程语言，目前最好的办法可能是作为子进程启动arti CLI SOCKS代理。我们尚未提供通过FFI公开的API；我们打算在未来添加此功能。

⚠ 警告 ⚠

请注意，该crate的API并非全部都已完全稳定。我们将在没有充分理由的情况下尽量避免破坏东西，并在破坏时遵循语义版本化，但请预期在我们宣布arti-client 1.x之前，可能会发生一些破坏。

Arti中底层crate公开的API更加不稳定；它们会比arti-client更频繁地破坏，原因更少。

使用arti-client

本crate的主要入口点是TorClient，这是一个对象，允许您通过Tor网络进行连接。

连接到Tor

调用TorClient::create_bootstrapped将建立与Tor网络的连接，并获取所需的网络共识状态。此状态将持久化到TorClientConfig中指定的位置。

(此方法要求您在async fn中初始化客户端。如果这不适合您，请考虑使用下面的构建器方法。)

// The client configuration describes how to connect to the Tor network,
// and what directories to use for storing persistent state.
let config = TorClientConfig::default();

// Start the Arti client, and let it bootstrap a connection to the Tor network.
// (This takes a while to gather the necessary directory information.
// It uses cached information when possible.)
let tor_client = TorClient::create_bootstrapped(config).await?;

创建客户端并在稍后连接

您可能希望立即创建Tor客户端，而不等待它启动（或不需要使用await）。这可以通过使用TorClientBuilder和TorClient::builder来完成，并调用TorClientBuilder::create_unbootstrapped。

返回的客户端在首次使用时可以启动（默认行为），也可以不启动；有关更多详细信息，请参阅BootstrapBehavior。

// Specifying `BootstrapBehavior::OnDemand` means the client will automatically
// bootstrap when it is used. `Manual` exists if you'd rather have full control.
let tor_client = TorClient::builder()
    .bootstrap_behavior(BootstrapBehavior::OnDemand)
    .create_unbootstrapped()?;

使用客户端

然后可以使用TorClient::connect通过Tor进行连接，该方法接受任何实现IntoTorAddr的对象。这返回一个DataStream，这是一个实现了AsyncRead和AsyncWrite的匿名化TCP流类型，如果启用了tokio crate功能，还包括那些特质的Tokio版本。

示例：通过Tor进行连接

#
// Initiate a connection over Tor to example.com, port 80.
let mut stream = tor_client.connect(("example.com", 80)).await?;

use futures::io::{AsyncReadExt, AsyncWriteExt};

// Write out an HTTP request.
stream
    .write_all(b"GET / HTTP/1.1\r\nHost: example.com\r\nConnection: close\r\n\r\n")
    .await?;

// IMPORTANT: Make sure the request was written.
// Arti buffers data, so flushing the buffer is usually required.
stream.flush().await?;

// Read and print the result.
let mut buf = Vec::new();
stream.read_to_end(&mut buf).await?;

println!("{}", String::from_utf8_lossy(&buf));
#

桥接使用

桥和可插入传输（PT）可以用作绕过审查的工具，在Tor被阻止的地方连接到Tor。在arti中，它们通过config::BridgesConfig进行配置。您需要启用pt-client功能以支持PT。请注意，可插入传输需要单独安装，Arti本身不提供它们。您可以在TB手册中了解更多有关PT的信息。

更高级的使用

Arti的这个版本包括对“流隔离”的基本支持：确保不同的TCP连接（“流”）通过不同的Tor电路（从而通过不同的出口节点，使其来自不同的IP地址）。

这有助于避免通过关联性解匿匿名用户：例如，您可能希望为银行和在线论坛分别使用不同的Tor连接，以避免两个身份因具有相同的源IP而相互关联。

流可以以两种方式隔离

• 通过调用TorClient::isolated_client，这会返回一个新的TorClient，其流将使用不同的电路
• 通过生成IsolationToken，并将它们通过StreamPrefs传递给TorClient::connect。

多运行时支持

Arti使用tor_rtcompat crate来支持多个异步运行时；目前，既支持Tokio也支持async-std。

Arti用于TCP连接的后端（tor_rtcompat::TcpProvider）和创建TLS会话（tor_rtcompat::TlsProvider）也可以通过此crate进行配置。这可以用于将Arti嵌入到需要大量控制其网络使用情况的定制环境中。

查看tor_rtcompat crate文档以了解更多关于这些功能的信息。

报告Arti错误

Arti经常输出非常长的调试消息，即使是对于开发者来说也很难理解。为了更好地了解您程序中出了什么问题，为每个Error编写match，并将err.report()记录下来，其中err是捕获到的错误。

// Initiate a connection over Tor to example.com, port 80.
// Note: here we try to handle the potential error using match
match tor_client.connect(("example.com", 80)).await {
    Ok(mut stream) => {
        eprintln!("sending request...");

        stream
            .write_all(b"GET / HTTP/1.1\r\nHost: example.com\r\nConnection: close\r\n\r\n")
            .await?;

        // IMPORTANT: Make sure the request was written.
        // Arti buffers data, so flushing the buffer is usually required.
        stream.flush().await?;

        eprintln!("reading response...");

        // Read and print the result.
        let mut buf = Vec::new();
        stream.read_to_end(&mut buf).await?;

        println!("{}", String::from_utf8_lossy(&buf));
    }
    Err(err) => {
        // Use .report() on an error to get a nicer error message
        // Raw Debug output will be much harder to decipher for all parties involved
        eprintln!("{}", err.report());
    }
}