|
|
[[PageOutline]]
|
|
|
|
|
|
= Offline Relay Identity Keys =
|
|
|
# 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:
|
|
|
[https://www.torproject.org/docs/faq.html.en#UpgradeOrMove I want to upgrade/move my relay. How do I keep the same key?]
|
|
|
[https://www.torproject.org/docs/faq.html.en#OfflineED25519 How do offline ed25519 identity keys work? What do I need to know?]
|
|
|
[I want to upgrade/move my relay. How do I keep the same key?](https://www.torproject.org/docs/faq.html.en#UpgradeOrMove)
|
|
|
[How do offline ed25519 identity keys work? What do I need to know?](https://www.torproject.org/docs/faq.html.en#OfflineED25519)
|
|
|
|
|
|
= Configuration and Setup =
|
|
|
# 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 ==
|
|
|
```
|
|
|
## 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):
|
... | ... | @@ -26,125 +26,125 @@ Some options for locations of your master keys probably are (sorted from more se |
|
|
1. on the relay itself but secured with a passphrase
|
|
|
1. 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 ==
|
|
|
## 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)
|
|
|
`--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)
|
|
|
`--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 ==
|
|
|
## 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 ==
|
|
|
## 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)
|
|
|
`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 =
|
|
|
# Maintenance
|
|
|
|
|
|
== Renewing the Temporary Signing Key ==
|
|
|
## 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 ==
|
|
|
## 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.
|
|
|
`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):
|
|
|
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.
|
|
|
`--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:
|
... | ... | @@ -157,17 +157,15 @@ Common root-causes for problems are: |
|
|
Starting with Tor 0.3.2.1-alpha you can use the `--key-expiration` parameter to display the key expiration date.
|
|
|
|
|
|
To display the expiry date on systems before that Tor version, there is a minimal python script to show the expiry date:
|
|
|
{{{
|
|
|
#!python
|
|
|
```
|
|
|
import time
|
|
|
with open('ed25519_signing_cert', 'rb') as f:
|
|
|
x = f.read()
|
|
|
print time.ctime(int(x[35:38].encode('hex'), 16) * 3600)
|
|
|
}}}
|
|
|
```
|
|
|
|
|
|
In Python3 use somethign like
|
|
|
{{{
|
|
|
#!/usr/bin/env python3
|
|
|
```
|
|
|
|
|
|
import codecs
|
|
|
import time
|
... | ... | @@ -177,4 +175,4 @@ with open('/var/lib/tor/data/keys/ed25519_signing_cert', 'rb') as f: |
|
|
expire = int(codecs.encode(cert[35:38], 'hex'), 16) * 3600
|
|
|
now = time.time()
|
|
|
print(int(expire-now))
|
|
|
}}} |
|
|
``` |