update prebuilt docs

1 files changed, 354 insertions, 0 deletions

diff --git a/man/taler-auditor-offline.1 b/man/taler-auditor-offline.1
new file mode 100644
index 00000000..9164a812
--- /dev/null
+++ b/man/taler-auditor-offline.1
@@ -0,0 +1,354 @@
+.\" Man page generated from reStructuredText.
+.
+.TH "TALER-AUDITOR-OFFLINE" "1" "Jan 21, 2021" "0.8pre0" "GNU Taler"
+.SH NAME
+taler-auditor-offline \- Taler auditor certifies that it audits a Taler exchange
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.SH SYNOPSIS
+.sp
+\fBtaler\-auditor\-offline\fP
+[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB––config=\fP‌\fIFILENAME\fP]
+[\fB\-h\fP\ |\ \fB––help\fP]
+[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB––loglevel=\fP‌\fILOGLEVEL\fP]
+[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB––logfile=\fP‌\fIFILENAME\fP]
+[\fB\-v\fP\ |\ \fB––version\fP]
+[subcommand …]
+.SH DESCRIPTION
+.sp
+\fBtaler\-auditor\-offline\fP is a command\-line tool to be used by an auditor to
+sign that he is aware of certain keys being used by a exchange. Using this
+signature, the auditor affirms that he will verify that the exchange is
+properly accounting for coins of those denominations.  The tool takes a list
+of subcommands as arguments which are then processed sequentially.
+.sp
+The tool includes two subcommands to interact \fIonline\fP with the exchange’s
+REST APIs.  The \fBdownload\fP subcommand downloads current public keys from the
+running exchange.  Note that this only includes keys that the exchange
+operator has previously validated using the \fBtaler\-exchange\-offline\fP tool.
+The resulting data serves as input to the \fBsign\fP and \fBshow\fP subcommands.
+.sp
+The \fBupload\fP subcommand uploads the signatures created with the private key to
+the exchange.  It handles the output of all subcommands (except \fBdownload\fP).
+The \fBdownload\fP and \fBupload\fP subcommands must naturally be run “online” and do not
+require access to the auditor’s private key, which should be kept offline.
+.sp
+All other subcommands are intended to be run “offline”. However, especially
+when testing, it is of course possible to run the subcommands online as well.
+Generally, subcommands read inputs (beyond command\-line arguments)
+from \fBstdin\fP\&. However, they may also consume outputs of previous
+subcommands.  The outputs of multiple subcommands are automatically combined,
+and if not consumed the final output is printed to \fBstdout\fP\&.
+.sp
+The general options for \fBtaler\-auditor\-offline\fP are:
+.INDENT 0.0
+.TP
+\fB\-c\fP \fIFILENAME\fP | \fB––config=\fP‌\fIFILENAME\fP
+Use the configuration and other resources for the merchant to operate
+from \fIFILENAME\fP\&.
+.TP
+\fB\-h\fP | \fB––help\fP
+Print short help on options.
+.TP
+\fB\-L\fP \fILOGLEVEL\fP | \fB––loglevel=\fP‌\fILOGLEVEL\fP
+Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP,
+\fBWARNING\fP, \fBERROR\fP\&.
+.TP
+\fB\-l\fP \fIFILENAME\fP | \fB––logfile=\fP‌\fIFILENAME\fP
+Send logging output to \fIFILENAME\fP\&.
+.TP
+\fB\-v\fP | \fB––version\fP
+Print version information.
+.UNINDENT
+.SH CONFIGURATION
+.sp
+The exchange and the \fBtaler\-auditor\-httpd\fP must both be provided with
+the auditor’s public key, such that they can validate messages signed
+by the auditor. To obtain the auditor’s public key, use:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ AUDITOR_PRIV_FILE=\(gataler\-config \-f \-c $CONF \-s AUDITOR \-o AUDITOR_PRIV_FILE\(ga
+$ gnunet\-ecc \-p $AUDITOR_PRIV_FILE
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Note that if the private key file does not yet exist, the above will fail.
+In this case, create the private key using:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ AUDITOR_PRIV_FILE=\(gataler\-config \-f \-c $CONF \-s AUDITOR \-o AUDITOR_PRIV_FILE\(ga
+$ AUDITOR_PRIV_DIR=\(gadirname $AUDITOR_PRIV_FILE\(ga
+$ mkdir \-p $AUDITOR_PRIV_DIR
+$ gnunet\-ecc \-g1 $AUDITOR_PRIV_FILE
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Relevant configuration options for \fBtaler\-auditor\-offline\fP are:
+.INDENT 0.0
+.IP \(bu 2
+\fB[auditor/AUDITOR_PRIV_FILE]\fP — where to store the private key
+.UNINDENT
+.SH SUBCOMMANDS
+.SS download
+.sp
+This subcommand must be run online. It downloads future signing and denomination
+keys with the associated meta data from the exchange and outputs the resulting
+JSON (for consumption by subsequent subcommands, or to \fBstdout\fP).
+.SS show
+.sp
+This subcommand outputs information about future signing and denomination keys for
+manual checking against the business\-approved fee structure, lifetimes and
+other parameters.
+.sp
+It consumes the output of the \fBdownload\fP subcommand, either from \fBstdin\fP or
+directly.
+.sp
+Its output always goes to \fBstdout\fP for human consumption (not in JSON).  It
+is usually a bad idea (but possible) to combine \fBshow\fP with other subcommands,
+except maybe for testing.
+.SS sign
+.sp
+This subcommand signs information about future signing and denomination keys.
+.sp
+It consumes the output of the \fBdownload\fP subcommand, either from \fBstdin\fP or
+directly.
+.sp
+It outputs the signatures over \fIall\fP denomination and signing keys
+present in the input, in a format suitable for the \fBupload\fP subcommand.
+.SS revoke\-denomination
+.sp
+This subcommand signs a revocation message for a denomination key.
+.sp
+The hash of the denomination public key must be given in the usual
+base32\-encoding as the first and only argument to the subcommand.
+.sp
+It outputs the signature affirming the revocation of the denomination key,
+in a format suitable for the \fBupload\fP subcommand.
+.SS revoke\-signkey
+.sp
+This subcommand signs a revocation message for an exchange online signing key.
+.sp
+The online signing public key must be given in the usual
+base32\-encoding as the first and only argument to the subcommand.
+.sp
+It outputs the signature affirming the revocation of the online signing key,
+in a format suitable for the \fBupload\fP subcommand.
+.SS enable\-auditor
+.sp
+This subcommand
+informs an exchange that an auditor is to be activated. Afterwards, the
+exchange will accept inputs from that auditor’s \fBtaler\-auditor\-offline\fP
+tool.  Note that the auditor also must add the exchange to the list of
+exchanges that it audits via \fBtaler\-auditor\-exchange\fP\&. Furthermore, the
+exchange’s database will need to be provided to the auditor.  This subcommand
+only informs the exchange about the auditor, but does not perform those
+additional mandatory steps for a working auditor.
+.sp
+The auditor’s public key must be given in the usual base32\-encoding as the
+first argument.
+.sp
+The auditor’s REST API base URL must be given as the second argument. The tool
+performs a minimal sanity check, namely that the URL begins with “http”
+(this also allows “https”), but as it runs offline does not perform any further
+validation!
+.sp
+The third argument must be a human\-readable name for the auditor. This may
+be shown to users and should identify the auditor’s business entity.  If
+the name includes spaces, the argument should be quoted.
+.sp
+The subcommand takes no inputs from \fBstdin\fP or other subcommands.
+.sp
+It outputs the signature affirming the addition of the auditor,
+in a format suitable for the \fBupload\fP subcommand.
+.SS disable\-auditor
+.sp
+This subcommand
+informs an exchange that an auditor is to be deactivated. Afterwards, the
+exchange will refuse inputs from that auditor’s \fBtaler\-auditor\-offline\fP
+tool.
+.sp
+The auditor’s public key must be given in the usual base32\-encoding as the
+first argument.
+.sp
+The subcommand takes no inputs from \fBstdin\fP or other subcommands.
+.sp
+It outputs the signature affirming the removal of the auditor,
+in a format suitable for the \fBupload\fP subcommand.
+.SS enable\-account
+.sp
+This subcommand
+informs an exchange that it should advertise a bank account as belonging to
+the exchange on its \fB/wire\fP endpoint.  Note that this does \fInot\fP ensure that
+the exchange will use this bank account for incoming or outgoing wire
+transfers! For this, the \fBtaler\-exchange\-transfer\fP and
+\fBtaler\-exchange\-wirewatch\fP tools must be configured.  Furthermore, the bank
+account information advertised could theoretically differ from that which
+these tool actually use, for example if the public bank account is only a
+front for the actual internal business acounts.
+.sp
+The \fBpayto://\fP URI (RFC 8905) of the exchange’s bank account must be given
+as the first argument to the subcommand.
+.sp
+The subcommand takes no inputs from \fBstdin\fP or other subcommands.
+.sp
+It outputs the signature affirming the addition of the wire account,
+in a format suitable for the \fBupload\fP subcommand.
+.SS disable\-account
+.sp
+This subcommand
+informs an exchange that it should stop advertising a bank account as
+belonging to the exchange on its \fB/wire\fP endpoint.
+.sp
+The \fBpayto://\fP URI (RFC 8905) of the exchange’s (former) bank account must be
+given as the first argument to the subcommand.
+.sp
+The subcommand takes no inputs from \fBstdin\fP or other subcommands.
+.sp
+It outputs the signature affirming the deletion of the wire account, in a
+format suitable for the \fBupload\fP subcommand.
+.SS wire\-fee
+.sp
+This subcommand informs an exchange about the desired wire fee (and closing fee)
+structure for particular wire method and a calendar year (!).  The tool does not
+permit changing wire fees during a calendar year. Also, once the wire fee has been
+set for a calendar year, it cannot be changed.
+.sp
+The subcommand takes the year, wire\-method (see RFC 8905, examples include
+\fBx\-taler\-bank\fP or \fBiban\fP), wire fee and closing fee as arguments.
+Instead of a year, the string \fBnow\fP can be given for the current year
+(this is mostly useful for test cases).  The wire\-method should follow the
+GANA registry as given in RFC 8905.  The fees must be given in the usual
+Taler format of \fBCURRENCY:NUMBER.FRACTION\fP\&.
+.sp
+The subcommand takes no inputs from \fBstdin\fP or other subcommands.
+.sp
+It outputs the signature affirming the wire fees, in a format suitable for the
+\fBupload\fP subcommand.
+.SS upload
+.sp
+This subcommand uploads outputs from other subcommands (except \fBdownload\fP and \fBshow\fP)
+to the exchange.  Note that it is possible that some uploads succeed, while others
+fail, as the operation is not atomic.
+.sp
+The subcommand takes no arguments and has no output.
+.SS help
+.sp
+This subcommand shows a summary of all available subcommands with the
+required arguments.
+.SH EXAMPLES
+.SS Download public keys from an exchange (online)
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ taler\-auditor\-offline download > keys.json
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Show information about public keys (offline or online)
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ taler\-auditor\-offline show < keys.json
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Sign public keys (offline)
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ taler\-auditor\-offline sign < keys.json > sigs.json
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Upload auditor signatures (online)
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ taler\-auditor\-offline upload < sigs.json
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Download, sign and upload, all in one (online)
+.sp
+Note that doing this is only recommended in non\-production deployments.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ taler\-auditor\-offline download sign upload
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH SECURITY CONSIDERATIONS
+.sp
+The \fBtaler\-auditor\-offline\fP tool assumes that it is run on a high\-security
+system, especially for the \fBsign\fP subcommand.
+.sp
+The auditor should first use the \fBshow\fP subcommand on the offline system to
+check that the keys being signed are acceptable. This process requires
+manual work: the auditor should check with the exchange operator that
+the keys (and meta data) matches that previously seen by the
+exchange operator when they used the \fBtaler\-exchange\-offline\fP tool.
+.SH SEE ALSO
+.sp
+gnunet\-ecc(1), taler\-auditor\-exchange(1), taler\-exchange\-offline(1),
+taler.conf(5)
+.SH BUGS
+.sp
+Report bugs by using \fI\%https://bugs.taler.net/\fP or by sending electronic
+mail to <\fI\%taler@gnu.org\fP>.
+.SH AUTHOR
+GNU Taler contributors
+.SH COPYRIGHT
+2014-2020 Taler Systems SA (GPLv3+ or GFDL 1.3+)
+.\" Generated by docutils manpage writer.
+.