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

David Goulet dgoulet at ev0ke.net
Wed Feb 1 19:36:10 UTC 2017

On 26 Jan (15:05:26), George Kadianakis wrote:
> 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].

Ok small modification here. Tor has an API to load/generate ed25519 keys that
uses standard suffix for the keys. Basically, we can use any filename we want
but the secret and public key will be suffixed with "_public_key" and

Thus, I'll make a slight change to the proposal for the key files:


The public key is added because for the offline key case.

Note that currently a relay secret key file is: "ed25519_master_id_secret_key"
so we added the "hs_" part to make it obvious for instance when an operator is
backing up keys that those are for HS.

Furthermore, those are the only keys that will touch the disk (except for
blinded keys in case of offline keys but not implemented yet) thus they are
obviously the "master id" key of the HS.


> - "./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.
> Cheers!
> _______________________________________________
> tor-dev mailing list
> tor-dev at lists.torproject.org
> https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-dev

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 585 bytes
Desc: not available
URL: <http://lists.torproject.org/pipermail/tor-dev/attachments/20170201/d225b2a8/attachment.sig>

More information about the tor-dev mailing list