path: root/man/taler-auditor-offline.1

.\" Man page generated from reStructuredText.
.
.TH "TALER-AUDITOR-OFFLINE" "1" "Jul 06, 2022" "0.9" "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 an 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
$ taler\-auditor\-offline setup
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that if the private key file already exists, the above will simply output
the existing key.  Passing additional arguments after setup (including “\-“)
will cause the output to be encapsulated in JSON.
.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 setup
.sp
When run the first time, this subcommand sets up the offline private key and
outputs the resulting public key. Subsequent invocations will simply again
output the (same) public key (in the format usable for the exchange
configuration).
.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 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
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-2022 Taler Systems SA (GPLv3+ or GFDL 1.3+)
.\" Generated by docutils manpage writer.
.