[tor-dev] [RFC] Directory structure of prop224 onion services

George Kadianakis desnacked at riseup.net
Thu Jan 26 13:05:26 UTC 2017

Hey list,

with service-side prop224 implementation moving forward, we need to pin down
the directory structure of prop224 onion services. This will be very similar to
the current directory structure, but with some mods to facilitate assymetric
client authorization keys and offline keys.

As people have pointed out, the HS directory structure matters less after the
introduction of ephemeral ADD_ONION onion services, but still it's an important
part of onion service sysadmin UX.

So the HiddenServiceDir directory will contain the following items:

- "./hostname"    [FILE]

   This is a file containing the onion address of the onion service.

   As you can see it's the same filename as in v2. Should we suffix it with v3
   to make it clear that it's v3 onion? Would we ever have v2 and v3 onions
   living in the same directory?

- "./private_key_ed25519"  [FILE]

   This is the file containing the private master ed25519 key of the onion service.

   If offline keys are _enabled_, then this file doesn't exist and instead a
   directory is made containing blinded keys for every day [TODO: The directory
   format here will be specified in the future].

- "./client_authorized_pubkeys"   [FILE]

  If client authorization is _enabled_, this is a newline-separated file of
  "<client name> <pubkey>" entries for authorized clients. You can think of it
  as the ~/.ssh/authorized_keys of onion services.

- "./client_authorized_privkeys/"          [DIRECTORY]
  "./client_authorized_privkeys/alice"     [FILE] 
  "./client_authorized_privkeys/bob"       [FILE]
  "./client_authorized_privkeys/charlie"   [FILE]
  If client authorization is _enabled_ _AND_ if the hidden service is
  responsible for generating and distributing private keys for its clients,
  then this directory contains files with client's private keys. The idea is
  that these files can be shredded and deleted after the private key has been
  passed to the client. For more context here, please read the client
  authorization thread in [tor-dev] and see 'Appendix F' of prop224 for more
  details on how this works.

So this is it. The above should handle most uses of onion services + client
authorization. The directory format of offline keys will be specified as we
move forward with implementation. 

Hope things here are not too controversial. Looking forward to your feedback.

In a few days, I will add a small Appendix section to prop224 with the
above, and also fix the parts of 'Appendix F' that got outdated since then.


More information about the tor-dev mailing list