arti/doc/dev/notes/onion_service_keys.md

Here are some keys that we need to store for onion services.

Below, we label some keys as "offline" keys, meaning that they are not strictly necessary for running an onion service or client minute-by-minute, and that it might be desirable to store them in a more secure environment. We label some processes as "offline" processes, meaning that they can happen infrequently in the background, and that it might be desirable to perform them in a more secure environment.

As a convenience feature, it should be possible to store these keys and perform these processes online, if a more secure environment is not desired.

Clients

Onion service clients need to remember and configure the following private keys:

• For a given onion service:
  • Any authentication keys in use with that onion service. (KS_hs_client_desc_auth or KS_hs_client_intro_auth)

The keys above are generated offline; their public keys are given to the onion service operator offline. They need to be available at runtime.

The public keys associated with them need to be encoded and transferred textually or in a file, for use by onion service providers. There is a passwd-style format for these, described in the C tor manual page, under HiddenServiceDirectory/client_keys and under the heading CLIENT AUTHORIZATION.

Services

Each onion service need these keys to operate:

• For each time period:
  • A private descriptor signing key (KS_hs_desc_sign),
  • A certificate for that signing key, signed with the BlindedOnionId for that time period (KP_blind_id).

To generate those certificates, each onion service needs these offline keys:

• A secret identity key (KS_hs_id).

To operate, an onion service needs these secret keys, which do not have to be persistent. The corresponding public keys are published in the service descriptor:

• A ntor key for its cryptographic handshake (KS_hss_ntor).
• A signing key associated with each active introduction point. (KS_hs_intro_auth)

For client authorization, the onion service needs to have:

• a list of authorized keys (KS_hs_client_desc_auth or KS_hs_client_intro_auth)

---

What C tor does

A client has a directory of private keys, called its ClientOnionAuthDir. It contains a list of files, each containing a singleonion ID (KP_hs_id), and a single associated authentication key (KP_hs_client_intro_auth). Only files that end with .auth_private are considered; others are ignored.

An onion service stores all of its material in a single directory, called its HiddenServiceDir. That directory contains:

• authorized_keys -- a directory containing a list of authorized client keys (KP_hs_client_intro_auth), one per file. Filenames are ignored.
• hostname -- A file containing the .onion address for this service
• private_key -- The secret identity key. (KS_hs_id)
• client_keys -- an under-specified store for client keys of another kind. (KP_hs_client_desc_auth)
• onion_service_non_anonymous -- a file generated for single onion services.

Note that C tor only stores only secret identity key for services: it doesn't persist any other keys to disk. Because of that, C tor only supports running with an online secret identity key.

Modes of Operation for Arti

For authorization and authentication keys:

• Perhaps there should be a mode where you just create files in a directory, and Arti processes them correctly.
• Perhaps there should be a CLI tool that generates keys for you.
• Perhaps there should eventually be an option to store keys in some password-protected way. Or we could just punt, and say that if you want password-protected storage, you should use an encrypted volume.

For service keys:

• There needs to be a separate set of keys for each onion service. Maybe they could be stored in location specified in the configuration file (like Tor does it); or maybe they could be stored in a keys/hs directory, with a tag derived from a name for the onion service provided by the user?
• There needs to be support for running with an online identity key, and generating certificates and signing keys as needed.
• There should (eventually) be support for running with provisioned keys only, and provisioning them offline.
  • We do not need to make any keys besides the identity key persistent until this happens. However, we should have some idea of how we would store other keys, to make sure we are not designing ourselves into a corner.
• There is no need to make any other keys persistent.