torrc path option for happy families key file

When implementing Happy Families for ansible-relayor I realized two issues I want suggest a change now that no tor release with happy families has been released yet:

• Unfortunately it is not possible to tell tor where to find the key file

• the idea was to copy the file only once per server because all tor instances need the same file

• but tor expects it to be in the keys folder, which requires the creation of many files/links instead of a single file

• the torrc configuration needs to be changed when changing the key, if the torrc were to point to the file the torrc file would not need any changes

background: relayor and families are primarily for operators running more than one tor daemon on a server for scalability reasons.

For relayor this problem is solvable due to automation but manually operated relays will be more affected by these limitations and these limits might increase the risk that relays are not properly configured.

Suggestions for improvements:

• allow configuring the path to the keys file with a torrc option - the option may be used multiple times
• make the FamilyID string optional in the torrc file

changed title from torrc path option for happy families file to torrc path option for happy families key file

CC @nickm

Something like this would be useful indeed. All our relays are configured manually (by design), so having to manage these key files individually would add a significant management and monitoring burden. All while being more prone to errors and mistakes.

For the family we synchronize a file with all our relays between our servers (one per server) and then include it in all our relays with %include /.../.../.../.../myfamily. I suspect this is fairly common for other operators not using automation. Something similar for the new family setup would be great, for example: FamilyKeyFile /dir/to/keyfile (which would of course be part of another torrc-default file that gets referenced by a %include /path/to/torrc-default in the relay specific configuration file).

Especially when you run more than a few relays, it's beneficial (from a management and monitoring perspective) to keep the relay specific configuration as minimal as possible. And in this case there is no technical reason to make this family key a relay specific configuration option, since it's a shared key between all relays by design.

So long story short: I think this is an excellent suggestion by @nusenu .

FWIW - Also following same manual approach as NTH across ~300 relays and would appreciate same configuration changes. Thanks for this great work!

assigned to @nickm

How would it be to have a directory instead of a file? That would be the simplest to implement, since we already have directory scanning for the KeyDir.

That would be fine I think. So then a operator would create a directory, put the key file in it, point FamilyKeyDir (or whatever) to the correct directory and Tor would use a valid key file automatically?

Does the key file need to conform to a specific file name or is any file name okay as long as the file contains the key in the correct layout/format? Both are fine, just asking to understand how this would work from a operator's perspective :).

As with the current KeyDir, any filename would be fine, so long as it ends with ".secret_family_key"

@nickm FamilyKeyDir and not requiring FamilyID in torrc would even be better than FamilyKeyFile because it would make key rotation more seamless because no torrc change is required then.

Thank you for picking up this ticket and suggesting the directory variant, and thank you for the relay operators supporting this gitlab issue.

Looking forward to testing it!

@nickm how will this behave if multiple .secret_family_key files exist in the directory? Will it use the alphabetical first or last?

Thinking a bit further on how rotation could be done without replacing the key straight up.

Easier than before with 2 or more FamilyId lines in torrc how-to-rotate-family-keys

Generate a new key and throw it into the key directory. After a few days delete the old one.

@nickm how will this behave if multiple .secret_family_key files exist in the directory? Will it use the alphabetical first or last?

It uses all the ones that are listed in FamilyID entries in the Torrc. Multiple entries are allowed.

@boldsuck @nickm So there is no chance in not requiring FamilyID entries?

We would like to avoid config edits at all costs as SIGHUP does not always reload the daemon when it is sandboxed and restarts are tedious. I assume this is what @nusenu is after as well in his previous comment.

I can add a FamilyID * option to say "use all the family IDs you find`, but they would still only get re-scanned on sighup, which I guess is not what you want?

So there is no chance in not requiring FamilyID entries?

@r0cket FamilyKeyDir is a one-time configuration in torrc.

If you want to rotate keys later, simply add a new family_key to the dir. It's best to do this before a kernel or tor upgrade, so you don't have to restart tor unnecessarily. And before the next tor upgrade, remove the old keys from the dir.

added Backlog label

+1 For a directory instead of a file. And although other directories can be configured, I think /var/lib/tor/keys/ is the most suitable. This is already created and empty if you have multiple instances. Bonus: No hassle with apparmor

added Next label and removed Backlog label

mentioned in merge request !875 (merged)

added 4h of time spent

Can anybody test the code at !875 (merged) , to make sure it works for you? It adds an option to set a FamilyIdKeyDirectory, other than normal KeyDirectory. Additionally, it lets you say FamilyId *,to use all the family keys found in that directory.

added Needs Review label and removed Next label

Thank you Nick!

I've tested

FamilyKeyDirectory /path/to/folder
FamilyId *

using https://gitlab.torproject.org/nickm/tor/-/tree/happy-families-ux f13f8a2f with and without Sandbox 1

and it achieves the main goal of this issue: support setting a custom path/folder and not requiring torrc config changes on key rotation.

A few remarks:

• maybe add something like this to the Sandbox section of the man page: "When Sandbox is 1 tor will not load new family keys on SIGHUP" in addition to the already present

(Note that if the seccomp2 Sandbox feature is enabled, it is not possible to change the key filenames while Tor is running.)

• the man page makes inconsistent use of "FamilyID" vs. "FamilyId"
• FamilyKeyDirectory man page section: Maybe make operators aware that this is a sensitive folder and that unauthorized read and write access must be prevented by setting proper folder permissions and that tor only needs read access to the folder.

To go further, can there be some default behavior not requiring any torrc changes from the current production versions today? Thinking forward to when a new version of Tor supports this, would be nice to have the least amount of effort required for the operator to implement / "upgrade".

If there are key files in the "normal" key directory, i.e. /var/lib/tor/keys for example, with filenames ending in .secret_family_key, can Tor automatically detect and use those without requiring changes to torrc? Another words, put key files ending in .secret_family_key into /var/lib/tor/keys (existing default key directory) and Tor will scan and start using (require SIGHUP) without requiring these two lines in the torrc, FamilyKeyDirectory or FamilyId?

Maybe this addresses the previous comment from @r0cket of not requiring any torrc changes? #41033 (comment 3178867)

Do note that Tor doesn't have a "default" or "normal" key directory. On GNU/Linux it might be /var/lib/tor (often at least), but this isn't the case for other platforms such as FreeBSD, OpenBSD, HardenedBSD, Windows, MacOS, DragonflyBSD, NetBSD, OpenSolaris etc.

And I don't think we should make this too complicated. For most people, it's just copying:

FamilyKeyDirectory /path/to/folder
FamilyId *

into one file per server. If you push the FamilyKey to the server and adjust its permissions, this one-time config is really no big deal. We have waited so many years for this feature and I no longer believed that it would be included in c-tor ;-)

I'm curious if @nusenu uses the FamilyKey's for AROI proof in OrNetStat, e.g: proof:dns-rsa familyfingerprint.example.com value: "we-run-this-family"

Unrelated to Familykeys, but because it's important, I'd like to draw attention to it again. I hope that these features: reapply exit policy on reload & add token bucket limiter on new stream per circuit of @trinity-1686a will soon be in tor stable.

For default behavior, if we make these two assumptions: 1) fewer operator required changes leads to more adoption, 2) Tor already has a mechanism on all OSes to store keys for fingerprints today, then we should have a way to have zero new parameters in torrc and use existing Tor mechanisms for managing keys which leads to more adoption, less maintenance, less opportunity for mistakes, etc.

Nothing wrong with also having more complex behavior by modifying torrc with FamilyKeyDirectory and FamilyId but why make that required instead of optional?

Why should the default behavior require more steps, more new information, and more changes with two new torrc parameters? Those should be optional, for greater control and more advanced users, not required for all users?

Can the default behavior with no torrc changes be the easiest way to configure a family for Tor relays? The more all other 4000+ relays adopt the concept of family, the healthier the Tor network?

Most of the work is creating the key, copying it to the server and adjusting the file owner and permissions of the key.

In contrast to old MyFamily, my MyFamilyKey makes work much easier. For each new instance, MyFamily must be adjusted on all servers. We've been waiting for over five years for MyFamilyKeys to become a reality, and we'll probably have to spend the next two or three years configuring MyFamily and my MyFamilyKey. The longer we discuss this, the longer we'll have to configure MyFamily.

With every second or third Tor release, new features come along, and we have to configure the torrc to use them. I don't understand the difficulty of adding a config line that would forever relieve us of the work of the old MyFamily config.

Before diving into this discussion I want to note that the two points I opened this issue for are solved by Nick's branch happy-families-ux f13f8a2f.

Do I see value in discussing configuration usability for happy families?

Yes, because network health people and I will have to deal with the negative consequences of potentially poor usability - meaning low adoption and high misconfiguration rate - for a long time.

Is this the correct place for this discussion?

Probably not.

That said I compare the 3 options:

1. current state: https://gitlab.torproject.org/nickm/tor/-/tree/happy-families-ux f13f8a2f without using FamilyKeyDirectory

required steps by the operator:

• generate the key file - for example: family.secret_family_key
• copy family.secret_family_key into the default keys folder (not using FamilyKeyDirectory).
  • tor's default keys directory is: the "keys" subdirectory of DataDirectory. This is the folder where tor expects the family keys when FamilyKeyDirectory is not used.
• make sure the filesystem permissions on family.secret_family_key allow tor to read the file
• add the torrc config line FamilyId *
• restart tor, which is required anyway when upgrading

2. suggestion by 1aeo (not requiring torrc changes; FamilyId * is the implicit default)

same as (1) but without this step:

• add the torrc config line FamilyId *

This is a potential usability improvement because it requires fewer steps.

• Are there some good reasons to not make it the default behavior?
• What are there potential negative side effects of making FamilyId * the default behavior?
• Is there an upper limit of family keys in case someone generates a lot of them?

3. current state: https://gitlab.torproject.org/nickm/tor/-/tree/happy-families-ux f13f8a2f using FamilyKeyDirectory

This is the one relayor will use and it can coexist with the behavior (2).

required steps by the operator:

• generate the key file family.secret_family_key
• copy family.secret_family_key into FamilyKeyDirectory
• make sure the filesystem permissions on the FamilyKeyDirectory folder allow a specific group to read the files
• add all tor per-instance users to that specific group
• add the the two torrc config lines:
  • FamilyKeyDirectory /path/to/folder
  • FamilyId * (optional if it is the default)
• restart tor, which is required anyway when upgrading

If (3) is used manually, it would require one config line less if FamilyId * is the default behaviour.

So in general it is about

• copy the family keys in the correct folder with proper permissions (1)

vs.

• copy the family keys in the correct folder with proper and add FamilyId * to your torrc (2)

I'm fine with both with a slight preference towards making FamilyId * the default behavior if there are no strong reasons against it. Maybe network health people should also weight in.

Before diving into this discussion I want to note that the two points I opened this issue for are solved by Nick's branch happy-families-ux f13f8a2f.

Yes, in my opinion that is the most viable solution.

So in general it is about

• copy the family keys in the correct folder with proper permissions (1)

vs.

• copy the family keys in the correct folder with proper and add FamilyId * to your torrc (2)

I'm fine with both with a slight preference towards making FamilyId * the default behavior if there are no strong reasons against it. Maybe network health people should also weight in.

I'm fine with both too. Regardless of whether FamilyId * is the default behavior or not, I, and probably most people, have to configure one or the other torrc instance. I think many people have HiddenService instances in addition to their relay instances. HiddenService instances must then be configured not to use default FamilyId * if tor automatically detect and use those.

Ultimately, @nickm has to decide how much work he wants to put into c-tor. (Especially auto detecting KeyDir on all OS requires a lot of time to test.)

Because as I said, we are replacing a config option that previously required multiline and keeping dozens or hundreds of fingerprints in sync. And this fingerprint synchronization has led to low adoption and misconfiguration. Therefore, each of the above options is a significant relief.

Let's move that discussion to tor-relays: https://lists.torproject.org/mailman3/hyperkitty/list/tor-relays@lists.torproject.org/thread/QPH3BN7PBMNW4PC65PRJXFUQ3YZNGICE/

mentioned in commit d6887404

closed with merge request !875 (merged)