Module restricted_discovery

Available on crate feature restricted-discovery only.

Configuration for hidden service restricted discovery mode.

By default, hidden services are accessible by anyone that knows their .onion address, this exposure making them vulnerable to DoS attacks. For added DoS resistance, services can hide their discovery information (the list of introduction points, recognized handshake types, etc.) from unauthorized clients by enabling restricted discovery mode.

Services running in this mode are only discoverable by the clients configured in the RestrictedDiscoveryConfig. Everyone else will be unable to reach the service, as the discovery information from the service’s descriptor is encrypted with the keys of the authorized clients.

Each authorized client must generate a service discovery keypair (KS_hsc_desc_enc) and share the public part of the keypair with the service. The service can then authorize the client by adding its public key to the static_keys list, or as an entry in one of the key_dirs specified in its RestrictedDiscoveryConfig.

Restricted discovery mode is only suitable for services that have a known set of no more than MAX_RESTRICTED_DISCOVERY_CLIENTS users. Hidden services that do not have a fixed, well-defined set of users, or that have more than MAX_RESTRICTED_DISCOVERY_CLIENTS users, should use other DoS resistance measures instead.

Live reloading

The restricted discovery configuration is automatically reloaded if watch_configuration is true.

This means that any changes to static_keys or to the .auth files from the configured key_dirs will be automatically detected, so you don’t need to restart your service in order for them to take effect.

Best practices

Each change you make to the authorized clients can result in a new descriptor being published. If you make multiple changes to your restricted discovery configuration (or to the other parts of the onion service configuration that trigger the publishing of a new descriptor, such as anonymity), those changes may not take effect immediately due to the descriptor publishing rate limiting.

To avoid generating unnecessary traffic, you should try to batch your changes as much as possible, or, alternatively, disable watch_configuration until you are satisfied with your configured authorized clients.

Caveats

Unauthorizing previously authorized clients

Removing a previously authorized client from static_keys or key_dirs does not guarantee its access will be revoked. This is because the client might still be able to reach your service via its current introduction points (the introduction points are not rotated when the authorized clients change). Moreover, even if the introduction points are rotated by chance, your changes are not guaranteed to take effect immediately, so it is possible for the service to publish its new introduction points in a descriptor that is readable by the recently unauthorized client.

Restricted discovery mode is a DoS resistance mechanism, not a substitute for conventional access control.

Moving key_dirs

If you move a key_dir (i.e. rename it), all of the authorized clients contained within it are removed (the descriptor is rebuilt and republished, without being encrypted for those clients). Any further changes to the moved directory will be ignored, unless the directory is moved back or a key_dir entry for its new location is added.

Moving the directory back to its original location (configured in key_dirs), will cause those clients to be added back and a new descriptor to be generated.

Key providers

The RestrictedDiscoveryConfig supports two key providers:

• StaticKeyProvider, where keys are specified as a static mapping from nicknames to keys
• DirectoryKeyProvider, which represents a directory of client keys.

Limitations

Hidden service descriptors are not allowed to exceed the maximum size specified in the HSV3MaxDescriptorSize consensus parameter, so there is an implicit upper limit for the number of clients you can authorize (the encrypted section of the descriptor is encrypted for each authorized client, so the more clients there are, the larger the descriptor will be). While we recommend configuring no more than MAX_RESTRICTED_DISCOVERY_CLIENTS clients, the actual limit for your service depends on the rest of its configuration (such as the number of introduction points).

Structs

DirectoryKeyProvider

A directory containing the client keys, each in the descriptor:x25519:<base32-encoded-x25519-public-key> format.

DirectoryKeyProviderBuilder

Builder for DirectoryKeyProvider.

DirectoryKeyProviderListBuilder

Wrapper struct to help derive_builder find the right types and methods

HsClientNickname

Nickname (local identifier) for a hidden service client.

RestrictedDiscoveryConfig

Configuration for enabling restricted discovery mode.

RestrictedDiscoveryConfigBuilder

Builder for RestrictedDiscoveryConfig.

StaticKeyProvider

A static mapping from HsClientNickname to client discovery keys.

StaticKeyProviderBuilder

Wrapper struct to help derive_builder find the right types and methods

Constants

MAX_RESTRICTED_DISCOVERY_CLIENTS

The recommended maximum number of restricted mode clients.

Type Aliases

DirectoryKeyProviderList

The serialized format of a DirectoryKeyProviderListBuilder: