From 7bfaa9b5516f78f1c784ed0fc45fa3695e7bb8e5 Mon Sep 17 00:00:00 2001
From: Marcello Stanisci <marcello.stanisci@inria.fr>
Date: Wed, 17 May 2017 11:39:03 +0200
Subject: [PATCH] instructions for the auditor to sign the blob

---
 doc/manual/manual.texi | 61 ++++++++++++++++++++++++++++++++++++++----
 1 file changed, 56 insertions(+), 5 deletions(-)

diff --git a/doc/manual/manual.texi b/doc/manual/manual.texi
index df616185c..cf7da9660 100644
--- a/doc/manual/manual.texi
+++ b/doc/manual/manual.texi
@@ -32,11 +32,10 @@ Texts.  A copy of the license is included in the section entitled
 @c Titlepage
 @c
 @titlepage
-@title The GNU Taler merchant backend operator tutorial
+@title The GNU Taler exchange operator tutorial
 @subtitle Version @value{VERSION}
 @subtitle @value{UPDATED}
 @author Marcello Stanisci (@email{marcello.stanisci@@inria.fr})
-@author Christian Grothoff (@email{christian.grothoff@@inria.fr})
 @page
 @vskip 0pt plus 1filll
 @insertcopying
@@ -53,8 +52,8 @@ Texts.  A copy of the license is included in the section entitled
 
 @menu
 * Introduction::            Whom this manual is addressed to
-* Installation::            Installing the Merchant backend
-* Configuration::           How to set up the Merchant backend
+* Installation::            Installing the exchange
+* Configuration::           How to set up the exchange
 
 
 Appendices
@@ -199,12 +198,64 @@ If you did not specify a prefix, the exchange will install to
 @node Configuration
 @chapter How to configure the exchange
 
+@section The configuration file
 @cindex taler-config
 @cindex taler.conf
 The installation already provides reasonable defaults.  The file
 @code{$HOME/.config/taler.conf} is responsible of overriding defaults
 values, or add new ones.  The format of the configuration file is
-the well-known INI file format.
+the well-known INI file format.  Nonetheless, the exchange takes a
+@code{-c CONFIG} option that makes the file @code{CONFIG} ovveride
+the defaults.
+
+@cindex keys
+@cindex denomination keys
+@cindex auditor
+@section Configuring keys
+
+@subsection Denomination keys
+@c FIXME TBD - NOTE, docs.taler.net contains already some text on this
+
+@subsection Master key
+@c FIXME TBD - NOTE, docs.taler.net contains already some text on this
+
+@subsection Specifying auditors
+
+In order to "add" any auditor to the list of the auditors accepted by
+the exchange, it's required to (1) generate a cryptographic blob containing
+metadata about the denomination keys, (2) ask the auditor to sign this blob,
+and (3) copy the auditor signed blob to a exchange's dedicated directory.
+
+The following command accomplishes step (1).
+
+@example
+taler-exchange-keyup -o blob
+@end example
+
+In production, step (2) is accomplished thanks to each auditor providing a RESTful
+service that lets the exchange administrator upload the @code{blob} and get a signed
+version of it.
+
+Nonetheless, for testing purposes, the following command emulates a auditor's
+signature that a exchange administrator can run locally.
+
+@example
+taler-auditor-sign -m EXCHANGE_MASTER_PUB -r BLOB -u AUDITOR_URI -o OUTPUT_FILE
+@end example
+
+The shown arguments are all mandatory.
+
+@itemize
+@item @code{EXCHANGE_MASTER_PUB} the base32 Crockford-encoded exchange's master
+public key.  Tipically, this value lies in the configuration option
+@code{[exchange]/master_public_key}.
+@item @code{BLOB} the blob generated in step (1).
+@item @code{AUDITOR_URI} the URI that identifies the auditor.
+@item @code{OUTPUT_FILE} where on the disk the signed blob is to be saved.
+@end itemize
+
+@section Wire formats
+@c FIXME TBD - NOTE, docs.taler.net _might_ contain already some text on this
 
 
 @c **********************************************************