Expand description
Β§tor-hsservice
Provide an onion service on the Tor network.
Β§Overview
This crate is part of Arti, a project to implement Tor in Rust.
It provides a service-side implementation of the onion service protocol, which enables Tor clients to provide a responder-anonymous service on the network. Other parties can connect to an onion service without learning where it is hosted.
This crate provides a low-level implementation of the onion service protocol
that may not be suitable for typical users.
Most users will instead want to use the arti binary
to run an onion service proxy, or use the TorClient::launch_onion_service API
in the arti-client crate.
Β§Reference
You can learn more about the protocols here as part of the onion services Specification.
LICENSE: MIT OR Apache-2.0
When the hs-pow-full feature is used, we link with LGPL licensed dependencies.
Re-exportsΒ§
pub use anon_level::Anonymity;pub use config::OnionServiceConfig;pub use err::ClientError;pub use err::EstablishSessionError;pub use err::FatalError;pub use err::IntroRequestError;pub use err::StartupError;pub use ipt_mgr::IptError;pub(crate) use keys::HsTimePeriodKeySpecifier;πpub use keys::BlindIdKeypairSpecifier;pub use keys::BlindIdPublicKeySpecifier;pub use keys::DescSigningKeypairSpecifier;pub use keys::HsIdKeypairSpecifier;pub use keys::HsIdPublicKeySpecifier;pub(crate) use pow::NewPowManager;πpub(crate) use pow::PowManager;πpub use publish::UploadError as DescUploadError;pub use req::RendRequest;pub use req::StreamRequest;pub use helpers::handle_rend_requests;pub(crate) use oneshot_fused_workaround as oneshot;πpub(crate) use crate::OnionServiceConfig;πpub(crate) use crate::StartupError;πpub(crate) use crate::StreamRequest;πpub(crate) use crate::err::IptStoreError;πpub(crate) use crate::err::StateExpiryError;πpub(crate) use crate::ipt_lid::InvalidIptLocalId;πpub(crate) use crate::ipt_lid::IptLocalId;πpub(crate) use crate::ipt_mgr::IptManager;πpub(crate) use crate::ipt_set::IptSet;πpub(crate) use crate::ipt_set::IptsManagerView;πpub(crate) use crate::ipt_set::IptsPublisherUploadView;πpub(crate) use crate::ipt_set::IptsPublisherView;πpub(crate) use crate::ipt_set;πpub(crate) use crate::ipt_set::PublishIptSet;πpub(crate) use crate::keys::expire_publisher_keys;πpub(crate) use crate::keys::IptKeyRole;πpub(crate) use crate::keys::IptKeySpecifier;πpub(crate) use crate::keys::IptKeySpecifierPattern;πpub(crate) use crate::publish::Publisher;πpub(crate) use crate::replay::IptReplayLog;πpub(crate) use crate::replay::ReplayError;πpub(crate) use crate::status::PublisherStatusSender;πpub(crate) use crate::status::State;πpub(crate) use crate::status::IptMgrStatusSender;πpub(crate) use crate::status::State as IptMgrState;πpub(crate) use crate::status::OnionServiceStatus;πpub(crate) use crate::status::OnionServiceStatusStream;πpub(crate) use crate::status::StatusSender;πpub(crate) use crate::time_store;πpub(crate) use crate::timeout_track::TrackingInstantOffsetNow;πpub(crate) use crate::timeout_track::TrackingNow;πpub(crate) use crate::timeout_track::Update as _;πpub(crate) use crate::BlindIdKeypairSpecifier;πpub(crate) use crate::DescSigningKeypairSpecifier;πpub(crate) use crate::HsIdKeypairSpecifier;πpub(crate) use crate::HsIdPublicKeySpecifier;πpub(crate) use crate::ClientError;πpub(crate) use crate::keys::BlindIdKeypairSpecifierPattern;πpub(crate) use crate::rend_handshake;πpub(crate) use crate::rend_handshake::RendCircConnector;πpub(crate) use crate::DescUploadError;πpub(crate) use crate::IptError;πpub(crate) use crate::FatalError;πpub(crate) use crate::RendRequest;πpub(crate) use crate::LinkSpecs;πpub(crate) use crate::NtorPublicKey;πpub(crate) use crate::req::RendRequestContext;πpub(crate) use crate::ShutdownStatus;πpub(crate) use crate::ipt_establish;πpub(crate) use ipt_establish::IptEstablisher;πpub(crate) use ipt_establish::IptParameters;πpub(crate) use ipt_establish::IptStatus;πpub(crate) use ipt_establish::IptStatusStatus;πpub(crate) use ipt_establish::IptWantsToRetire;πpub(crate) use std::pin::Pin;πpub(crate) use tor_keymgr::KeystoreEntry;πpub(crate) use tor_netdir::NetDir;πpub(crate) use oneshot_fused_workaround as oneshot;π
ModulesΒ§
- anon_
level π - Define the
Anonymitytype to indicate a level of anonymity. - broadcast π
- Provides a lossless, MPMC channel. All receivers are guaranteed to recieve each message.
- caps π
- Helpers for capability declaration and negotiation.
- config
- Configuration information for onion services.
- curve25519 π
- Re-exporting Curve25519 implementations.
- ed25519 π
- Re-exporting Ed25519 implementations, and related utilities.
- err π
- Declare an error type for the
tor-hsservicecrate. - fmt π
- Utilities for formatting and printing
Strings. - fs π
- Filesystem manipulation operations.
- future π
- Asynchronous values.
- helpers π
- Functions to help working with onion services.
- internal_
prelude π - Imports used internally within this crate
- io π
- Traits, helpers, and type definitions for core I/O functionality.
- ipt_
establish π - IPT Establisher
- ipt_lid π
IptLocalId- ipt_mgr π
- IPT Manager
- ipt_set π
- IPT set - the principal API between the IPT manager and publisher
- iter π
- Composable external iteration.
- keys π
KeySpecifierimplementations for hidden service keys.- mpsc π
- A multi-producer, single-consumer queue for sending values across asynchronous tasks.
- pow π
- Implementation of
PowManager, for tracking proof-of-work seeds and data for adjusting difficulty. - publish π
- Publish and maintain onion service descriptors
- rend_
handshake π - Implementation for the introduce-and-rendezvous handshake.
- replay π
- Facility for detecting and preventing replays on introduction requests.
- req π
- Request objects used to implement onion services.
- status
- Support for reporting the status of an onion service.
- time_
store π - Saving/loading timestamps to disk
- timeout_
track π - Utilities to track and compare times and timeouts
- watch π
- A state distribution channel. The internal state can be borrowed or cloned, but receivers do not observe every value.
MacrosΒ§
- bad_
api_ πusage - Create a bad API usage error, including a message like
format!, and capturing this call site - chain π
- Chain zero or more iterators together into one sequence.
- debug π
- Constructs an event at the debug level.
- debug_
report π - Log a report for
errat levelDEBUG(or higher if it is a bug). - define_
asref_ πdyn_ std_ error - Defines
AsRef<dyn StdError + 'static>for a type implementingStdError - define_
derive_ πdeftly - Define a reuseable template
- derive_
deftly_ πtemplate_ KeySpecifier - A helper for implementing
KeySpecifiers. - error π
- Constructs an event at the error level.
- error_
report π - Log a report for
errat levelERROR - impl_
debug_ πhex - Define
Debugto print as hex - info π
- Constructs an event at the info level.
- info_
report π - Log a report for
errat levelINFO(or higher if it is a bug). - internal π
- Create an internal error, including a message like
format!, and capturing this call site - into_
bad_ πapi_ usage - Helper for converting an error into an bad API usage error
- into_
internal π - Helper for converting an error into an internal error
- log_
ratelim π - Log a rate-limited failure message.
- select_
biased π - Polls multiple futures and streams simultaneously, executing the branch
for the future that finishes first. Unlike
select!, if multiple futures are ready, one will be selected in order of declaration. Futures directly passed toselect_biased!must beUnpinand implementFusedFuture. - trace π
- Constructs an event at the trace level.
- warn π
- Constructs an event at the warn level.
- warn_
report π - Log a report for
errat levelWARN
StructsΒ§
- AesOpe
Key π - Key for a simple order-preserving encryption on the offset from the start of an SRV protocol run.
- Arc π
- A thread-safe reference-counting pointer. βArcβ stands for βAtomically Reference Countedβ.
- Arti
Path πRange - A range specifying a substring of a
KeyPath. - Assert
Unwind πSafe - A simple wrapper around a type to assert that it is unwind safe.
- Binary
Heap π - A priority queue implemented with a binary heap.
- BufReader π
- The
BufReader<R>struct adds buffering to any reader. - BufWriter π
- Wraps a writer and buffers its output.
- Bug π
- Programming error (a bug)
- Data
Stream π - An anonymized stream over the Tor network.
- Drop
Notify πWatch Sender - Wrapper for
postage::watch::Senderthat sendsDropNotifyEof::eof()when dropped - Duration π
- A
Durationtype to represent a span of time, typically used for system timeouts. - File π
- An object providing access to an open file on the filesystem.
- ForLaunch π
- Objects and handles needed to launch an onion service.
- HashMap π
- A hash map implemented with quadratic probing and SIMD lookup.
- HashSet π
- A hash set implemented as a
HashMapwhere the value is(). - HsBlind
Id π - A blinded onion service identity, represented in a compact format. (
KP_hs_blind_id) - HsBlind
IdKey π - The βblindedβ identity of a v3 onion service. (
KP_hs_blind_id) - HsBlind
IdKeypair π - The private counterpart of a
HsBlindIdKey. - HsCirc
Pool π - An object to provide circuits for implementing onion services.
- HsClient
Desc πEncKey - Client service discovery key, used for onion descriptor
decryption. (
KP_hsc_desc_enc) - HsDesc
Builder π - Builder for
HsDesc. - HsDesc
Signing πKeypair - The private counterpart of a
HsDescSigningKey. - HsDesc
Upload πRequest - A request to upload a hidden service descriptor
- HsDir
Params π - Parameters for generating and using an HsDir ring.
- HsId
- The identity of a v3 onion service. (
KP_hs_id) - HsIdKey π
- The identity of a v3 onion service, expanded into a public key. (
KP_hs_id) - HsId
Keypair π - The private counterpart of a
HsIdKey. - HsIntro
PtSession πIdKey - A key used to identify and authenticate an onion service at a single
introduction point. (
KP_hs_ipt_sid) - HsIntro
PtSession πIdKeypair - The private counterpart of a
HsIntroPtSessionIdKey. - HsNickname π
- Nickname (local identifier) for a Tor hidden service
- HsSvc
Ntor πKeypair - A pair of a public and private components for a
HsSvcNtorKey. - Instance
RawSubdir π - Subdirectory within an instanceβs state, for raw filesystem operations
- Instant π
- A measurement of a monotonically nondecreasing clock.
Opaque and useful only with
Duration. - Invalid
Nickname - Local nickname for Tor Hidden Service (
.onionservice) was syntactically invalid - KeyMgr π
- A key manager that acts as a frontend to a primary
Keystoreand any number of secondaryKeystores. - Lock
File πGuard - Re-export of the lock guard type, as obtained via
ContainsInstanceStateGuardA lock-file for which we hold the lock. - Mutex π
- A mutual exclusion primitive useful for protecting shared data
- Mutex
Guard π - An RAII implementation of a βscoped lockβ of a mutex. When this structure is dropped (falls out of scope), the lock will be unlocked.
- Onion
Service - A handle to an instance of an onion service.
- Onion
Service Builder - Builder for
OnionService. - Open
Options π - Options and flags which can be used to configure how a file is opened.
- OsStr π
- Borrowed reference to an OS string (see
OsString). - Owned
Circ πTarget - OwnedCircTarget is a summary of a
CircTargetthat owns all its members. - Path π
- A slice of a path (akin to
str). - PathBuf π
- An owned, mutable path (akin to
String). - Phantom
Data π - Zero-sized type used to mark things that βact likeβ they own a
T. - Relay π
- A view of a relay on the Tor network, suitable for building circuits.
- Relay
Ids π - RelayIds is an owned copy of the set of known identities of a relay.
- Request
Failed πError - An error that has occurred after we have contacted a directory cache and made a circuit to it.
- Retry
Delay π - An implementation for retrying a remote operation based on a decorrelated jitter schedule.
- Retry
Error π - An error type for use when weβre going to do something a few times, and they might all fail.
- Revision
Counter π - Counts which revision of an onion service descriptor is which, within a given time period.
- Running
Onion Service - A handle to a running instance of an onion service.
To construct a
RunningOnionService, useOnionServiceBuilderto build anOnionService, and then call its.launch()method. - Slug π
- An owned slug, checked for syntax
- Spawn
Error π - An error that occurred during spawning.
- State
Directory π - The whole programβs state directory
- SvcInner π
- Implementation details for an onion service.
- System
Time π - A measurement of the system clock, useful for talking to external entities like the file system or other processes.
- Time
Period π - A period of time, as used in the onion service system.
- VecDeque π
- A double-ended queue implemented with a growable ring buffer.
EnumsΒ§
- AnyRelay
Msg π - A single parsed relay message, sent or received along a circuit
- Config
Build πError - An error related to an option passed to Arti via a configuration builder.
- Cow π
- A clone-on-write smart pointer.
- DirClient
Error π - An error originating from the tor-dirclient crate.
- Either π
- Combines two different futures, streams, or sinks having the same associated types into a single type.
- Error
Kind π - Classification of an error arising from Artiβs Tor operations
- Keystore
Selector π - Specifies which keystores a
KeyMgroperation should apply to. - Meta
Cell πDisposition - A possible successful outcome of giving a message to a
MsgHandler. - Ordering π
- An
Orderingis the result of a comparison between two values. - Reconfigure π
- Rules for reconfiguring a running Arti instance.
- Reconfigure
Error π - An error caused when attempting to reconfigure an existing Arti client, or one of its modules.
- Seek
From π - Enumeration of possible methods to seek within an I/O object.
- Shutdown
Status π - Return value from one call to the main loop iteration
- Timeliness π
- How βtimelyβ must a network directory be?
- Void π
- The empty type for cases which canβt occur.
TraitsΒ§
- Any π
- A trait to emulate dynamic typing.
- Async
Read π - Read bytes asynchronously.
- Async
Write π - Write bytes asynchronously.
- Circ
Target π - Information about a Tor relay used to extend a circuit to it.
- Crypto
Rng π - A marker trait for securely unpredictable infallible RNGs
- Debug π
?formatting.- Deserialize π
- A data structure that can be deserialized from any data format supported by Serde.
- Deserializer π
- A data format that can deserialize any data structure supported by Serde.
- Display π
- Format trait for an empty format,
{}. - FromStr π
- Parse a value from a string
- Future π
- A future represents an asynchronous computation, commonly obtained by use of
async. - HasKind π
- Errors that can be categorized as belonging to an
ErrorKind - Hash π
- A hashable type.
- KeySpecifier π
- The βspecifierβ of a key, which identifies an instance of a key.
- KeySpecifier
Component π - A trait for serializing and deserializing specific types of
Slugs. - KeySpecifier
Component πViaDisplay From Str - Implement
KeySpecifierComponentin terms ofDisplayandFromStr(helper trait) - Launchable π
- Private trait used to type-erase
ForLaunch<R>, so that we donβt need to parameterize OnionService on<R>. - NetDir
Provider π - An object that can provide
NetDirs, as well as inform consumers when they might have changed. - Netdoc
Builder π - Builders for network documents.
- Read π
- The
Readtrait allows for reading bytes from a source. - Runtime π
- A runtime for use by Tor client library code.
- Seek π
- The
Seektrait provides a cursor which can be moved within a stream of bytes. - Serialize π
- A data structure that can be serialized into any data format supported by Serde.
- Serializer π
- A data format that can serialize any data structure supported by Serde.
- Sleep
Provider π - Trait for a runtime that can wait until a timer has expired.
- StdError π
Erroris a trait representing the basic expectations for error values, i.e., values of typeEinResult<T, E>.- Stream π
- A stream of values produced asynchronously.
- Write π
- A trait for objects which are byte-oriented sinks.
- _ π
- An extension trait for
Futures that provides a variety of convenient adapters. - _ π
- An extension trait for
Sinks that provides a variety of convenient combinator functions. - _ π
- An extension trait for
Streams that provides a variety of convenient combinator functions. - _ π
- Adapters specific to
Result-returning streams - _ π
- An
Iteratorblanket implementation that provides extra adaptors and methods. - _ π
- Extension trait for
Spawn. - _ π
- Extensions to
Result<Void, E> - _ π
- A type that can be displayed in a redacted or un-redacted form, but which forces the caller to choose.
- _ π
- A
redactableobject is one where we know a way to display part of it when we are running with safe logging enabled. - _ π
- Extension trait for some
postage::watch::Senderto providemaybe_send - _ π
- Renaming of
Path::displayasdisplay_lossy - _ π
- Extension trait to provide
.gen_range_checked() - _ π
- Trait implemented by anything that can serve as a relay message.
- _ π
- Extension trait providing
.report()method on concrete errors - _ π
- A pattern specifying some or all of a kind of key
- _ π
- An object containing information about a relayβs identity keys.
- _ π
- Objects that co-own a lock on an instance
- _ π
- An extension trait on
SleepProviderfor timeouts and clock delays.
FunctionsΒ§
- chain π
- Takes two iterables and creates a new iterator over both in sequence.
- create_
desc_ πsign_ key_ cert - Create the descriptor signing key certificate.
- list_
expired_ πkeys_ for_ service - Returns all the keys (as
KeystoreEntry) of the service identified bynicknamethat are expired according to the providedHsDirParams. - list_
keys_ πfor_ service - Returns all the keys (as
KeystoreEntry) of the service identified bynickname. - max π
- Compares and returns the maximum of two values.
- maybe_
generate_ πhsid - Generate the identity key of the service, unless it already exists or
offline_hsidistrue. - mpsc_
channel_ πno_ memquota - Precisely
futures::channel::mpsc::channel - onion_
address π - Return the onion address of this service.
- remove_
keys_ πfor_ service - Remove all the keys of the service with the specified
nickname. - send_
request π - Fetch or upload a Tor directory object using the provided stream.
- supported_
hsservice_ protocols - Return a list of the protocolssupported by this crate, running as a hidden service.
Type AliasesΒ§
- BoxStream π
- An owned dynamically typed
Streamfor use in cases where you canβt statically type your result or need to add some indirection. - Link
Specs π - Convenience alias for link specifiers of an intro point
- Ntor
Public πKey - Convenient type alias for an ntor public key
Attribute MacrosΒ§
- async_
trait π
Derive MacrosΒ§
- Constructor π
- What
#[derive(Constructor)]generates - Debug π
- Derive macro generating an impl of the trait
Debug. - Deftly π
- Perform ad-hoc templating driven by a data structure
- Deref π
- Using
#[derive(Deref)] - Deref
Mut π - What
#[derive(DerefMut)]generates - Deserialize π
- Derive macro available if serde is built with
features = ["derive"]. - Educe π
- Error π
- Hash π
- Derive macro generating an impl of the trait
Hash. - Into π
- What
#[derive(Into)]generates - Serialize π
- Derive macro available if serde is built with
features = ["derive"].