1  Here are some keys that we need to store for onion services.
  2  
  3  Below, we label some keys as "offline" keys, meaning that they are not
  4  strictly necessary for running an onion service or client minute-by-minute,
  5  and that it might be desirable to store them in a more secure environment.
  6  We label some processes as "offline" processes, meaning that they can happen
  7  infrequently in the background, and that it might be desirable to perform
  8  them in a more secure environment.
  9  
 10  As a convenience feature, it _should_ be possible to store these keys and
 11  perform these processes online, if a more secure environment is not desired.
 12  
 13  
 14  # Clients
 15  
 16  Onion service clients need to remember and configure the following private
 17  keys:
 18  
 19    * For a given onion service:
 20       * Any authentication keys in use with that onion
 21         service. (`KS_hs_client_desc_auth` or `KS_hs_client_intro_auth`)
 22  
 23  The keys above are generated offline; their public keys are given to the
 24  onion service operator offline.  They need to be available at runtime.
 25  
 26  The public keys associated with them need to be encoded and transferred
 27  textually or in a file, for use by onion service providers.
 28  There is a passwd-style format for these, described in the C tor manual page,
 29  under `HiddenServiceDirectory/client_keys`  and under the heading `CLIENT
 30  AUTHORIZATION`.
 31  
 32  
 33  # Services
 34  
 35  Each onion service need these keys to operate:
 36  
 37    * For each time period:
 38      * A private descriptor signing key (`KS_hs_desc_sign`),
 39      * A certificate for that signing key, signed with the `BlindedOnionId`
 40        for that time period (`KP_blind_id`).
 41  
 42  To generate those certificates, each onion service needs
 43  these offline keys:
 44  
 45    * A secret identity key (`KS_hs_id`).
 46  
 47  To operate, an onion service needs these secret keys, which do not have to be
 48  persistent.
 49  The corresponding public keys are published in the service descriptor:
 50    * A ntor key for its cryptographic handshake (`KS_hss_ntor`).
 51    * A signing key associated with each active introduction point.
 52      (`KS_hs_intro_auth`)
 53  
 54  For restricted discovery, the onion service needs to have:
 55    * **a list of authorized keys**  (`KS_hs_client_desc_auth` or
 56      `KS_hs_client_intro_auth`)
 57  
 58  ----
 59  
 60  # What C tor does
 61  
 62  A client has a directory of private keys, called its `ClientOnionAuthDir`.
 63  It contains a list of files, each containing a singleonion ID (KP_hs_id), and
 64  a single associated authentication key (`KP_hs_client_intro_auth`).
 65  Only files that end with `.auth_private` are considered; others are
 66  ignored.
 67  
 68  
 69  An onion service stores all of its material in a single directory, called its
 70  `HiddenServiceDir`.  That directory contains:
 71    * `authorized_keys` -- a directory containing a list of authorized client
 72      keys (`KP_hs_client_intro_auth`), one per file. Filenames are ignored.
 73    * `hostname` -- A file containing the `.onion` address for this service
 74    * `private_key` -- The secret identity key. (`KS_hs_id`)
 75    * `client_keys` -- an under-specified store for client keys of another
 76      kind.
 77      (`KP_hs_client_desc_auth`)
 78    * `onion_service_non_anonymous` -- a file generated for single onion
 79      services.
 80  
 81  Note that C tor only stores only secret identity key for services: it doesn't
 82  persist any other keys to disk.
 83  Because of that, C tor only supports running with an online secret identity
 84  key.
 85  
 86  # Modes of Operation for Arti
 87  
 88  For authorization and authentication keys:
 89    * Perhaps there should be a mode where you just create files in a
 90      directory, and Arti processes them correctly.
 91    * Perhaps there should be a CLI tool that generates keys for you.
 92    * Perhaps there should eventually be an option to store keys in some
 93      password-protected way.  Or we could just punt, and say that if you want
 94      password-protected storage, you should use an encrypted volume.
 95  
 96  For service keys:
 97    * There needs to be a separate set of keys for each onion service.
 98      Maybe they could be stored in location specified in the configuration
 99      file (like Tor does it); or maybe they could be stored in a `keys/hs`
100      directory, with a tag derived from a name for the onion service provided
101      by the user?
102    * There needs to be support for running with an online identity key, and
103      generating certificates and signing keys as needed.
104    * There should (eventually) be support for running with provisioned keys
105      only, and provisioning them offline.
106       * We do not need to make any keys besides the identity key persistent
107         until this happens.
108         However, we should have some idea of _how_ we would store other keys,
109         to make sure we are not designing ourselves into a corner.
110    * There is no need to make any other keys persistent.
111  
112