wiki:doc/TorRelaySecurity/OfflineKeys

Version 4 (modified by mikeperry, 4 years ago) (diff)

Remove references to sections by number

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 {1 - link to "I want to upgrade/move my relay. How do I keep the same key?"} {2 - link to " How do offline ed25519 identity keys work? What do I need to know?" frequently asked questions} FAQ for a fast introduction on ed25519 identities.

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

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/* /var/lib/tor/keys/*
chmod -R 700 /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.

Examples: The 'keys' folder containing the ed25519 master identity secret key is in the default location, $HOME/.tor: tor --keygen 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, fix the permissions, and restart or reload (SIGHUP) your Tor process.

The 'keys' folder containing the ed25519 master identity secret key is in a backup folder on an usb drive: tor --DataDirectory /media/usb/tor-relays/relay-nickname --keygen 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, fix the permissions, and restart or reload (SIGHUP) your Tor process.

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, fix the permissions, and restart or reload (SIGHUP) your Tor process.

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): 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 the 'keys' folder containing the ed25519 master identity key

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.

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.