sarah
/
tor
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Convert the tor-gencert manpage to asciidoc

This commit is contained in:
Sebastian Hahn 2010-01-18 08:42:48 +01:00
parent 9fe1c000b0
commit 2fc0c3031b
4 changed files with 103 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.gitignore vendored
View File

@ -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

11
doc/Makefile.am
View File

@ -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

86
doc/tor-gencert.1
View File

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

90
doc/tor-gencert.1.txt Normal file
View File

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