2022-09-23 14:47:30 +01:00
|
|
|
# tor-ptmgr
|
|
|
|
|
2022-12-20 13:31:47 +00:00
|
|
|
Manage a set of anti-censorship pluggable transports.
|
2022-09-23 14:47:30 +01:00
|
|
|
|
|
|
|
## Overview
|
|
|
|
|
|
|
|
This crate is part of [Arti](https://gitlab.torproject.org/tpo/core/arti/),
|
|
|
|
a project to implement [Tor](https://www.torproject.org/) in Rust.
|
|
|
|
|
|
|
|
In Tor, a "transport" is a mechanism used to avoid censorship by disguising
|
|
|
|
the Tor protocol as some other kind of traffic.
|
|
|
|
|
|
|
|
A "pluggable transport" is one that is not implemented by default as part of
|
|
|
|
the Tor protocol, but which can instead be added later on by the packager or
|
|
|
|
the user. Pluggable transports are typically provided as external binaries
|
|
|
|
that implement a SOCKS proxy, along with certain other configuration
|
|
|
|
protocols.
|
|
|
|
|
|
|
|
This crate provides a means to manage a set of configured pluggable
|
|
|
|
transports
|
|
|
|
|
|
|
|
## Limitations
|
|
|
|
|
2022-11-28 18:34:48 +00:00
|
|
|
TODO: Currently, the APIs for this crate make it quite
|
2022-09-23 14:47:30 +01:00
|
|
|
tor-specific. Notably, it can only return Channels! It would be good
|
|
|
|
instead to adapt it so that it was more generally useful by other projects
|
|
|
|
that want to use pluggable transports in rust. For now, I have put the
|
|
|
|
Tor-channel-specific stuff behind a `tor-channel-factory` feature, but there
|
|
|
|
are no APIs for using PTs without that feature currently. That should
|
2022-11-28 18:34:48 +00:00
|
|
|
change. (See issue [arti#666](https://gitlab.torproject.org/tpo/core/arti/-/issues/666))
|
2022-09-23 14:47:30 +01:00
|
|
|
|
2022-11-28 18:34:48 +00:00
|
|
|
TODO: The first version of this crate will probably only conform
|
|
|
|
to the original Tor pluggable transport protocol, and not to more recent variants
|
2022-09-23 14:47:30 +01:00
|
|
|
as documented at `pluggabletransports.info`
|
|
|
|
|
2022-11-28 18:16:58 +00:00
|
|
|
## Feature flags
|
|
|
|
|
2022-11-28 18:34:48 +00:00
|
|
|
### Additive features
|
|
|
|
|
|
|
|
* `tor-channel-factory`: Build with support for a ChannelFactory implementation
|
|
|
|
that allows this crate's use with Tor. (Currently, this is the only way to
|
|
|
|
use the crate; see "Limitations" section above.)
|
|
|
|
|
|
|
|
* `full` -- Build with all the features above.
|
|
|
|
|
2022-11-28 18:16:58 +00:00
|
|
|
### Experimental and unstable features
|
|
|
|
|
|
|
|
Note that the APIs enabled by these features are NOT covered by semantic
|
|
|
|
versioning guarantees: we might break them or remove them between patch
|
|
|
|
versions.
|
|
|
|
|
|
|
|
* `experimental-api` -- build with experimental, unstable API support.
|
|
|
|
|
|
|
|
* `experimental` -- Build with all experimental features above, along with
|
|
|
|
all experimental features from other arti crates.
|
|
|
|
|
|
|
|
|
2022-09-23 14:47:30 +01:00
|
|
|
License: MIT OR Apache-2.0
|