1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
|
# Notes re: planchets and blinding
## `TALER_denom_blind()`
```
Blind coin for blind signing with @a dk using blinding secret @a coin_bks.
```
- `@param[out] c_hash resulting hashed coin`
- `@param[out] blinded_planchet planchet data to initialize`
## `TALER_planchet_prepare()`
Prepare a planchet for withdrawal. Creates and blinds a coin.
- calls `TALER_denom_blind()!`
- `@param[out] c_hash set to the hash of the public key of the coin (needed later)`
- `@param[out] pd set to the planchet detail for TALER_MERCHANT_tip_pickup() and other withdraw operations, pd->blinded_planchet.cipher will be set to cipher from @a dk`
## `TALER_coin_ev_hash`
Compute the hash of a blinded coin.
- `@param blinded_planchet blinded planchet`
- `@param denom_hash hash of the denomination publick key`
- `@param[out] bch where to write the hash, type struct TALER_BlindedCoinHashP`
**Where is this called!?**
```
taler-exchange-httpd_refreshes_reveal.c
605: TALER_coin_ev_hash (&rrc->blinded_planchet,
taler-exchange-httpd_recoup.c
290: TALER_coin_ev_hash (&blinded_planchet,
taler-exchange-httpd_withdraw.c
581: TALER_coin_ev_hash (&wc.blinded_planchet,
taler-exchange-httpd_age-withdraw_reveal.c
350: ret = TALER_coin_ev_hash (&detail.blinded_planchet,
taler-exchange-httpd_recoup-refresh.c
284: TALER_coin_ev_hash (&blinded_planchet,
taler-exchange-httpd_age-withdraw.c
279: ret = TALER_coin_ev_hash (&awc->coin_evs[c],
884: TALER_coin_ev_hash (&awc->coin_evs[i],
taler-exchange-httpd_batch-withdraw.c
832: TALER_coin_ev_hash (&pc->blinded_planchet,
```
## `TALER_coin_pub_hash`
Compute the hash of a coin.
- `@param coin_pub public key of the coin`
- `@param age_commitment_hash hash of the age commitment vector. NULL, if no age commitment was set`
- `@param[out] coin_h where to write the hash`
**Where is this called!?**
### In `lib/crypto.c`, function `TALER_test_coin_valid`.
```
Check if a coin is valid; that is, whether the denomination key
exists, is not expired, and the signature is correct.
@param coin_public_info the coin public info to check for validity
@param denom_pub denomination key, must match @a coin_public_info's `denom_pub_hash`
@return #GNUNET_YES if the coin is valid,
#GNUNET_NO if it is invalid
#GNUNET_SYSERR if an internal error occurred
```
It then calls `TALER_denom_pub_verify` on the result of `TALER_coin_pub_hash` and the signature
### In `util/denom.c`, function `TALER_denom_blind`
## `TALER_EXCHANGE_batch_withdraw` vs `TALER_EXCHANGE_batch_withdraw2`
### `TALER_EXCHANGE_batch_withdraw`
```
/**
* Withdraw multiple coins from the exchange using a /reserves/$RESERVE_PUB/batch-withdraw
* request. This API is typically used by a wallet to withdraw many coins from a
* reserve.
*
* Note that to ensure that no money is lost in case of hardware
* failures, the caller must have committed (most of) the arguments to
* disk before calling, and be ready to repeat the request with the
* same arguments in case of failures.
*
* @param curl_ctx The curl context to use
* @param exchange_url The base-URL of the exchange
* @param keys The /keys material from the exchange
* @param reserve_priv private key of the reserve to withdraw from
* @param wci_length number of entries in @a wcis
* @param wcis inputs that determine the planchets
* @param res_cb the callback to call when the final result for this request is available
* @param res_cb_cls closure for @a res_cb
* @return NULL
* if the inputs are invalid (i.e. denomination key not with this exchange).
* In this case, the callback is not called.
*/
struct TALER_EXCHANGE_BatchWithdrawHandle *
TALER_EXCHANGE_batch_withdraw (
struct GNUNET_CURL_Context *curl_ctx,
const char *exchange_url,
const struct TALER_EXCHANGE_Keys *keys,
const struct TALER_ReservePrivateKeyP *reserve_priv,
unsigned int wci_length,
const struct TALER_EXCHANGE_WithdrawCoinInput wcis[static wci_length],
TALER_EXCHANGE_BatchWithdrawCallback res_cb,
void *res_cb_cls);
```
### `TALER_EXCHANGE_batch_withdraw2`
```
/**
* Withdraw a coin from the exchange using a /reserves/$RESERVE_PUB/batch-withdraw
* request. This API is typically used by a merchant to withdraw a tip
* where the blinding factor is unknown to the merchant.
*
* Note that to ensure that no money is lost in case of hardware
* failures, the caller must have committed (most of) the arguments to
* disk before calling, and be ready to repeat the request with the
* same arguments in case of failures.
*
* @param curl_ctx The curl context to use
* @param exchange_url The base-URL of the exchange
* @param keys The /keys material from the exchange
* @param pds array of planchet details of the planchet to withdraw
* @param pds_length number of entries in the @a pds array
* @param reserve_priv private key of the reserve to withdraw from
* @param res_cb the callback to call when the final result for this request is available
* @param res_cb_cls closure for @a res_cb
* @return NULL
* if the inputs are invalid (i.e. denomination key not with this exchange).
* In this case, the callback is not called.
*/
struct TALER_EXCHANGE_BatchWithdraw2Handle *
TALER_EXCHANGE_batch_withdraw2 (
struct GNUNET_CURL_Context *curl_ctx,
const char *exchange_url,
const struct TALER_EXCHANGE_Keys *keys,
const struct TALER_ReservePrivateKeyP *reserve_priv,
unsigned int pds_length,
const struct TALER_PlanchetDetail pds[static pds_length],
TALER_EXCHANGE_BatchWithdraw2Callback res_cb,
void *res_cb_cls);
```
### Differences
| batch_withdraw | batch_withdraw2 |
|------------------------------------|------------------------|
| `TALER_EXCHANGE_WithdrawCoinInput` | `TALER_PlanchetDetail` |
```
struct TALER_EXCHANGE_WithdrawCoinInput
{
/**
* Denomination of the coin.
*/
const struct TALER_EXCHANGE_DenomPublicKey *pk;
/**
* Master key material for the coin.
*/
const struct TALER_PlanchetMasterSecretP *ps;
/**
* Age commitment for the coin.
*/
const struct TALER_AgeCommitmentHash *ach;
};
```
```
struct TALER_PlanchetDetail
{
/**
* Hash of the denomination public key.
*/
struct TALER_DenominationHashP denom_pub_hash;
/**
* The blinded planchet
*/
struct TALER_BlindedPlanchet {
/**
* Type of the sign blinded message
*/
enum TALER_DenominationCipher cipher;
/**
* Details, depending on @e cipher.
*/
union
{
/**
* If we use #TALER_DENOMINATION_CS in @a cipher.
*/
struct TALER_BlindedCsPlanchet cs_blinded_planchet;
/**
* If we use #TALER_DENOMINATION_RSA in @a cipher.
*/
struct TALER_BlindedRsaPlanchet rsa_blinded_planchet;
} details;
} blinded_planchet;
};
```
## TODOs
### Update documentation
- [x] batch-withdraw needs error code for AgeRestrictionRequired
- [x] withdraw needs error code for AgeRestrictionRequired
|
