gits7r/ed25519-id-offline-keys-manual.txt

## ed25519-id-offline-keys-manual.txt
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. It is an undesired feature if you plan to run the relay unattended and will take the relay offline if you forget or are unable to renew the temporary signing key when 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.

1. 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


2. 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 teh 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'


3. 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/


4. 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/


5. Time to 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


6. 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/


7. Renewal of 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 Step 3 and move the temporary signing key and certificate to the DataDirectory/keys folder of your Tor daemon, after that Step 4 to fix permissions. Finally, to load the new keys, 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 Step 3 and move the temporary signing key and certificate to the DataDirectory/keys folder of your Tor daemon, after that Step 4 to fix permissions. Finally, to load the new keys, 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 Step 3 and moe the temporary signing key and certificate to the DataDirectory/keys folder of your Tor daemon, after that Step 4 to fix permissions. Finally, to load the new keys, restart or reload (SIGHUP) your Tor process.


8. Encrypting, decrypting or changing the passphrase of the ed25519 master identity key.
"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.
	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. It is an undesired feature if you plan to run the relay unattended and will take the relay offline if you forget or are unable to renew the temporary signing key when 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.

	1. 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


	2. 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 teh 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'


	3. 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/


	4. 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/


	5. Time to 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


	6. 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/


	7. Renewal of 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 Step 3 and move the temporary signing key and certificate to the DataDirectory/keys folder of your Tor daemon, after that Step 4 to fix permissions. Finally, to load the new keys, 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 Step 3 and move the temporary signing key and certificate to the DataDirectory/keys folder of your Tor daemon, after that Step 4 to fix permissions. Finally, to load the new keys, 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 Step 3 and moe the temporary signing key and certificate to the DataDirectory/keys folder of your Tor daemon, after that Step 4 to fix permissions. Finally, to load the new keys, restart or reload (SIGHUP) your Tor process.


	8. Encrypting, decrypting or changing the passphrase of the ed25519 master identity key.
	"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.