From af4b7d040507a69614fdb526e098a9295acc6c1f Mon Sep 17 00:00:00 2001
From: Nick Mathewson <nickm@torproject.org>
Date: Wed, 11 May 2016 14:03:34 -0400
Subject: [PATCH] Document the contents of $datadir/keys

Ticket 17621.
---
 changes/doc17621 |  3 +++
 doc/tor.1.txt    | 55 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+)
 create mode 100644 changes/doc17621

diff --git a/changes/doc17621 b/changes/doc17621
new file mode 100644
index 0000000000..af61d81728
--- /dev/null
+++ b/changes/doc17621
@@ -0,0 +1,3 @@
+  o Documentation:
+    - Document the contents of the 'datadir/keys' subdirectory in the manual
+      page. Closes ticekt 17621.
diff --git a/doc/tor.1.txt b/doc/tor.1.txt
index 787223d701..5d85935727 100644
--- a/doc/tor.1.txt
+++ b/doc/tor.1.txt
@@ -2702,6 +2702,61 @@ __DataDirectory__**/lock**::
 __DataDirectory__**/keys/***::
     Only used by servers. Holds identity keys and onion keys.
 
+__DataDirectory__**/keys/authority_identity_key**::
+    A directory authority's master identity key, used to authenticate its
+    signing key. Tor doesn't use this while it's running. The tor-gencert
+    program uses this. If you're running an authority, you should keep this
+    key offline, and not actually put it here.
+
+__DataDirectory__**/keys/authority_certificate**::
+    A directory authority's certificate, which authenticates the authority's
+    current vote- and consensus-signing key using its master identity key.
+    Only directory authorities use this file.
+
+__DataDirectory__**/keys/authority_signing_key**::
+    A directory authority's signing key, used to sign votes and consensuses.
+    Only directory authorities use this file.  Corresponds to the
+    **authority_certificate** cert.
+
+__DataDirectory__**/keys/legacy_certificate**::
+    As authority_certificate: used only when V3AuthUseLegacyKey is set.
+    See documentation for V3AuthUseLegacyKey.
+
+__DataDirectory__**/keys/legacy_signing_key**::
+    As authority_signing_key: used only when V3AuthUseLegacyKey is set.
+    See documentation for V3AuthUseLegacyKey.
+
+__DataDirectory__**/keys/secret_id_key**::
+    A relay's RSA1024 permanent identity key, including private and public
+    components.  Used to sign router descriptors, and to sign other keys.
+
+__DataDirectory__**/keys/ed25519_master_id_public_key**::
+    The public part of a relay's Ed25519 permanent identity key.
+
+__DataDirectory__**/keys/ed25519_master_id_secret_key**::
+    The private part of a relay's Ed25519 permanent identity key.  This key
+    is used to sign the medium-term ed25519 signing key.  This file can be
+    kept offline, or kept encrypted. If so, Tor will not be able to generate
+    new signing keys itself; you'll need to use tor --keygen yourself to do
+    so.
+
+__DataDirectory__**/keys/ed25519_signing_secret_key**::
+    The private and public components of a relay's medium-term Ed25519 signing
+    key. This key is authenticated by the Ed25519 master key, in turn
+    authenticates other keys (and router descriptors).
+
+__DataDirectory__**/keys/ed25519_signing_cert**::
+    The certificate which authenticates "ed25519_signing_secret_key" as
+    having been signed by the Ed25519 master key.
+
+__DataDirectory__**/keys/secret_onion_key**::
+    A relay's RSA1024 short-term onion key. Used to decrypt old-style ("TAP")
+    circuit extension requests.
+
+__DataDirectory__**/keys/secret_onion_key_ntor**::
+    A relay's Curve25519 short-term onion key. Used to handle modern ("ntor")
+    circuit extension requests.
+
 __DataDirectory__**/fingerprint**::
     Only used by servers. Holds the fingerprint of the server's identity key.