Skip to main content

Crate tor_hsservice

Crate tor_hsservice 

Source
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 Anonymity type 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-hsservice crate.
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 πŸ”’
KeySpecifier implementations 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 err at level DEBUG (or higher if it is a bug).
define_asref_dyn_std_error πŸ”’
Defines AsRef<dyn StdError + 'static> for a type implementing StdError
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 err at level ERROR
impl_debug_hex πŸ”’
Define Debug to print as hex
info πŸ”’
Constructs an event at the info level.
info_report πŸ”’
Log a report for err at level INFO (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 to select_biased! must be Unpin and implement FusedFuture.
trace πŸ”’
Constructs an event at the trace level.
warn πŸ”’
Constructs an event at the warn level.
warn_report πŸ”’
Log a report for err at level WARN

StructsΒ§

AesOpeKey πŸ”’
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’.
ArtiPathRange πŸ”’
A range specifying a substring of a KeyPath.
AssertUnwindSafe πŸ”’
A simple wrapper around a type to assert that it is unwind safe.
BinaryHeap πŸ”’
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)
DataStream πŸ”’
An anonymized stream over the Tor network.
DropNotifyWatchSender πŸ”’
Wrapper for postage::watch::Sender that sends DropNotifyEof::eof() when dropped
Duration πŸ”’
A Duration type 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 HashMap where the value is ().
HsBlindId πŸ”’
A blinded onion service identity, represented in a compact format. (KP_hs_blind_id)
HsBlindIdKey πŸ”’
The β€œblinded” identity of a v3 onion service. (KP_hs_blind_id)
HsBlindIdKeypair πŸ”’
The private counterpart of a HsBlindIdKey.
HsCircPool πŸ”’
An object to provide circuits for implementing onion services.
HsClientDescEncKey πŸ”’
Client service discovery key, used for onion descriptor decryption. (KP_hsc_desc_enc)
HsDescBuilder πŸ”’
Builder for HsDesc.
HsDescSigningKeypair πŸ”’
The private counterpart of a HsDescSigningKey.
HsDescUploadRequest πŸ”’
A request to upload a hidden service descriptor
HsDirParams πŸ”’
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)
HsIdKeypair πŸ”’
The private counterpart of a HsIdKey.
HsIntroPtSessionIdKey πŸ”’
A key used to identify and authenticate an onion service at a single introduction point. (KP_hs_ipt_sid)
HsIntroPtSessionIdKeypair πŸ”’
The private counterpart of a HsIntroPtSessionIdKey.
HsNickname πŸ”’
Nickname (local identifier) for a Tor hidden service
HsSvcNtorKeypair πŸ”’
A pair of a public and private components for a HsSvcNtorKey.
InstanceRawSubdir πŸ”’
Subdirectory within an instance’s state, for raw filesystem operations
Instant πŸ”’
A measurement of a monotonically nondecreasing clock. Opaque and useful only with Duration.
InvalidNickname
Local nickname for Tor Hidden Service (.onion service) was syntactically invalid
KeyMgr πŸ”’
A key manager that acts as a frontend to a primary Keystore and any number of secondary Keystores.
LockFileGuard πŸ”’
Re-export of the lock guard type, as obtained via ContainsInstanceStateGuard A lock-file for which we hold the lock.
Mutex πŸ”’
A mutual exclusion primitive useful for protecting shared data
MutexGuard πŸ”’
An RAII implementation of a β€œscoped lock” of a mutex. When this structure is dropped (falls out of scope), the lock will be unlocked.
OnionService
A handle to an instance of an onion service.
OnionServiceBuilder
Builder for OnionService.
OpenOptions πŸ”’
Options and flags which can be used to configure how a file is opened.
OsStr πŸ”’
Borrowed reference to an OS string (see OsString).
OwnedCircTarget πŸ”’
OwnedCircTarget is a summary of a CircTarget that owns all its members.
Path πŸ”’
A slice of a path (akin to str).
PathBuf πŸ”’
An owned, mutable path (akin to String).
PhantomData πŸ”’
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.
RelayIds πŸ”’
RelayIds is an owned copy of the set of known identities of a relay.
RequestFailedError πŸ”’
An error that has occurred after we have contacted a directory cache and made a circuit to it.
RetryDelay πŸ”’
An implementation for retrying a remote operation based on a decorrelated jitter schedule.
RetryError πŸ”’
An error type for use when we’re going to do something a few times, and they might all fail.
RevisionCounter πŸ”’
Counts which revision of an onion service descriptor is which, within a given time period.
RunningOnionService
A handle to a running instance of an onion service. To construct a RunningOnionService, use OnionServiceBuilder to build an OnionService, and then call its .launch() method.
Slug πŸ”’
An owned slug, checked for syntax
SpawnError πŸ”’
An error that occurred during spawning.
StateDirectory πŸ”’
The whole program’s state directory
SvcInner πŸ”’
Implementation details for an onion service.
SystemTime πŸ”’
A measurement of the system clock, useful for talking to external entities like the file system or other processes.
TimePeriod πŸ”’
A period of time, as used in the onion service system.
VecDeque πŸ”’
A double-ended queue implemented with a growable ring buffer.

EnumsΒ§

AnyRelayMsg πŸ”’
A single parsed relay message, sent or received along a circuit
ConfigBuildError πŸ”’
An error related to an option passed to Arti via a configuration builder.
Cow πŸ”’
A clone-on-write smart pointer.
DirClientError πŸ”’
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.
ErrorKind πŸ”’
Classification of an error arising from Arti’s Tor operations
KeystoreSelector πŸ”’
Specifies which keystores a KeyMgr operation should apply to.
MetaCellDisposition πŸ”’
A possible successful outcome of giving a message to a MsgHandler.
Ordering πŸ”’
An Ordering is the result of a comparison between two values.
Reconfigure πŸ”’
Rules for reconfiguring a running Arti instance.
ReconfigureError πŸ”’
An error caused when attempting to reconfigure an existing Arti client, or one of its modules.
SeekFrom πŸ”’
Enumeration of possible methods to seek within an I/O object.
ShutdownStatus πŸ”’
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.
AsyncRead πŸ”’
Read bytes asynchronously.
AsyncWrite πŸ”’
Write bytes asynchronously.
CircTarget πŸ”’
Information about a Tor relay used to extend a circuit to it.
CryptoRng πŸ”’
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.
KeySpecifierComponent πŸ”’
A trait for serializing and deserializing specific types of Slugs.
KeySpecifierComponentViaDisplayFromStr πŸ”’
Implement KeySpecifierComponent in terms of Display and FromStr (helper trait)
Launchable πŸ”’
Private trait used to type-erase ForLaunch<R>, so that we don’t need to parameterize OnionService on <R>.
NetDirProvider πŸ”’
An object that can provide NetDirs, as well as inform consumers when they might have changed.
NetdocBuilder πŸ”’
Builders for network documents.
Read πŸ”’
The Read trait allows for reading bytes from a source.
Runtime πŸ”’
A runtime for use by Tor client library code.
Seek πŸ”’
The Seek trait 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.
SleepProvider πŸ”’
Trait for a runtime that can wait until a timer has expired.
StdError πŸ”’
Error is a trait representing the basic expectations for error values, i.e., values of type E in Result<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 Iterator blanket 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 redactable object 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::Sender to provide maybe_send
_ πŸ”’
Renaming of Path::display as display_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 SleepProvider for 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 by nickname that are expired according to the provided HsDirParams.
list_keys_for_service πŸ”’
Returns all the keys (as KeystoreEntry) of the service identified by nickname.
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_hsid is true.
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 Stream for use in cases where you can’t statically type your result or need to add some indirection.
LinkSpecs πŸ”’
Convenience alias for link specifiers of an intro point
NtorPublicKey πŸ”’
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)]
DerefMut πŸ”’
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"].