aboutsummaryrefslogtreecommitdiff
path: root/src/include/taler_mint_service.h
blob: f300a5cfb8539f9f9006132e01bd78e1f0319e9b (plain)
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
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
/*
  This file is part of TALER
  Copyright (C) 2014 Christian Grothoff (and other contributing authors)

  TALER is free software; you can redistribute it and/or modify it under the
  terms of the GNU Affero General Public License as published by the Free Software
  Foundation; either version 3, or (at your option) any later version.

  TALER is distributed in the hope that it will be useful, but WITHOUT ANY
  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.

  You should have received a copy of the GNU Affero General Public License along with
  TALER; see the file COPYING.  If not, If not, see <http://www.gnu.org/licenses/>
*/
/**
 * @file include/taler_mint_service.h
 * @brief C interface of libtalermint, a C library to use mint's HTTP API
 * @author Sree Harsha Totakura <sreeharsha@totakura.in>
 */
#ifndef _TALER_MINT_SERVICE_H
#define _TALER_MINT_SERVICE_H

#include "taler_util.h"
#include <jansson.h>

/**
 * Handle to this library context
 */
struct TALER_MINT_Context;

/**
 * Handle to the mint
 */
struct TALER_MINT_Handle;

/**
 * Mint's signature key
 */
struct TALER_MINT_SigningPublicKey
{
  /**
   * The signing public key
   */
  struct GNUNET_CRYPTO_EddsaPublicKey key;

  /**
   * Validity start time
   */
  struct GNUNET_TIME_Absolute valid_from;

  /**
   * Validity expiration time
   */
  struct GNUNET_TIME_Absolute valid_until;
};


/**
 * Mint's denomination key
 */
struct TALER_MINT_DenomPublicKey
{
  /**
   * The public key
   */
  struct GNUNET_CRYPTO_rsa_PublicKey *key;

  /**
   * Timestamp indicating when the denomination key becomes valid
   */
  struct GNUNET_TIME_Absolute valid_from;

  /**
   * Timestamp indicating when the denomination key can’t be used anymore to
   * withdraw new coins.
   */
  struct GNUNET_TIME_Absolute withdraw_valid_until;

  /**
   * Timestamp indicating when coins of this denomination become invalid.
   */
  struct GNUNET_TIME_Absolute deposit_valid_until;

  /**
   * The value of this denomination
   */
  struct TALER_Amount value;

  /**
   * The applicable fee for withdrawing a coin of this denomination
   */
  struct TALER_Amount fee_withdraw;

  /**
   * The applicable fee to spend a coin of this denomination
   */
  struct TALER_Amount fee_deposit;

  /**
   *The applicable fee to refresh a coin of this denomination
   */
  struct TALER_Amount fee_refresh;
};


/**
 * Initialise a context.  A context should be used for each thread and should
 * not be shared among multiple threads.
 *
 * @return the context
 */
struct TALER_MINT_Context *
TALER_MINT_init (void);


/**
 * Cleanup library initialisation resources.  This function should be called
 * after using this library to cleanup the resources occupied during library's
 * initialisation.
 *
 * @param ctx the library context
 */
void
TALER_MINT_cleanup (struct TALER_MINT_Context *ctx);


/**
 * Initialise a connection to the mint.
 *
 * @param ctx the context
 * @param hostname the hostname of the mint
 * @param port the point where the mint's HTTP service is running.  If port is
 *             given as 0, ports 80 or 443 are chosen depending on @a url.
 * @param mint_key the public key of the mint.  This is used to verify the
 *                 responses of the mint.
 * @return the mint handle; NULL upon error
 */
struct TALER_MINT_Handle *
TALER_MINT_connect (struct TALER_MINT_Context *ctx,
                    const char *hostname,
                    uint16_t port,
                    struct GNUNET_CRYPTO_EddsaPublicKey *mint_key);

/**
 * Disconnect from the mint
 *
 * @param mint the mint handle
 */
void
TALER_MINT_disconnect (struct TALER_MINT_Handle *mint);


/**
 * A handle to get the keys of a mint
 */
struct TALER_MINT_KeysGetHandle;

/**
 * Functions of this type are called to signal completion of an asynchronous call.
 *
 * @param cls closure
 * @param emsg if the asynchronous call could not be completed due to an error,
 *        this parameter contains a human readable error message
 */
typedef void
(*TALER_MINT_ContinuationCallback) (void *cls,
                                    const char *emsg);

/**
 * Functions of this type are called to provide the retrieved signing and
 * denomination keys of the mint.  No TALER_MINT_*() functions should be called
 * in this callback.
 *
 * @param cls closure passed to TALER_MINT_keys_get()
 * @param sign_keys NULL-terminated array of pointers to the mint's signing
 *          keys.  NULL if no signing keys are retrieved.
 * @param denom_keys NULL-terminated array of pointers to the mint's
 *          denomination keys; will be NULL if no signing keys are retrieved.
 */
typedef void
(*TALER_MINT_KeysGetCallback) (void *cls,
                               struct TALER_MINT_SigningPublicKey **sign_keys,
                               struct TALER_MINT_DenomPublicKey **denom_keys);


/**
 * Get the signing and denomination key of the mint.
 *
 * @param mint handle to the mint
 * @param cb the callback to call with the keys
 * @param cb_cls closure for the @a cb callback
 * @param cont_cb the callback to call after completing this asynchronous call
 * @param cont_cls the closure for the @a cont_cb callback
 * @return a handle to this asynchronous call; NULL upon eror
 */
struct TALER_MINT_KeysGetHandle *
TALER_MINT_keys_get (struct TALER_MINT_Handle *mint,
                     TALER_MINT_KeysGetCallback cb,
                     void *cb_cls,
                     TALER_MINT_ContinuationCallback cont_cb,
                     void *cont_cls);


/**
 * Cancel the asynchronous call initiated by TALER_MINT_keys_get().  This should
 * not be called if either of the @a TALER_MINT_KeysGetCallback or @a
 * TALER_MINT_ContinuationCallback passed to TALER_MINT_keys_get() have been
 * called.
 *
 * @param get the handle for retrieving the keys
 */
void
TALER_MINT_keys_get_cancel (struct TALER_MINT_KeysGetHandle *get);


/**
 * A Deposit Handle
 */
struct TALER_MINT_DepositHandle;


/**
 * Callbacks of this type are used to serve the result of submitting a deposit
 * permission object to a mint
 *
 * @param cls closure
 * @param status 1 for successful deposit, 2 for retry, 0 for failure
 * @param obj the received JSON object; can be NULL if it cannot be constructed
 *        from the reply
 * @param emsg in case of unsuccessful deposit, this contains a human readable
 *        explanation.
 */
typedef void
(*TALER_MINT_DepositResultCallback) (void *cls,
                                     int status,
                                     json_t *obj,
                                     char *emsg);


/**
 * Submit a deposit permission to the mint and get the mint's response
 *
 * @param mint the mint handle
 * @param cb the callback to call when a reply for this request is available
 * @param cls closure for the above callback
 * @param deposit_obj the deposit permission received from the customer along
 *         with the wireformat JSON object
 * @return a handle for this request; NULL if the JSON object could not be
 *         parsed or is of incorrect format or any other error.  In this case,
 *         the callback is not called.
 */
struct TALER_MINT_DepositHandle *
TALER_MINT_deposit_submit_json (struct TALER_MINT_Handle *mint,
                                TALER_MINT_DepositResultCallback cb,
                                void *cls,
                                json_t *deposit_obj);


#if 0
/**
 * Submit a deposit permission to the mint and get the mint's response.
 *
 * @param mint the mint handle
 * @param cb the callback to call when a reply for this request is available
 * @param cls closure for the above callback
 * @param coin the public key of the coin
 * @param denom_key denomination key of the mint which is used to blind-sign the
 *         coin
 * @param ubsig the mint's unblinded signature
 * @param transaction_id transaction identifier
 * @param amount the amount to deposit
 * @param merchant_pub the public key of the merchant
 * @param h_contract hash of the contract
 * @param h_wire hash of the wire format used
 * @param csig signature of the coin over the transaction_id, amount,
 *         merchant_pub, h_contract and, h_wire
 * @param wire_obj the wireformat object corresponding to h_wire
 * @return a handle for this request
 */
struct TALER_MINT_DepositHandle *
TALER_MINT_deposit_submit_json_ (struct TALER_MINT_Handle *mint,
                                 TALER_MINT_DepositResultCallback *cb,
                                 void *cls,
                                 struct GNUNET_CRYPTO_EddsaPublicKey *coin_pub,
                                 struct TALER_BLIND_SigningPublicKey *denom_pub,
                                 struct TALER_BLIND_Signature *ubsig,
                                 uint64_t transaction_id,
                                 struct TALER_Amount *amount,
                                 struct GNUNET_CRYPTO_EddsaPublicKey *merchant_pub,
                                 struct GNUNET_HashCode *h_contract,
                                 struct GNUNET_HashCode *h_wire,
                                 struct GNUNET_CRYPTO_EddsaSignature *csig,
                                 json_t *wire_obj);
#endif


/**
 * Cancel a deposit permission request.  This function cannot be used on a
 * request handle if a response is already served for it.
 *
 * @param the deposit permission request handle
 */
void
TALER_MINT_deposit_submit_cancel (struct TALER_MINT_DepositHandle *deposit);

#endif  /* _TALER_MINT_SERVICE_H */