[or-cvs] r13091: Add a manual page for tor-gencert. Also implement the missin (in tor/trunk: . doc src/tools)

Thu Jan 10 17:08:06 UTC 2008

Author: nickm
Date: 2008-01-10 12:08:05 -0500 (Thu, 10 Jan 2008)
New Revision: 13091

Added:
   tor/trunk/doc/tor-gencert.1
Modified:
   tor/trunk/
   tor/trunk/ChangeLog
   tor/trunk/doc/Makefile.am
   tor/trunk/doc/TODO
   tor/trunk/src/tools/tor-gencert.c
Log:
 r17550 at catbus:  nickm | 2008-01-10 12:08:01 -0500
 Add a manual page for tor-gencert.  Also implement the missing -s option in tor-gencert, and fix the info message for when no cert file is specified.



Property changes on: tor/trunk
___________________________________________________________________
 svk:merge ticket from /tor/trunk [r17550] on 8246c3cf-6607-4228-993b-4d95d33730f1

Modified: tor/trunk/ChangeLog
===================================================================

--- tor/trunk/ChangeLog	2008-01-10 16:08:47 UTC (rev 13090)
+++ tor/trunk/ChangeLog	2008-01-10 17:08:05 UTC (rev 13091)
@@ -50,6 +50,8 @@
     - New configuration options to override default maximum number of
       servers allowed on a single IP address.  This is important
       for running a test network on a single host.
+    - Actually implement the -s option to tor-gencert.
+    - Add a manual page for tor-gencert.
 
   o Minor features (other):
     - Add hidden services and DNSPorts to the list of things that make

Modified: tor/trunk/doc/Makefile.am
===================================================================
--- tor/trunk/doc/Makefile.am	2008-01-10 16:08:47 UTC (rev 13090)
+++ tor/trunk/doc/Makefile.am	2008-01-10 17:08:05 UTC (rev 13091)
@@ -4,7 +4,7 @@
              tor-osx-dmg-creation.txt tor-rpm-creation.txt   \
              tor-win32-mingw-creation.txt
 
-man_MANS = tor.1 tor-resolve.1
+man_MANS = tor.1 tor-resolve.1 tor-gencert.1
 
 SUBDIRS = design-paper spec
 

Modified: tor/trunk/doc/TODO
===================================================================
--- tor/trunk/doc/TODO	2008-01-10 16:08:47 UTC (rev 13090)
+++ tor/trunk/doc/TODO	2008-01-10 17:08:05 UTC (rev 13091)
@@ -32,7 +32,7 @@
       dir-connection-is-encrypted.
     - set up a filter to not answer any bridge descriptors on a
       non-encrypted request
-N - write a tor-gencert man page
+  o write a tor-gencert man page
 
   . geoip caching and publishing for bridges
     d Track consecutive time up, not time since last-forgotten IP.

Added: tor/trunk/doc/tor-gencert.1
===================================================================
--- tor/trunk/doc/tor-gencert.1	                        (rev 0)
+++ tor/trunk/doc/tor-gencert.1	2008-01-10 17:08:05 UTC (rev 13091)
@@ -0,0 +1,81 @@
+.TH tor-gencert 1 "" Jan-2008 ""
+.\" manual page by Nick Mathewson
+.SH NAME
+.LP
+tor-gencert \- Generate certs and keys for Tor directory authorities
+
+.SH SYNOPSIS
+\fBtor-gencert\fP\ [-h|--help] [-v] [-r|--reuse] [--create-identity-key] [-i \fIid_file\fP] [-c \fIcert_file\fP] [-m \fInum\fP] [-a \fIaddress\fP:\fIport\fP]
+
+.SH DESCRIPTION
+\fBtor-gencert\fR generates certificates and private keys for use by Tor
+directory authorities running the v3 Tor directory protocol, as used by Tor
+0.2.0 and later.  If you are not running a directory authority, you don't
+need to use tor-gencert.
+.PP
+Every directory authority has a long term authority \fIidentity key\fP (which
+is distinct from the identity key it uses as a Tor server); this key should
+be kept offline in a secure location.  It is used to certify shorter-lived
+\fIsigning keys\fP, which are kept online and used by the directory authority
+to sign votes and consensus documents.
+.PP
+After you use this program to generate a signing key and a certificate, copy
+those files to the keys subdirectory of your Tor process, and send Tor a
+SIGHUP signal. DO NOT COPY THE IDENTITY KEY.
+
+.SH OPTIONS
+\fB-v\fP
+Display verbose output.
+.LP
+.TP
+\fB-h\fP or \fB--help\fP
+Display help text and exit.
+.LP
+.TP
+\fB-r\fP or \fB--reuse\fP
+Generate a new certificate, but not a new signing key.  This can be
+used to change the address or lifetime associated with a given key.
+.LP
+.TP
+\fB--create-identity-key\fP
+Generate a new identity key.  You should only use this option the first
+time you run tor-gencert; in the future, you should use the identity
+key that's already there.
+.LP
+.TP
+\fB-i \fR\fIFILENAME\fP
+Read the identity key from the specified file.  If the file is not present
+and --create-identity-key is provided, create the identity key in the
+specified file.  Default: "./authority_identity_key"
+.LP
+.TP
+\fB-s \fR\fIFILENAME\fP
+Write the signing key to the specified file.  Default:
+"./authority_signing_key"
+.LP
+.TP
+\fB-c \fR\fIFILENAME\fP
+Write the certificate to the specified file.
+Default: "./authority_certificate"
+.LP
+.TP
+\fB-m \fR\fINUM\fP
+Number of months that the certificate should be valid.  Default: 12.
+.LP
+.TP
+\fB-a \fR\fIaddress\fR:\fIport\fP
+If provided, advertise the address:port combination as this authority's
+preferred directory port in its certificate.  If the address is a hostname,
+the hostname is resolved to an IP before it's published.
+
+.SH BUGS
+This probably doesn't run on Windows.  That's not a big issue, since we
+don't really want authorities to be running on Windows anyway.
+
+.SH SEE ALSO
+.BR tor (1)
+.PP
+See also the "dir-spec.txt" file, distributed with Tor.
+
+.SH AUTHORS
+Roger Dingledine <arma at mit.edu>, Nick Mathewson <nickm at alum.mit.edu>.

Modified: tor/trunk/src/tools/tor-gencert.c
===================================================================
--- tor/trunk/src/tools/tor-gencert.c	2008-01-10 16:08:47 UTC (rev 13090)
+++ tor/trunk/src/tools/tor-gencert.c	2008-01-10 17:08:05 UTC (rev 13091)
@@ -96,6 +96,12 @@
         return 1;
       }
       identity_key_file = tor_strdup(argv[++i]);
+    } else if (!strcmp(argv[i], "-s")) {
+      if (i+1>=argc) {
+        fprintf(stderr, "No argument to -s\n");
+        return 1;
+      }
+      signing_key_file = tor_strdup(argv[++i]);
     } else if (!strcmp(argv[i], "-c")) {
       if (i+1>=argc) {
         fprintf(stderr, "No argument to -c\n");
@@ -158,7 +164,7 @@
   if (!certificate_file) {
     certificate_file = tor_strdup("./authority_certificate");
     log_info(LD_GENERAL, "No signing key file given; defaulting to %s",
-             signing_key_file);
+             certificate_file);
   }
   return 0;
 }

