[tor-dev] documentation for new offline master key functionality (--keygen is undocumented)

[s7r]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256


On 11/13/2015 8:51 PM, nusenu wrote:
> Hi,
> 
> since tor 0.2.7.5 is apparently not very far [1] from being
> released I was wondering whether there is any documentation about
> the new offline master key functionality? (or is this undocumented
> because it is not considered for general use yet?)
> 
> tor v0.2.7.4-rc's manual has the following:
> 
> " SigningKeyLifetime N days|weeks|months
> 
> For how long should each Ed25519 signing key be valid? Tor uses a 
> permanent master identity key that can be kept offline, and
> periodically generates new "signing" keys that it uses online. This
> option configures their lifetime. (Default: 30 days)
> 
> OfflineMasterKey 0|1
> 
> If non-zero, the Tor relay will never generate or load its master 
> secret key. Instead, you’ll have to use "tor --keygen" to manage
> the master secret key. (Default: 0) "
> 
> but doesn't say anything about --keygen itself [2].
> 
> The 0.2.7.x mentions also a '--newpass' option that I wasn't able
> to find in the manpage:
> 
> " - Add a new OfflineMasterKey option to tell Tor never to try
> loading or generating a secret Ed25519 identity key. You can use
> this in combination with tor --keygen to manage offline and/or
> encrypted Ed25519 keys. Implements ticket 16944. - Add a --newpass
> option to allow changing or removing the passphrase of an encrypted
> key with tor --keygen. Implements part of ticket 16769. - On
> receiving a HUP signal, check to see whether the Ed25519 signing
> key has changed, and reload it if so. Closes ticket 16790. "
> 
> Can a tor operator use one offline master key for several relays
> (that are running at the same time) or is one master key required
> for every relay? (I assume the latter)
> 
No. One unique master identity key per relay is required.

> How does the process of renewing the signing keys look like?
> 
> According to the logs I assume simple run tor --keygen again and
> copy ed25519_signing_cert + ed25519_signing_secret_key to the 
> relay's /keys folder
> 
> the logs say: "It looks like I need to generate and sign a new 
> medium-term signing key, because you asked me to make one with
> --keygen. To do that, I need to load the permanent master identity
> key."
> 
For renewing the medium term signing key and certificate, you need to
have the master identity key accessible (either encrypted or
unencrypted) and do:

$ tor --datadirectory /path/to/master_id_key --keygen

Tor will ask for the passphrase if the master id key is encrypted or
just create the medium term signing key and certificate if it is not
encrypted.

The above command will create the medium term signing key valid for
the default lifetime of SigningKeyLifetime which is 30 days. If you
want to specify a different lifetime you need to do:

$ tor --datadirectory /path/to/master_id_key --signingkeylifetime 'n
days | weeks | months' --keygen


This requires the user running the commands to have write access in
the directory where the master id key is, because the medium term
signing key and certificate will be saved there. This is why we need
the --master-key and --out arguments so we can use them in situations
where the master id key is kept on a non-writeable media and tor
should read from one place and write to another.

- --newpass is currently working and is intended to allow operators to
encrypt/decrypt or change the passphrase of the master id key. If you
want to encrypt, enter a passphrase and confirm it; if you want to
decrypt, enter the current passphrase and NO new passphrase when asked.

> Does a tor operator has to SIGHUP a running tor instance after
> copying the new signing keys to the appropriate folder or will tor
> attempt to reload that file as soon as this signing key expires?
> 
Yes.

> How can a tor relay op display a given signing key's expiry date?
> 
I don't think there is an option for this.

> Does using the offline master key functionality imply that the
> relay will only have an ed25519 and no RSA key?
> 
For now, no, an online RSA key is needed otherwise the relay can't be
part of the consensus. In time, when enough relays upgrade, RSA
identity keys will be removed entirely.

> Is the offline master key limited to ed25519 keys and useless
> while using ed25519 + RSA keys at the same time? (because the RSA
> key is not offline?)
> 
Hmmm. Probably yes. Until transition (until we remove permanently RSA
identities) only the ed25519 key will be protected, RSA key will have
to be online. Even in this case, directory authorities remember relays
by their ed25519 + RSA pair of identities. If just one of them
changes, that relay will be rejected.

So if a relay that has the ed25519 identity offline has been
compromised, the operator cannot reuse the ed25519 identity even this
one is still considered safe. If the same ed25519 identity will appear
again with a different RSA identity pair, it'll be rejected.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (MingW32)

iQEcBAEBCAAGBQJWSKbLAAoJEIN/pSyBJlsRl7IH/1s8r/pdEtnkb3DPk303rgLI
8PyrhpVk0T60cdqIN0DK3ovNdmWZXae0LpAA/mFXRvdvxTyBCEP4OmFawA0qaUfJ
9RnUg5+/vTMiyiRwExxfRyqBrCsUZm/DUSVwl4gCcyygHss7xG/qhk6cOOrIXdk+
qY0KmtFtc8ZxrK/ri3AYm7wSU7JDBjLH6zUu/5rdGQaiwRkMd8iUinzQsfU3mYyG
O86xbcKSTYQ63gOF827sBZp0wnbXaGEcfu6juDUsrSuTuC016aBScdBfaAWZPTIL
cHiyXaiUTgyLj8xqT1q08YWqf13M1GG3xoziqiXMuONWfzmd3v+OCH44K3ZJirM=
=kj3S
-----END PGP SIGNATURE-----