diff --git a/src/auditor-lib/auditor_api_handle.c b/src/auditor-lib/auditor_api_handle.c index 4db528a31..9e4f73486 100644 --- a/src/auditor-lib/auditor_api_handle.c +++ b/src/auditor-lib/auditor_api_handle.c @@ -483,7 +483,7 @@ MAH_path_to_url2 (const char *base_url, struct TALER_AUDITOR_Handle * TALER_AUDITOR_connect (struct GNUNET_CURL_Context *ctx, const char *url, - TALER_AUDITOR_VersionificationCallback version_cb, + TALER_AUDITOR_VersionCallback version_cb, void *version_cb_cls) { struct TALER_AUDITOR_Handle *auditor; diff --git a/src/include/Makefile.am b/src/include/Makefile.am index 2916a812c..d06d0064a 100644 --- a/src/include/Makefile.am +++ b/src/include/Makefile.am @@ -12,6 +12,7 @@ else talerinclude_HEADERS = \ platform.h \ + taler_auditor_service.h \ taler_amount_lib.h \ taler_auditordb_lib.h \ taler_auditordb_plugin.h \ diff --git a/src/include/taler_auditor_service.h b/src/include/taler_auditor_service.h new file mode 100644 index 000000000..a26ecb6f7 --- /dev/null +++ b/src/include/taler_auditor_service.h @@ -0,0 +1,159 @@ +/* + This file is part of TALER + Copyright (C) 2014-2018 Taler Systems SA + + 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, see +*/ +/** + * @file include/taler_auditor_service.h + * @brief C interface of libtalerauditor, a C library to use auditor's HTTP API + * @author Sree Harsha Totakura + * @author Christian Grothoff + */ +#ifndef _TALER_AUDITOR_SERVICE_H +#define _TALER_AUDITOR_SERVICE_H + +#include +#include "taler_util.h" +#include "taler_error_codes.h" +#include + + +/* ********************* /version *********************** */ + +/** + * @brief Information we get from the auditor about auditors. + */ +struct TALER_AUDITOR_VersionInformation +{ + /** + * Public key of the auditing institution. Wallets and merchants + * are expected to be configured with a set of public keys of + * auditors that they deem acceptable. These public keys are + * the roots of the Taler PKI. + */ + struct TALER_AuditorPublicKeyP auditor_pub; + + /** + * Supported Taler protocol version by the auditor. + * String in the format current:revision:age using the + * semantics of GNU libtool. See + * https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning + */ + char *version; + +}; + + +/** + * How compatible are the protocol version of the auditor and this + * client? The bits (1,2,4) can be used to test if the auditor's + * version is incompatible, older or newer respectively. + */ +enum TALER_AUDITOR_VersionCompatibility +{ + + /** + * The auditor runs exactly the same protocol version. + */ + TALER_AUDITOR_VC_MATCH = 0, + + /** + * The auditor is too old or too new to be compatible with this + * implementation (bit) + */ + TALER_AUDITOR_VC_INCOMPATIBLE = 1, + + /** + * The auditor is older than this implementation (bit) + */ + TALER_AUDITOR_VC_OLDER = 2, + + /** + * The auditor is too old to be compatible with + * this implementation. + */ + TALER_AUDITOR_VC_INCOMPATIBLE_OUTDATED + = TALER_AUDITOR_VC_INCOMPATIBLE + | TALER_AUDITOR_VC_OLDER, + + /** + * The auditor is more recent than this implementation (bit). + */ + TALER_AUDITOR_VC_NEWER = 4, + + /** + * The auditor is too recent for this implementation. + */ + TALER_AUDITOR_VC_INCOMPATIBLE_NEWER + = TALER_AUDITOR_VC_INCOMPATIBLE + | TALER_AUDITOR_VC_NEWER, + + /** + * We could not even parse the version data. + */ + TALER_AUDITOR_VC_PROTOCOL_ERROR = 8 + +}; + + +/** + * Function called with information about the auditor. + * + * @param cls closure + * @param vi basic information about the auditor + * @param compat protocol compatibility information + */ +typedef void +(*TALER_AUDITOR_VersionCallback) (void *cls, + const struct TALER_AUDITOR_VersionInformation *vi, + enum TALER_AUDITOR_VersionCompatibility compat); + + +/** + * @brief Handle to the auditor. This is where we interact with + * a particular auditor and keep the per-auditor information. + */ +struct TALER_AUDITOR_Handle; + + +/** + * Initialise a connection to the auditor. Will connect to the + * auditor and obtain information about the auditor's master public + * key and the auditor's auditor. The respective information will + * be passed to the @a version_cb once available, and all future + * interactions with the auditor will be checked to be signed + * (where appropriate) by the respective master key. + * + * @param ctx the context + * @param url HTTP base URL for the auditor + * @param version_cb function to call with the auditor's versionification information + * @param version_cb_cls closure for @a version_cb + * @return the auditor handle; NULL upon error + */ +struct TALER_AUDITOR_Handle * +TALER_AUDITOR_connect (struct GNUNET_CURL_Context *ctx, + const char *url, + TALER_AUDITOR_VersionCallback version_cb, + void *version_cb_cls); + + +/** + * Disconnect from the auditor. + * + * @param auditor the auditor handle + */ +void +TALER_AUDITOR_disconnect (struct TALER_AUDITOR_Handle *auditor); + + +#endif /* _TALER_AUDITOR_SERVICE_H */