68 lines
2.5 KiB
Markdown
68 lines
2.5 KiB
Markdown
|
# tor-client
|
|||
|
|
|||
|
High-level functionality for accessing the Tor network as a client.
|
|||
|
|
|||
|
## Overview
|
|||
|
|
|||
|
The `tor-client` crate aims to provide a safe, easy-to-use API for
|
|||
|
applications that want to use Tor network to anonymize their
|
|||
|
traffic. It hides most of the underlying detail, letting other
|
|||
|
crates decide how exactly to use the Tor crate.
|
|||
|
|
|||
|
This crate is part of
|
|||
|
[Arti](https://gitlab.torproject.org/tpo/core/arti/), a project to
|
|||
|
implement [Tor](https://www.torproject.org/) in Rust.
|
|||
|
It is the highest-level library crate in
|
|||
|
Arti, and the one that nearly all client-only programs should use.
|
|||
|
Most of its functionality is provided by lower-level crates in Arti.
|
|||
|
|
|||
|
### ⚠️Warnings ⚠
|
|||
|
️
|
|||
|
**Do not expect ANY privacy from this code yet.**
|
|||
|
|
|||
|
Arti is a work in progress, and there are currently certain
|
|||
|
missing features that _will_ make it far less private than the
|
|||
|
standard Tor implementation. In fact, the absence of these makes
|
|||
|
Arti clients vulnerable to certain classes of well known attacks
|
|||
|
that the standard Tor implementation defends against.
|
|||
|
|
|||
|
At present, do not expect Arti to give you _any privacy at all_. (We'll
|
|||
|
remove or soften this warning once we're more confident in our privacy.)
|
|||
|
|
|||
|
**Do not use this code in production yet.**
|
|||
|
|
|||
|
All of the APIs for this crate, and for Arti in general, are not
|
|||
|
the least bit stable. If you use this code, please expect your
|
|||
|
software to break on a regular basis.
|
|||
|
|
|||
|
### Design considerations, privacy considerations.
|
|||
|
|
|||
|
As we build the APIs for this crate, we've been aiming for
|
|||
|
simplicity and safety: we want it to be as easy as possible to use
|
|||
|
`tor-client`, while trying to make certain kinds of privacy or security
|
|||
|
violation hard to write accidentally.
|
|||
|
|
|||
|
Privacy isn't just a drop-in feature, however. There are still
|
|||
|
plenty of ways to accidentally leak information, even if you're
|
|||
|
anonymizing your connections over Tor. We'll try to document
|
|||
|
those in a user's guide at some point as Arti becomes more mature.
|
|||
|
|
|||
|
## Using `tor-client`
|
|||
|
|
|||
|
The `tor-client` crate provides an async Rust API. It is
|
|||
|
compatible with the `tokio` and `async_std` asyncronous backends.
|
|||
|
|
|||
|
TODO: Good examples here once the crate setup API is more simple.
|
|||
|
|
|||
|
## Feature flags
|
|||
|
|
|||
|
`tokio` -- (Default) Build with support for the Tokio backend.
|
|||
|
|
|||
|
`async-std` -- Build with support for the `async_std` backend.
|
|||
|
|
|||
|
`experimental-api` -- Build with experimental, unstable API support.
|
|||
|
Note that these APIs are NOT covered by semantic versioning guarantees:
|
|||
|
we might break them or remove them between patch versions.
|
|||
|
|
|||
|
License: MIT OR Apache-2.0
|