summaryrefslogtreecommitdiff
path: root/src/include/taler_mint_service.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/include/taler_mint_service.h')
-rw-r--r--src/include/taler_mint_service.h263
1 files changed, 177 insertions, 86 deletions
diff --git a/src/include/taler_mint_service.h b/src/include/taler_mint_service.h
index 4fd9a281d..2f641241f 100644
--- a/src/include/taler_mint_service.h
+++ b/src/include/taler_mint_service.h
@@ -17,6 +17,7 @@
* @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>
+ * @author Christian Grothoff
*/
#ifndef _TALER_MINT_SERVICE_H
#define _TALER_MINT_SERVICE_H
@@ -24,14 +25,114 @@
#include "taler_util.h"
/**
- * @brief Handle to this library context
+ * @brief Handle to this library context. This is where the
+ * main event loop logic lives.
*/
struct TALER_MINT_Context;
+
/**
- * @brief Handle to the mint
+ * Initialise a context. A context should be used for each thread and should
+ * not be shared among multiple threads.
+ *
+ * @return the context, NULL on error (failure to initialize)
*/
-struct TALER_MINT_Handle;
+struct TALER_MINT_Context *
+TALER_MINT_init (void);
+
+
+/**
+ * Obtain the information for a select() call to wait until
+ * #TALER_MINT_perform() is ready again. Note that calling
+ * any other TALER_MINT-API may also imply that the library
+ * is again ready for #TALER_MINT_perform().
+ *
+ * Basically, a client should use this API to prepare for select(),
+ * then block on select(), then call #TALER_MINT_perform() and then
+ * start again until the work with the context is done.
+ *
+ * This function will NOT zero out the sets and assumes that @a max_fd
+ * and @a timeout are already set to minimal applicable values. It is
+ * safe to give this API FD-sets and @a max_fd and @a timeout that are
+ * already initialized to some other descriptors that need to go into
+ * the select() call.
+ *
+ * @param ctx context to get the event loop information for
+ * @param read_fd_set will be set for any pending read operations
+ * @param write_fd_set will be set for any pending write operations
+ * @param except_fd_set is here because curl_multi_fdset() has this argument
+ * @param max_fd set to the highest FD included in any set;
+ * if the existing sets have no FDs in it, the initial
+ * value should be "-1". (Note that `max_fd + 1` will need
+ * to be passed to select().)
+ * @param timeout set to the timeout in milliseconds (!); -1 means
+ * no timeout (NULL, blocking forever is OK), 0 means to
+ * proceed immediately with #TALER_MINT_perform().
+ */
+void
+TALER_MINT_get_select_info (struct TALER_MINT_Context *ctx,
+ fd_set *read_fd_set,
+ fd_set *write_fd_set,
+ fd_set *except_fd_set,
+ int *max_fd,
+ long *timeout);
+
+
+/**
+ * Run the main event loop for the Taler interaction.
+ *
+ * @param ctx the library context
+ */
+void
+TALER_MINT_perform (struct TALER_MINT_Context *ctx);
+
+
+/**
+ * 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_fini (struct TALER_MINT_Context *ctx);
+
+
+/**
+ * List of possible options to be passed to
+ * #TALER_MINT_connect().
+ */
+enum TALER_MINT_Option
+{
+ /**
+ * Terminator (end of option list).
+ */
+ TALER_MINT_OPTION_END = 0
+
+};
+
+
+/**
+ * Information we get from the mint about auditors.
+ */
+struct TALER_MINT_AuditorInformation
+{
+ /**
+ * Public key of the auditing institution.
+ */
+ struct TALER_AuditorPublicKeyP auditor_pub;
+
+ /**
+ * URL of the auditing institution. The application must check that
+ * this is an acceptable auditor for its purpose and also verify
+ * that the @a auditor_pub matches the auditor's public key given at
+ * that website. We expect that in practice software is going to
+ * often ship with an initial list of accepted auditors, just like
+ * browsers ship with a CA root store.
+ */
+ const char *auditor_url;
+};
+
/**
* @brief Mint's signature key
@@ -56,7 +157,7 @@ struct TALER_MINT_SigningPublicKey
/**
- * @brief Mint's denomination key
+ * @brief Public information about a mint's denomination key
*/
struct TALER_MINT_DenomPublicKey
{
@@ -104,115 +205,104 @@ struct TALER_MINT_DenomPublicKey
/**
- * Initialise a context. A context should be used for each thread and should
- * not be shared among multiple threads.
- *
- * @return the context
+ * Information about keys from the mint.
*/
-struct TALER_MINT_Context *
-TALER_MINT_init (void);
+struct TALER_MINT_Keys
+{
+ /**
+ * Long-term offline signing key of the mint.
+ */
+ struct TALER_MasterPublicKeyP master_pub;
-/**
- * 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);
+ /**
+ * Array of the mint's online signing keys.
+ */
+ struct TALER_MINT_SigningPublicKey *sign_keys;
+ /**
+ * Array of the mint's denomination keys.
+ */
+ struct TALER_MINT_DenomPublicKey *denom_keys;
-/**
- * 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 master_key the public master 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,
- const struct TALER_MasterPublicKeyP *master_key);
+ /**
+ * Array of the keys of the auditors of the mint.
+ */
+ struct TALER_AuditorPublicKeyP *auditors;
-/**
- * Disconnect from the mint
- *
- * @param mint the mint handle
- */
-void
-TALER_MINT_disconnect (struct TALER_MINT_Handle *mint);
+ /**
+ * Length of the @e sign_keys array.
+ */
+ unsigned int num_sign_keys;
+ /**
+ * Length of the @e denom_keys array.
+ */
+ unsigned int num_denom_keys;
+
+ /**
+ * Length of the @e auditors array.
+ */
+ unsigned int num_auditors;
+
+};
-/**
- * @brief A handle to get the keys of a mint
- */
-struct TALER_MINT_KeysGetHandle;
/**
- * @brief Functions of this type are called to signal completion of an asynchronous call.
+ * Function called with information about who is auditing
+ * a particular mint and what key the mint is using.
*
* @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
+ * @param keys information about the various keys used
+ * by the mint
*/
typedef void
-(*TALER_MINT_ContinuationCallback) (void *cls,
- const char *emsg);
+(*TALER_MINT_CertificationCallback) (void *cls,
+ const struct TALER_MINT_Keys *keys);
+
/**
- * @brief 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.
+ * @brief Handle to the mint. This is where we interact with
+ * a particular mint and keep the per-mint information.
*/
-typedef void
-(*TALER_MINT_KeysGetCallback) (void *cls,
- struct TALER_MINT_SigningPublicKey **sign_keys,
- struct TALER_MINT_DenomPublicKey **denom_keys);
+struct TALER_MINT_Handle;
/**
- * Get the signing and denomination key of the mint.
+ * Initialise a connection to the mint. Will connect to the
+ * mint and obtain information about the mint's master public
+ * key and the mint's auditor. The respective information will
+ * be passed to the @a cert_cb once available, and all future
+ * interactions with the mint will be checked to be signed
+ * (where appropriate) by the respective master key.
*
- * @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
+ * @param ctx the context
+ * @param url HTTP base URL for the mint
+ * @param cert_cb function to call with the mint's certification information
+ * @param cert_cb_cls closure for @a cert_cb
+ * @param ... list of additional arguments, terminated by #TALER_MINT_OPTION_END.
+ * @return the mint handle; NULL upon error
*/
-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);
+struct TALER_MINT_Handle *
+TALER_MINT_connect (struct TALER_MINT_Context *ctx,
+ const char *url,
+ TALER_MINT_CertificationCallback cert_cb,
+ void *cert_cb_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.
+ * Disconnect from the mint.
*
- * @param get the handle for retrieving the keys
+ * @param mint the mint handle
*/
void
-TALER_MINT_keys_get_cancel (struct TALER_MINT_KeysGetHandle *get);
+TALER_MINT_disconnect (struct TALER_MINT_Handle *mint);
+#if 0
+
+// FIXME: API below with json-crap is too low-level...
/**
* @brief A Deposit Handle
*/
@@ -221,7 +311,7 @@ struct TALER_MINT_DepositHandle;
/**
* Callbacks of this type are used to serve the result of submitting a deposit
- * permission object to a mint
+ * permission object to a mint.
*
* @param cls closure
* @param status 1 for successful deposit, 2 for retry, 0 for failure
@@ -256,7 +346,6 @@ TALER_MINT_deposit_submit_json (struct TALER_MINT_Handle *mint,
json_t *deposit_obj);
-#if 0
/**
* Submit a deposit permission to the mint and get the mint's response.
*
@@ -291,7 +380,6 @@ TALER_MINT_deposit_submit_json_ (struct TALER_MINT_Handle *mint,
const struct GNUNET_HashCode *h_wire,
const struct TALER_CoinSignature *csig,
json_t *wire_obj);
-#endif
/**
@@ -303,4 +391,7 @@ TALER_MINT_deposit_submit_json_ (struct TALER_MINT_Handle *mint,
void
TALER_MINT_deposit_submit_cancel (struct TALER_MINT_DepositHandle *deposit);
+#endif
+
+
#endif /* _TALER_MINT_SERVICE_H */