taler-auditor-offline.1.rst (6467B)
1 taler-auditor-offline(1) 2 ######################## 3 4 .. only:: html 5 6 Name 7 ==== 8 9 **taler-auditor-offline** - operations using the auditor's private key 10 11 Synopsis 12 ======== 13 14 **taler-auditor-offline** 15 [**-c** *FILENAME* | **--config=**\ \ *FILENAME*] 16 [**-h** | **--help**] 17 [**-L** *LOGLEVEL* | **--loglevel=**\ \ *LOGLEVEL*] 18 [**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] 19 [**-v** | **--version**] 20 [subcommand ...] 21 22 23 Description 24 =========== 25 26 **taler-auditor-offline** is a command-line tool to be used by an auditor to 27 sign that he is aware of certain keys being used by an exchange. Using this 28 signature, the auditor affirms that he will verify that the exchange is 29 properly accounting for coins of those denominations. The tool takes a list 30 of subcommands as arguments which are then processed sequentially. 31 32 The tool includes two subcommands to interact *online* with the exchange's 33 REST APIs. The ``download`` subcommand downloads current public keys from the 34 running exchange. Note that this only includes keys that the exchange 35 operator has previously validated using the **taler-exchange-offline** tool. 36 The resulting data serves as input to the ``sign`` and ``show`` subcommands. 37 38 The ``upload`` subcommand uploads the signatures created with the private key to 39 the exchange. It handles the output of all subcommands (except ``download``). 40 The ``download`` and ``upload`` subcommands must naturally be run "online" and do not 41 require access to the auditor's private key, which should be kept offline. 42 43 All other subcommands are intended to be run "offline". However, especially 44 when testing, it is of course possible to run the subcommands online as well. 45 Generally, subcommands read inputs (beyond command-line arguments) 46 from ``stdin``. However, they may also consume outputs of previous 47 subcommands. The outputs of multiple subcommands are automatically combined, 48 and if not consumed the final output is printed to ``stdout``. 49 50 51 The general options for **taler-auditor-offline** are: 52 53 **-c** *FILENAME* \| **--config=**\ \ *FILENAME* 54 Use the configuration and other resources for the merchant to operate 55 from *FILENAME*. 56 57 **-h** \| **--help** 58 Print short help on options. 59 60 **-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* 61 Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, 62 ``WARNING``, ``ERROR``. 63 64 **-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* 65 Send logging output to *FILENAME*. 66 67 **-v** \| **--version** 68 Print version information. 69 70 71 72 73 Configuration 74 ============= 75 76 The exchange and the **taler-auditor-httpd** must both be provided with 77 the auditor's public key, such that they can validate messages signed 78 by the auditor. To obtain the auditor's public key, use: 79 80 .. code-block:: console 81 82 $ taler-auditor-offline setup 83 84 Note that if the private key file already exists, the above will simply output 85 the existing key. Passing additional arguments after setup (including "-") 86 will cause the output to be encapsulated in JSON. 87 88 Relevant configuration options for **taler-auditor-offline** are: 89 90 * ``[auditor/AUDITOR_PRIV_FILE]`` --- where to store the private key 91 92 93 94 Subcommands 95 =========== 96 97 setup 98 ----- 99 100 When run the first time, this subcommand sets up the offline private key and 101 outputs the resulting public key. Subsequent invocations will simply again 102 output the (same) public key (in the format usable for the exchange 103 configuration). 104 105 download 106 -------- 107 108 This subcommand must be run online. It downloads future signing and denomination 109 keys with the associated meta data from the exchange and outputs the resulting 110 JSON (for consumption by subsequent subcommands, or to ``stdout``). 111 112 113 show 114 ---- 115 116 This subcommand outputs information about future signing and denomination keys for 117 manual checking against the business-approved fee structure, lifetimes and 118 other parameters. 119 120 It consumes the output of the ``download`` subcommand, either from ``stdin`` or 121 directly. 122 123 Its output always goes to ``stdout`` for human consumption (not in JSON). It 124 is usually a bad idea (but possible) to combine ``show`` with other subcommands, 125 except maybe for testing. 126 127 128 sign 129 ---- 130 131 This subcommand signs information about future signing and denomination keys. 132 133 It consumes the output of the ``download`` subcommand, either from ``stdin`` or 134 directly. 135 136 It outputs the signatures over *all* denomination and signing keys 137 present in the input, in a format suitable for the ``upload`` subcommand. 138 139 140 upload 141 ------ 142 143 This subcommand uploads outputs from other subcommands (except ``download`` and ``show``) 144 to the exchange. Note that it is possible that some uploads succeed, while others 145 fail, as the operation is not atomic. 146 147 The subcommand takes no arguments and has no output. 148 149 150 help 151 ---- 152 153 This subcommand shows a summary of all available subcommands with the 154 required arguments. 155 156 157 158 Examples 159 ======== 160 161 Download public keys from an exchange (online) 162 ---------------------------------------------- 163 164 .. code-block:: console 165 166 $ taler-auditor-offline download > keys.json 167 168 Show information about public keys (offline or online) 169 ------------------------------------------------------ 170 171 .. code-block:: console 172 173 $ taler-auditor-offline show < keys.json 174 175 Sign public keys (offline) 176 -------------------------- 177 178 .. code-block:: console 179 180 $ taler-auditor-offline sign < keys.json > sigs.json 181 182 Upload auditor signatures (online) 183 ---------------------------------- 184 185 .. code-block:: console 186 187 $ taler-auditor-offline upload < sigs.json 188 189 Download, sign and upload, all in one (online) 190 ---------------------------------------------- 191 192 Note that doing this is only recommended in non-production deployments. 193 194 .. code-block:: console 195 196 $ taler-auditor-offline download sign upload 197 198 199 200 201 Security considerations 202 ======================= 203 204 The **taler-auditor-offline** tool assumes that it is run on a high-security 205 system, especially for the ``sign`` subcommand. 206 207 The auditor should first use the ``show`` subcommand on the offline system to 208 check that the keys being signed are acceptable. This process requires 209 manual work: the auditor should check with the exchange operator that 210 the keys (and meta data) matches that previously seen by the 211 exchange operator when they used the **taler-exchange-offline** tool. 212 213 214 See Also 215 ======== 216 217 taler-exchange-offline(1), taler-auditor.conf(5) 218 219 Bugs 220 ==== 221 222 Report bugs by using https://bugs.taler.net/ or by sending electronic 223 mail to <taler@gnu.org>.