diff options
| -rw-r--r-- | .gitignore | 4 | ||||
| -rw-r--r-- | doc/Makefile.am | 11 | ||||
| -rw-r--r-- | doc/tor-gencert.1 | 86 | ||||
| -rw-r--r-- | doc/tor-gencert.1.txt | 90 |
4 files changed, 103 insertions, 88 deletions
diff --git a/.gitignore b/.gitignore index 44e6bd0c4..37d87503c 100644 --- a/.gitignore +++ b/.gitignore @@ -93,6 +93,10 @@ /doc/Makefile.in /doc/tor.1 /doc/doxygen +/doc/tor-gencert.1 +/doc/tor-gencert.1.in +/doc/tor-gencert.html +/doc/tor-gencert.html.in # /doc/design-paper/ /doc/design-paper/Makefile diff --git a/doc/Makefile.am b/doc/Makefile.am index 2eae7a187..4810d2538 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -5,12 +5,12 @@ html_in = $(asciidoc_files:=.html.in) man_in = $(asciidoc_files:=.1.in) EXTRA_DIST = HACKING \ - tor-resolve.1 tor-gencert.1 \ + tor-resolve.1 \ $(html_in) $(man_in) $(asciidoc_files:=.1.txt) \ tor-osx-dmg-creation.txt tor-rpm-creation.txt \ tor-win32-mingw-creation.txt torify.1 -nodist_man_MANS = tor.1 tor-resolve.1 tor-gencert.1 torify.1 $(asciidoc_files:=.1) +nodist_man_MANS = tor.1 tor-resolve.1 torify.1 $(asciidoc_files:=.1) doc_DATA = $(asciidoc_files:=.html) @@ -25,12 +25,19 @@ DIST_SUBDIRS = design-paper spec $(html_in) : $(top_srcdir)/doc/asciidoc-helper.sh html @ASCIIDOC@ @SED@ $@ +tor-gencert.html.in : tor-gencert.1.txt + # Generate the manpage from asciidoc, but don't do # machine-specific replacements yet $(man_in) : $(top_srcdir)/doc/asciidoc-helper.sh man @A2X@ @SED@ $@ +tor-gencert.1.in : tor-gencert.1.txt + # use ../config.status to swap all machine-specific magic strings # in the asciidoc with their replacements. $(asciidoc_product) : ../config.status --file=$@; + +tor-gencert.1 : tor-gencert.1.in +tor-gencert.html : tor-gencert.html.in diff --git a/doc/tor-gencert.1 b/doc/tor-gencert.1 deleted file mode 100644 index 5bcb5f0c3..000000000 --- a/doc/tor-gencert.1 +++ /dev/null @@ -1,86 +0,0 @@ -.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--passphrase-fd \fR\fIFILEDES\fP -Filedescriptor to read the file descriptor from. Ends at the first -NUL or newline. Default: read from the terminal. -.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@mit.edu>, Nick Mathewson <nickm@alum.mit.edu>. diff --git a/doc/tor-gencert.1.txt b/doc/tor-gencert.1.txt new file mode 100644 index 000000000..2a2d1179c --- /dev/null +++ b/doc/tor-gencert.1.txt @@ -0,0 +1,90 @@ +// Copyright (c) The Tor Project, Inc. +// See LICENSE for licensing information +// This is an asciidoc file used to generate the manpage/html reference. +// Learn asciidoc on http://www.methods.co.nz/asciidoc/userguide.html +tor-gencert(1) +============== +Nick Mathewson + +NAME +---- +tor-gencert - Generate certs and keys for Tor directory authorities + +SYNOPSIS +-------- +**tor-gencert** [-h|--help] [-v] [-r|--reuse] [--create-identity-key] [-i __id_file__] [-c +__cert_file__] [-m __num__] [-a __address__:__port__] + +DESCRIPTION +----------- +**tor-gencert** 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. + + +Every directory authority has a long term authority __identity__ __key__ (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 __signing__ __keys__, which are kept online and used by the +directory authority to sign votes and consensus documents. + + +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. + +OPTIONS +------- +**-v**:: + Display verbose output. + +**-h** or **--help**:: + Display help text and exit. + +**-r** or **--reuse**:: + 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. + +**--create-identity-key**:: + 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. + +**-i** __FILENAME__:: + 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" + +**-s** __FILENAME__:: + Write the signing key to the specified file. Default: + "./authority_signing_key" + +**-c** __FILENAME__:: + Write the certificate to the specified file. Default: + "./authority_certificate" + +**-m** __NUM__:: + Number of months that the certificate should be valid. Default: 12. + +**--passphrase-fd** __FILEDES__:: + Filedescriptor to read the file descriptor from. Ends at the first NUL or + newline. Default: read from the terminal. + +**-a** __address__:__port__:: + 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. + +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. + +SEE ALSO +-------- +**tor**(1) + + +See also the "dir-spec.txt" file, distributed with Tor. + +AUTHORS +------- + Roger Dingledine <arma@mit.edu>, Nick Mathewson <nickm@alum.mit.edu>. |