Crate tor_hsservice

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.

Limitations

This crate is a work in progress.

As of February 2024, there are some features missing that are necessary for running a secure, private onion service. Notably these include:

• Resistance to denial of service attacks
  • Support for proof-of-work checking and validation
  • Detection and response to out-of-memory conditions
• Vanguard relays for resistance to path discovery
• Descriptor encryption keys, so that only certain clients to connect to the service.
• Removal of old keys and state information. (Currently, the on-disk state will grow slowly but without bound, with sensitive information retained indefinitely.)

Reference

You can learn more about the protocols here as part of the onion services Specification.

LICENSE: MIT OR Apache-2.0

Re-exports

• pub use config::OnionServiceConfig;

Modules

• anon_level 🔒
  Define the Anonymity type to indicate a level of anonymity.
• config
  Configuration information for onion services.
• err 🔒
  Declare an error type for the tor-hsservice crate.
• helpers 🔒
  Functions to help working with onion services.
• internal_prelude 🔒
  Imports used internally within this crate
• ipt_establish 🔒
  IPT Establisher
• ipt_lid 🔒
  IptLocalId
• ipt_mgr 🔒
  IPT Manager
• ipt_set 🔒
  IPT set - the principal API between the IPT manager and publisher
• keys 🔒
  KeySpecifier implementations for hidden service keys.
• netdir 🔒
  Helpers for obtaining NetDirs.
• nickname 🔒
  HsNickname module itself is private, but HsNickname etc. are re-exported
• 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

Structs

• BlindIdKeypairSpecifier
  The blinded signing keypair.
• BlindIdPublicKeySpecifier
  The blinded public key.
• DescSigningKeypairSpecifier
  The descriptor signing key.
• ForLaunch 🔒
  Objects and handles needed to launch an onion service.
• HsIdKeypairSpecifier
  The long-term identity keypair of the service.
• HsIdPublicKeySpecifier
  The public part of the identity key of the service.
• HsNickname
  Nickname (local identifier) for a Tor hidden service
• InvalidNickname
  Local nickname for Tor Hidden Service (.onion service) was syntactically invalid
• NetdirProviderShutdown
  The network directory provider is shutting down without giving us the netdir we asked for.
• OnionService
  A handle to an instance of an onion service, which may or may not be running.
• OnionServiceState 🔒
  The state of an instance of an onion service.
• RendRequest
  Request to complete an introduction/rendezvous handshake.
• RunningOnionService
  A handle to a running instance of an onion service.
• StreamRequest
  A request from a client to open a new stream to an onion service.
• SvcInner 🔒
  Implementation details for an onion service.

Enums

• Anonymity
  The level of anonymity that an onion service should try to run with.
• ClientError
  An error which occurs trying to communicate with a particular client.
• DescUploadError
  An error that occurs while trying to upload a descriptor.
• EstablishSessionError
  An error produced while trying to connect to a rendezvous point and open a session with a client.
• FatalError
  An error which means we cannot continue to try to operate an onion service.
• IntroRequestError
  An error produced while trying to process an introduction request we have received from a client via an introduction point.
• IptError
  An error caused by a faulty IPT.
• ShutdownStatus 🔒
  Return value from one call to the main loop iteration
• StartupError
  An error which occurs trying to create and start up an onion service

Traits

• Launchable 🔒
  Private trait used to type-erase ForLaunch<R>, so that we don’t need to parameterize OnionService on <R>.

Functions

• handle_rend_requests
  Consume a stream of RendRequest, accepting them all, and produce a stream of StreamRequest.
• maybe_generate_hsid 🔒
  Generate the identity key of the service, unless it already exists or offline_hsid is true.

Type Aliases

• LinkSpecs 🔒
  Convenience alias for link specifiers of an intro point
• NtorPublicKey 🔒
  Convenient type alias for an ntor public key