wiki:doc/TorRelaySecurity/OfflineKeys

Offline Relay Identity Keys

The offline identity keys for relays is an optional feature supported as of Tor 0.2.7. Don't use it unless you are willing and able to renew the temporary signing key regularly when it expires. If you leave your relay unattended and forget to renew the temporary signing key, your relay will become unusable and will cease to relay traffic. This will also affect your ability to obtain and keep the Guard and Stable flags. If you use this feature, set some kind of calendar notification for yourself to remind you to renew your temporary signing key before it expires!

Read these two frequently asked questions for a fast introduction on ed25519 router identities: I want to upgrade/move my relay. How do I keep the same key? How do offline ed25519 identity keys work? What do I need to know?

Configuration and Setup

To use offline keys, you must configure Tor not to automatically generate or try to load an existing ed25519 master identity key, since we plan to keep it offline. Add the following option in your torrc file:

OfflineMasterKey 1

Remark on where to generate your Master Keys

Before you go and generate your master keys you should think about where you want to generate and store them, because once the master key is generated in an insecure location there is no going back other than generating new ones.

Some options for locations of your master keys probably are (sorted from more secure to less secure):

  1. an offline computer with no internet connectivity (most secure, but tedious)
  2. within an offline VM on your client machine (i.e. Qubes OS setup)
  3. on your client machine but with a dedicated user that is not used for high risk activities like browsing the web
  4. on your client machine with your ordinary account
  5. on the relay itself but secured with a passphrase
  6. on the relay itself without a passphrase: This defeats the purpose of offline master keys to some extend and is not recommended.

Offline Key Generation

To generate a new ed25519 master identity key to use with this relay, use "tor --keygen" to generate a new ed25519 master identity key. You can optionally encrypt the master identity key with a passphrase, Tor will ask for one when generating the key. If you don't want to encrypt the master identity key, simply don't enter any passphrase when asked and confirm.

tor --keygen can take some optional arguments:

--DataDirectory </path/to/dir> - provide the path where you want to save the files. A 'keys' subfolder will be created automatically under the target folder which will contain the generated files. (Default: $HOME/.tor) NOTE: The user running the --keygen command needs to have read and write permissions in the specified target folder. The generated files will be owned by the user who run the command which can be different from the user running the Tor daemon on the system. To use these files you need to move them to the DataDirectory/keys/ folder of your Tor daemon (if different) and change the owner to the user actually running the Tor daemon on the system (if different).

--SigningKeyLifetime 'n days|weeks|months' - specify a different lifetime for the temporary signing key (Default: 30 days)

Examples: Save the ed25519 master identity key in the default $HOME/.tor folder of the system:

tor --keygen

Save the ed25519 master identity key in a backup folder on an usb drive.

tor --keygen --DataDirectory /media/usb/tor-relays/relay-nickname

Save the ed25519 master identity key in the default $HOME/.tor folder of the system and increase the lifetime of the temporary signing key to 3 months instead of the default 30 days:

tor --keygen --SigningKeyLifetime '3 months'

Save the ed25519 master identity key in a backup folder on an usb drive and increase the lifetime of the temporary signing key to 3 months instead of the default 30 days:

tor --keygen --DataDirectory /media/usb/tor-relays/relay-nickname --SigningKeyLifetime '3 months'

Key Installation and Startup

Move the temporary signing key and certificate to the DataDirectory/keys folder of your Tor daemon. Let's assume you are on Debian and this is /var/lib/tor (in FreeBSD it is /var/db/tor) and you have used "tor --keygen" in the default target folder ($HOME/.tor):

mkdir /var/lib/tor/keys
mv $HOME/.tor/keys/ed25519_master_id_public_key /var/lib/tor/keys/
mv $HOME/.tor/keys/ed25519_signing_* /var/lib/tor/keys/

Fix the permissions and change the owner of the moved files to the user actually running the Tor daemon on your system. Let's assume you are on Debian and this is debian-tor (in FreeBSD it is _tor):

chown -R debian-tor:debian-tor /var/lib/tor/
chmod -R u+X,og-rwx /var/lib/tor/

Now, start the Tor daemon on your system of course configured to run as a relay. This will also automatically generate the soon to be removed old type RSA relay identity. At this moment Tor cannot work without both of these identities (RSA and Ed25519).

service tor start

Back up your keys

Backup all identity keys in a safe place. You are going to need them in case you need to reisntall your relay in the future. We only care about these 2 master identity key files: secret_id_key (RSA identity) ed25519_master_id_secret_key or ed25519_master_id_secret_key_encrypted (Ed25519 identity)

Copy both these files in a safe place, and make sure you pair them together as belonging to the same relay - mixing the Ed25519 identity of a relay with the RSA identity of another relay is bad.

Copy the RSA identity key from your Tor's daemon DataDirectory/keys folder. Let's assume you are on Debian and this is /var/lib/tor/keys (in FreeBSD it is /var/db/tor/keys):

cp /var/lib/tor/keys/secret_id_key /path/to/backup/relay-nickname/

Copy the Ed25519 identity from where it was previously saved by "tor --keygen". Let's assume you didn't use a --datadirectory argument with --keygen and it was saved in the default location ($HOME/.tor)

cp $HOME/.tor/keys/ed25519_master_id_secret_key* /path/to/backup/relay-nickname/

Maintenance

Renewing the Temporary Signing Key

When the temporary signing key and certificate are about to expire, Tor will print warnings in the log file about this. Since the master key is offline, you need to manually renew them with "tor --keygen". To do this, you only need to point Tor to the folder which contains a 'keys' subfolder and the ed25519 master identity secret key.

If the 'keys' folder containing the ed25519 master identity secret key is in the default location, $HOME/.tor, then you only need to run:

tor --keygen

If the 'keys' folder containing the ed25519 master identity secret key is in a backup folder on an usb drive, then you ned to run:

tor --keygen --DataDirectory /media/usb/tor-relays/relay-nickname

If you'd like to create new temporary signing key and certificate with a lifetime of more than the default 30 days, provide in addition a --SigningKeyLifetime argument:

tor --keygen --SigningKeyLifetime '6 months'

The new files will be saved in the same folder where the master identity secret key is. Go back to #KeyInstallationandStartup and move the temporary signing key and certificate to the DataDirectory/keys folder of your Tor daemon and fix the filesystem permissions. Restarting or reloading Tor after renewing the keys is not required.

Using and updating key passwords

tor --keygen allows you to encrypt/decrypt or change the passphrase of an ed25519 master identity key with a --newpass argument.

Examples (if the 'keys' folder containing your ed25519 master identity key is not in $HOME/.tor include a --DataDirectory argument with the correct path):

If you have the ed25519 master identity key saved in plain text and you'd like to encrypt it:

tor --keygen --newpass

Enter a passphrase and confirm it. Tor will encrypt the master identity key and append _encrypted suffix to its filename. There's no passphrase recovery feature so make sure you don't lose it.

If you have the ed25519 master identity key encrypted and you'd like to decrypt it and save it in plain text:

tor --keygen --newpass

Enter the current passphrase, after that don't enter a new passphrase and confirm.

If you want to change the passphrase of your encrypted ed25519 master identity key:

tor --keygen --newpass

Enter the current passphrase, after that the new passphrase and confirm it. There's no passphrase recovery feature so make sure you don't lose it.

We are working on additional arguments for "tor --keygen" (ticket #17127). --master-key : manually provide a path directly to the ed25519 master identity key without the need of a 'keys' folder as required with --DataDirectory. --out : manually provide the path where Tor should save the generated files (temporary signing key and certificate) - currently they are saved in the same location with the ed25519 master identity key.

Troubleshooting

Common root-causes for problems are:

  • key expired but was not renewed
  • wrong temporary key was put in place
  • temporary key and certificate were not moved from the offline master key folder to the DataDirectory/keys folder of the Tor daemon
  • filesystem permissions haven't been taken care of after renewing the temporary keys

Tor does not provide an option to display the expiry date yet (#17639), but there is a minimal python script to show the expiry date:

import time
with open('ed25519_signing_cert', 'rb') as f:
    x = f.read()
    print time.ctime(int(x[35:38].encode('hex'), 16) * 3600)
Last modified 17 months ago Last modified on May 26, 2016, 9:00:19 PM