Merge branch '010_docs'
This commit is contained in:
commit
132416275d
17
README.md
17
README.md
|
@ -56,16 +56,16 @@ We're not _aware_ of any critical security features missing in Arti; but
|
|||
however, since Arti is comparatively new software, you should probably be
|
||||
cautious about using it in production.
|
||||
|
||||
There are no guarantees about API stability yet: if you write code
|
||||
that uses Arti, you should expect it to break with future versions. If you
|
||||
write an a configuration file for Arti, it might stop working in the future.
|
||||
Now that Arti has reached version 0.1.0, we believe it is suitable for
|
||||
_experimental_ embedding within other Rust applications. We will try to keep
|
||||
the API as exposed by the top-level `arti_client` crate more or less stable
|
||||
over time. (We may have to break existing programs from time to time, but we
|
||||
will try not to do so without a very good reason. Either way, we will try to
|
||||
follow Rust's semantic versioning best practices.)
|
||||
|
||||
## Trying it out today
|
||||
|
||||
Arti can act as a SOCKS proxy that uses the Tor network.
|
||||
It knows how to download directory
|
||||
information and how to load it from cache, but it doesn't try to
|
||||
download more than one directory per run.
|
||||
|
||||
To try it out, run the demo program in `arti` as follows. It will open a
|
||||
SOCKS proxy on port 9150.
|
||||
|
@ -121,17 +121,18 @@ get our project manager to sign off on them.
|
|||
* [x] Performance: preemptive circuit construction
|
||||
* [x] Performance: circuit build timeout inference
|
||||
* [x] API support for embedding
|
||||
* [ ] API support for status reporting
|
||||
* [x] API support for status reporting
|
||||
* [x] Correct timeout behavior
|
||||
* [and more...](https://gitlab.torproject.org/tpo/core/arti/-/milestones/7)
|
||||
|
||||
* Arti 1.0.0: Initial stable release (Goal: Mid September, 2022??)
|
||||
* Target audience: **initial users**
|
||||
* [ ] Security audit
|
||||
* [ ] Stable API
|
||||
* [ ] Stable CLI
|
||||
* [ ] Stable configuration format
|
||||
* [ ] Automatic detection and response of more kinds of network problems
|
||||
* [ ] At least as secure as C Tor
|
||||
* [ ] Client performance similar to C Tor
|
||||
* [ ] More performance work
|
||||
* [and more...](https://gitlab.torproject.org/tpo/core/arti/-/milestones/8)
|
||||
|
||||
|
|
|
@ -282,8 +282,14 @@ impl From<SystemConfig> for SystemConfigBuilder {
|
|||
/// Finally, you can get fine-grained control over the members of a a
|
||||
/// TorClientConfig using [`TorClientConfigBuilder`].
|
||||
///
|
||||
/// NOTE: These are NOT the final options or their final layout.
|
||||
/// Expect NO stability here.
|
||||
/// # ⚠ Stability Warning ⚠
|
||||
///
|
||||
/// The design of this structure, and of the configuration system for
|
||||
/// Arti, is likely to change significantly before the release of Arti
|
||||
/// 1.0.0. The layout of options within this structure is also likely
|
||||
/// to change. For more information see ticket [#285].
|
||||
///
|
||||
/// [#285]: https://gitlab.torproject.org/tpo/core/arti/-/issues/285
|
||||
#[derive(Clone, Debug, Eq, PartialEq)]
|
||||
pub struct TorClientConfig {
|
||||
/// Information about the Tor network we want to connect to.
|
||||
|
|
|
@ -15,11 +15,18 @@
|
|||
//!
|
||||
//! Note that Arti is a work in progress; although we've tried to write all the
|
||||
//! critical security components, you probably shouldn't use Arti in production
|
||||
//! until it's a bit more mature.
|
||||
//! until it's a bit more mature. (That said, now is a _great_ time to try
|
||||
//! our Arti on an experimental basis, so you can tell us what we need
|
||||
//! to fix between now and the 1.0.0 release.)
|
||||
//!
|
||||
//! Also note that 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.
|
||||
//! Also note that the APIs for this crate are not all yet
|
||||
//! completely stable. We'll try not to break things without good
|
||||
//! reason, and we'll follow semantic versioning when we do, but
|
||||
//! please expect a certain amount of breakage between now and 1.0.0.
|
||||
//!
|
||||
//! The APIs exposed by lower-level crates in Arti are _even more
|
||||
//! unstable_; they will break more often than those from
|
||||
//! `arti-client`, for less reason.
|
||||
//!
|
||||
//! # Using `arti-client`
|
||||
//!
|
||||
|
|
|
@ -8,6 +8,14 @@
|
|||
//!
|
||||
//! It provides a client configuration tool using using `serde` and `config`,
|
||||
//! plus extra features defined here for convenience.
|
||||
//!
|
||||
//! # ⚠ Stability Warning ⚠
|
||||
//!
|
||||
//! The design of this crate, and of the configuration system for
|
||||
//! Arti, is likely to change significantly before the release of Arti
|
||||
//! 1.0.0. For more information see ticket [#285].
|
||||
//!
|
||||
//! [#285]: https://gitlab.torproject.org/tpo/core/arti/-/issues/285
|
||||
|
||||
#![deny(missing_docs)]
|
||||
#![warn(noop_method_call)]
|
||||
|
|
|
@ -7,6 +7,14 @@
|
|||
//! implement [Tor](https://www.torproject.org/) in Rust.
|
||||
//!
|
||||
//! It provides low-level types for handling configuration values.
|
||||
//!
|
||||
//! # ⚠ Stability Warning ⚠
|
||||
//!
|
||||
//! The design of this crate, and of the configuration system for
|
||||
//! Arti, is likely to change significantly before the release of Arti
|
||||
//! 1.0.0. For more information see ticket [#285].
|
||||
//!
|
||||
//! [#285]: https://gitlab.torproject.org/tpo/core/arti/-/issues/285
|
||||
|
||||
#![deny(missing_docs)]
|
||||
#![warn(noop_method_call)]
|
||||
|
|
|
@ -33,6 +33,9 @@ various ways. Other crates should use this crate, and not actually
|
|||
use any crypto implementation crates directly. (It's okay to use crates that
|
||||
define cryptographic traits.)
|
||||
|
||||
`tor-error`: Declare a general `ErrorKind` implementation used to hide the
|
||||
details for the errors in higher-level Arti crates.
|
||||
|
||||
`tor-persist`: Types and traits for handling persistent data in Arti.
|
||||
|
||||
`tor-rtcompat`: Traits to expose a common interface for asynchronous runtime
|
||||
|
@ -96,8 +99,17 @@ network view as an instance of `tor-netdir::NetDir`.
|
|||
`arti-client`: A client library that can be used to connect to the Tor network
|
||||
and make connections.
|
||||
|
||||
`arti-config`: Support for working with Arti's configuration file format.
|
||||
This is likely to move to a lower level and get refactored significantly
|
||||
before Arti 1.0.0.
|
||||
|
||||
`arti`: A simple command-line client program that can run as a SOCKS proxy.
|
||||
|
||||
`arti-bench`: A testing crate for running performance tests.
|
||||
|
||||
`arti-hyper`: An example crate, using `arti_client` as a backend for the
|
||||
`hyper` HTTP library.
|
||||
|
||||
## Design considerations, privacy considerations.
|
||||
|
||||
As we build the APIs for Arti, we've been aiming for
|
||||
|
|
35
doc/FAQ.md
35
doc/FAQ.md
|
@ -10,12 +10,37 @@ Arti is also the name of the software produced by this project.
|
|||
|
||||
## What is the status of Arti today?
|
||||
|
||||
As of mid-June 2021: Arti ready for developers to play around with, but it is
|
||||
not yet ready for general use. Arti can run as a simple Tor client and
|
||||
send anonymized traffic over the network; it has no support for running as a
|
||||
relay or for using onion services.
|
||||
As of March 2022: Arti is ready for experimental use by developers
|
||||
interesting in embedding Tor support in their projects. Arti can run as
|
||||
a simple Tor client and send anonymized traffic over the network, but it
|
||||
has no support for running as a relay or for using onion services.
|
||||
|
||||
Before Arti is ready for production use, we need to make sure that it
|
||||
has all the important security features from the C Tor implementation; we
|
||||
need to improve its performance; and we need to improve its APIs based
|
||||
on user requirements. We hope to have this done for our
|
||||
[our 1.0.0 milestone](https://gitlab.torproject.org/tpo/core/arti/-/milestones/8#tab-issues) in September 2022.
|
||||
|
||||
(After that, our 1.1 milestone will focus on anticensorship work,
|
||||
and 1.2 will focus on support for onion services.)
|
||||
|
||||
## Should I use Arti?
|
||||
|
||||
As of mid-October 2021: only if you are interested in helping us find bugs!
|
||||
As of March 2022: You should only use Arti as a client if you are
|
||||
interesting in helping us experiment and find bugs.
|
||||
|
||||
If you are interested in shipping Arti as part of your own application,
|
||||
you should start experimenting with it _now_, so that you can let us
|
||||
know what features and APIs are missing for you, and we have a chance to
|
||||
add them.
|
||||
|
||||
## Will Arti replace the C Tor implementation?
|
||||
|
||||
Eventually, yes. But it will take a _lot_ of work.
|
||||
|
||||
We plan to maintain and support the C Tor implementation until Arti is a
|
||||
viable replacement for the vast majority of use cases. We estimate that
|
||||
this will take us several more years, at the least. Even then, we plan
|
||||
to continue supporting the C Tor implementation for some while, to give
|
||||
people time to switch.
|
||||
|
||||
|
|
Loading…
Reference in New Issue