From 57d1f08dbca256f5fe16d57b29bfa523dec8f6c4 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 8 Jan 2015 18:37:20 +0100 Subject: -initial import for mint --- src/include/taler_mint_service.h | 303 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 303 insertions(+) create mode 100644 src/include/taler_mint_service.h (limited to 'src/include/taler_mint_service.h') diff --git a/src/include/taler_mint_service.h b/src/include/taler_mint_service.h new file mode 100644 index 000000000..ee3b30e39 --- /dev/null +++ b/src/include/taler_mint_service.h @@ -0,0 +1,303 @@ +/* + This file is part of TALER + (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 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 General Public License for more details. + + You should have received a copy of the GNU General Public License along with + TALER; see the file COPYING. If not, If not, see +*/ + +/** + * @file include/taler_mint_service.h + * @brief C interface to the mint's HTTP API + * @author Sree Harsha Totakura + */ + +#ifndef _TALER_MINT_SERVICE_H +#define _TALER_MINT_SERVICE_H + +#include "taler_rsa.h" +#include "taler_util.h" +#include + +/** + * 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 TALER_RSA_PublicKeyBinaryEncoded 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 (); + + +/** + * 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 cls closure for the above callback + * @param cont_cb the callback to call after completing this asynchronous call + * @param cont_cls the closure for the continuation 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 *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 */ -- cgit v1.2.3