diff options
author | Christian Grothoff <christian@grothoff.org> | 2022-08-01 18:09:06 +0200 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2022-08-01 18:09:06 +0200 |
commit | 0835669986f11dfdbcae5b069990286ae8784f21 (patch) | |
tree | c3bb68cb19a6a83e3582a004c4eb45614e5a4e6b /src | |
parent | 9d2033872f7ed6dbeb5dfd84df2b4f4ad9983e39 (diff) | |
download | exchange-0835669986f11dfdbcae5b069990286ae8784f21.tar.xz |
-very basic skeleton for KYC API
Diffstat (limited to 'src')
-rw-r--r-- | src/exchange/taler-exchange-httpd.h | 7 | ||||
-rw-r--r-- | src/exchange/taler-exchange-httpd_kyc.c | 250 | ||||
-rw-r--r-- | src/exchange/taler-exchange-httpd_kyc.h | 220 | ||||
-rw-r--r-- | src/include/Makefile.am | 1 | ||||
-rw-r--r-- | src/include/taler_kyclogic_plugin.h | 125 |
5 files changed, 602 insertions, 1 deletions
diff --git a/src/exchange/taler-exchange-httpd.h b/src/exchange/taler-exchange-httpd.h index 278a05be9..0fda5ed8d 100644 --- a/src/exchange/taler-exchange-httpd.h +++ b/src/exchange/taler-exchange-httpd.h @@ -1,6 +1,6 @@ /* This file is part of TALER - Copyright (C) 2014, 2015, 2020 Taler Systems SA + Copyright (C) 2014-2022 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 @@ -26,10 +26,15 @@ #include <microhttpd.h> #include "taler_json_lib.h" #include "taler_crypto_lib.h" +#include "taler_kyclogic_plugin.h" #include "taler_extensions.h" #include <gnunet/gnunet_mhd_compat.h> +/* ************* NOTE: OLD KYC logic,*********** + new logic is in taler-exchange-httpd_kyc.h! + ********************************************* */ + /** * Enumeration for our KYC modes. */ diff --git a/src/exchange/taler-exchange-httpd_kyc.c b/src/exchange/taler-exchange-httpd_kyc.c new file mode 100644 index 000000000..dd5a334bd --- /dev/null +++ b/src/exchange/taler-exchange-httpd_kyc.c @@ -0,0 +1,250 @@ +/* + This file is part of TALER + Copyright (C) 2022 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 <http://www.gnu.org/licenses/> +*/ +/** + * @file taler-exchange-httpd_kyc.c + * @brief KYC API for the exchange + * @author Christian Grothoff + */ +#include "platform.h" +#include "taler-exchange-httpd_kyc.h" + +/** + * Information about a KYC provider. + */ +struct TEH_KycProvider; + + +/** + * Abstract representation of a KYC check. + */ +struct TEH_KycCheck +{ + /** + * Human-readable name given to the KYC check. + */ + char *name; + + /** + * Array of @e num_providers providers that offer this type of KYC check. + */ + struct TEH_KycProvider *providers; + + /** + * Length of the @e providers array. + */ + unsigned int num_providers; + +}; + + +struct TEH_KycProvider +{ + /** + * Name of the provider (configuration section name). + */ + const char *provider_section_name; + + /** + * Array of @e num_checks checks performed by this provider. + */ + struct TEH_KycCheck *provided_checks; + + /** + * Logic to run for this provider. + */ + struct TEH_KYCLOGIC_Plugin *logic; + + /** + * @e provider_section_name specific details to + * pass to the @e logic functions. + */ + struct TEH_KYCLOGIC_ProviderDetails *pd; + + /** + * Length of the @e checks array. + */ + unsigned int num_checks; + + /** + * Type of user this provider supports. + */ + enum TEH_KycUserType user_type; +}; + + +/** + * Condition that triggers a need to perform KYC. + */ +struct TEH_KycTrigger +{ + + /** + * Timeframe to consider for computing the amount + * to compare against the @e limit. Zero for the + * wallet balance trigger (as not applicable). + */ + struct GNUNET_TIME_Relative timeframe; + + /** + * Maximum amount that can be transacted until + * the rule triggers. + */ + struct TALER_Amount limit; + + /** + * Array of @e num_checks checks to apply on this trigger. + */ + struct TEH_KycCheck *required_checks; + + /** + * Length of the @e checks array. + */ + unsigned int num_checks; + + /** + * What event is this trigger for? + */ + enum TEH_KycTriggerEvent trigger; + +}; + + +/** + * Array of @e num_kyc_logics KYC logic plugins we have loaded. + */ +static struct TEH_KYCLOGIC_Plugin *kyc_logics; + +/** + * Length of the #kyc_logics array. + */ +static unsigned in num_kyc_logics; + +/** + * Array of @e num_kyc_checks known types of + * KYC checks. + */ +static struct TEH_KycCheck *kyc_checks; + +/** + * Length of the #kyc_checks array. + */ +static unsigned int num_kyc_checks; + +/** + * Array of configured triggers. + */ +static struct TEH_KycTrigger *kyc_triggers; + +/** + * Length of the #kyc_triggers array. + */ +static unsigned int num_kyc_triggers; + +/** + * Array of configured providers. + */ +static struct TEH_KycProviders *kyc_providers; + +/** + * Length of the #kyc_providers array. + */ +static unsigned int num_kyc_providers; + + +enum GNUNET_GenericReturnValue +TEH_kyc_trigger_from_string (const char *trigger_s, + enum TEH_KycTriggerEvent *trigger) +{ + GNUNET_break (0); + return GNUNET_SYSERR; +} + + +const char * +TEH_kyc_trigger2s (enum TEH_KycTriggerEvent trigger) +{ + GNUNET_break (0); + return NULL; +} + + +enum GNUNET_GenericReturnValue +TEH_kyc_user_type_from_string (const char *ut_s, + enum TEH_KycUserType *ut) +{ + GNUNET_break (0); + return GNUNET_SYSERR; +} + + +const char * +TEH_kyc_user_type2s (enum TEH_KycUserType ut) +{ + GNUNET_break (0); + return NULL; +} + + +enum GNUNET_GenericReturnValue +TEH_kyc_init (void) +{ + GNUNET_break (0); + // iterate over configuration sections, + // initialize arrays above + // sanity check: ensure at least one provider exists + // for any trigger and indidivual or business. + + return GNUNET_OK; +} + + +void +TEH_kyc_done (void) +{ + // unload plugins + // free arrays +} + + +const char * +TEH_kyc_test_required (enum TEH_KycTriggerEvent event, + const struct TALER_PaytoHashP *h_payto, + TEH_KycAmountIterator ai, + void *cls) +{ + // Check if event(s) may at all require KYC. + // If so, check what provider checks are + // already satisified for h_payto (with database) + // If unsatisfied checks are left, use 'ai' + // to check if amount is high enough to trigger them. + // If it is, find cheapest provider that satisfies + // all of them (or, if multiple providers would be + // needed, return one of them). + GNUNET_break (0); + return NULL; +} + + +enum GNUNET_GenericReturnValue +TEH_kyc_get_logic (const char *provider_section_name, + struct TEH_KYCLOGIC_Plugin **plugin, + struct TEH_KYCLOGIC_ProviderDetails **pd) +{ + // lookup provider by section name in array, + // return internal plugin/pd fields. + GNUNET_break (0); + return GNUNET_SYSERR; +} diff --git a/src/exchange/taler-exchange-httpd_kyc.h b/src/exchange/taler-exchange-httpd_kyc.h new file mode 100644 index 000000000..51883caca --- /dev/null +++ b/src/exchange/taler-exchange-httpd_kyc.h @@ -0,0 +1,220 @@ +/* + This file is part of TALER + Copyright (C) 2022 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 <http://www.gnu.org/licenses/> +*/ +/** + * @file taler-exchange-httpd_kyc.h + * @brief KYC API for the exchange + * @author Christian Grothoff + */ +#ifndef TALER_EXCHANGE_HTTPD_KYC_H +#define TALER_EXCHANGE_HTTPD_KYC_H + +#include <microhttpd.h> +#include "taler_kyclogic_plugin.h" + + +/** + * Enumeration for our KYC user types. + */ +enum TEH_KycUserType +{ + /** + * KYC rule is for an individual. + */ + TEH_KYC_INDIVIDUAL = 0, + + /** + * KYC rule is for a business. + */ + TEH_KYC_BUSINESS = 1 +}; + + +/** + * Enumeration of possible events that may trigger + * KYC requirements. + */ +enum TEH_KycTriggerEvent +{ + + /** + * Customer withdraws coins. + */ + TEH_KYC_TRIGGER_WITHDRAW = 0, + + /** + * Merchant deposits coins. + */ + TEH_KYC_TRIGGER_DEPOSIT = 1, + + /** + * Wallet receives P2P payment. + */ + TEH_KYC_TRIGGER_P2P_RECEIVE = 2, + + /** + * Wallet balance exceeds threshold. + */ + TEH_KYC_TRIGGER_WALLET_BALANCE = 3 + +}; + + +/** + * Parse KYC trigger string value from a string + * into enumeration value. + * + * @param trigger_s string to parse + * @param[out] trigger set to the value found + * @return #GNUNET_OK on success, #GNUNET_NO if option + * does not exist, #GNUNET_SYSERR if option is + * malformed + */ +enum GNUNET_GenericReturnValue +TEH_kyc_trigger_from_string (const char *trigger_s, + enum TEH_KycTriggerEvent *trigger); + + +/** + * Convert KYC trigger value to human-readable string. + * + * @param trigger value to convert + * @return human-readable representation of the @a trigger + */ +const char * +TEH_kyc_trigger2s (enum TEH_KycTriggerEvent trigger); + + +/** + * Parse user type string into enumeration value. + * + * @param ut_s string to parse + * @param[out] ut set to the value found + * @return #GNUNET_OK on success, #GNUNET_NO if option + * does not exist, #GNUNET_SYSERR if option is + * malformed + */ +enum GNUNET_GenericReturnValue +TEH_kyc_user_type_from_string (const char *ut_s, + enum TEH_KycUserType *ut); + + +/** + * Convert KYC user type to human-readable string. + * + * @param ut value to convert + * @return human-readable representation of the @a ut + */ +const char * +TEH_kyc_user_type2s (enum TEH_KycUserType ut); + + +/** + * Initialize KYC subsystem. Loads the KYC + * configuration. + * + * @return #GNUNET_OK on success + */ +enum GNUNET_GenericReturnValue +TEH_kyc_init (void); + + +/** + * Shut down the KYC subsystem. + */ +void +TEH_kyc_done (void); + + +/** + * Function called on each @a amount that was found to + * be relevant for a KYC check. + * + * @param cls closure to allow the KYC module to + * total up amounts and evaluate rules + * @param amount encountered transaction amount + * @param date when was the amount encountered + * @return #GNUNET_OK to continue to iterate, + * #GNUNET_NO to abort iteration + * #GNUNET_SYSERR on internal error (also abort itaration) + */ +enum GNUNET_GenericReturnValue +(*TEH_KycAmountCallback)(void *cls, + const struct TALER_Amount *amount, + struct GNUNET_TIME_Absolute date); + + +/** + * Function called to iterate over KYC-relevant + * transaction amounts for a particular time range. + * Called within a database transaction, so must + * not start a new one. + * + * @param cls closure, identifies the event type and + * account to iterate over events for + * @param limit maximum time-range for which events + * should be fetched (timestamp in the past) + * @param cb function to call on each event found, + * events must be returned in reverse chronological + * order + * @param cb_cls closure for @a cb + */ +void +(*TEH_KycAmountIterator)(void *cls, + struct GNUNET_TIME_Absolute limit, + TEH_KycAmountCallback cb, + void *cb_cls); + + +/** + * Check if KYC is provided for a particular operation. Returns the best + * provider (configuration section name) that could perform the required + * check. + * + * Called within a database transaction, so must + * not start a new one. + * + * @param event what type of operation is triggering the + * test if KYC is required + * @param h_payto account the event is about + * @param ai callback offered to inquire about historic + * amounts involved in this type of operation + * at the given account + * @param cls closure for @a pi and @a ai + * @return NULL if no check is needed + */ +const char * +TEH_kyc_test_required (enum TEH_KycTriggerEvent event, + const struct TALER_PaytoHashP *h_payto, + TEH_KycAmountIterator ai, + void *cls); + + +/** + * Obtain the provider logic for a given + * @a provider_section_name. + * + * @param provider_section_name identifies a KYC provider process + * @param[out] plugin set to the KYC logic API + * @param[out] pd set to the specific operation context + * @return #GNUNET_OK on success + */ +enum GNUNET_GenericReturnValue +TEH_kyc_get_logic (const char *provider_section_name, + struct TEH_KYCLOGIC_Plugin **plugin, + struct TEH_KYCLOGIC_ProviderDetails **pd); + + +#endif diff --git a/src/include/Makefile.am b/src/include/Makefile.am index 13b9a1444..f3388507d 100644 --- a/src/include/Makefile.am +++ b/src/include/Makefile.am @@ -17,6 +17,7 @@ talerinclude_HEADERS = \ taler_exchangedb_plugin.h \ taler_extensions.h \ taler_fakebank_lib.h \ + taler_kyclogic_plugin.h \ taler_json_lib.h \ taler_testing_lib.h \ taler_util.h \ diff --git a/src/include/taler_kyclogic_plugin.h b/src/include/taler_kyclogic_plugin.h new file mode 100644 index 000000000..303c53443 --- /dev/null +++ b/src/include/taler_kyclogic_plugin.h @@ -0,0 +1,125 @@ +/* + This file is part of TALER + Copyright (C) 2022 Taler Systems SA + + 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, see <http://www.gnu.org/licenses/> +*/ +/** + * @file include/taler_kyclogic_plugin.h + * @brief KYC API specific logic C interface + * @author Christian Grothoff + */ +#ifndef TALER_KYCLOGIC_PLUGIN_H +#define TALER_KYCLOGIC_PLUGIN_H + +#include <jansson.h> +#include <gnunet/gnunet_util_lib.h> + + +/** + * Plugin-internal specification of the configuration + * of the plugin for a given KYC provider. + */ +struct TEH_KYCLOGIC_ProviderDetails; + +/** + * Handle for an initiation operation. + */ +struct TEH_KYCLOGIC_InitiateHandle; + + +/** + * Function called with the result of a KYC initiation + * operation. + * + * @param ec #TALER_EC_NONE on success + * @param redirect_url set to where to redirect the user on success, NULL on failure + * @param provider_user_id set to user ID at the provider, or NULL if not supported or unknown + * @param provider_legitimization_id set to legitimization process ID at the provider, or NULL if not supported or unknown + * @param error_msg_hint set to additional details to return to user, NULL on success + */ +typedef void +(*TEH_KYCLOGIC_InitiateCallback)( + enum TALER_ErrorCode ec, + const char *redirect_url, + const char *provider_user_id, + const char *provider_legitimization_id, + const char *error_msg_hint); + + +/** + * @brief The plugin API, returned from the plugin's "init" function. + * The argument given to "init" is simply a configuration handle. + */ +struct TALER_KYCLOGIC_Plugin +{ + + /** + * Closure for all callbacks. + */ + void *cls; + + /** + * Name of the library which generated this plugin. Set by the + * plugin loader. + */ + char *library_name; + + /** + * Load the configuration of the KYC provider. + * + * @param provider_section_name configuration section to parse + * @return NULL if configuration is invalid + */ + struct TEH_KYCLOGIC_ProviderDetails * + (*load_configuration)(const char *provider_section_name); + + /** + * Release configuration resources previously loaded + * + * @param[in] pd configuration to release + */ + void + (*unload_configuration)(struct TEH_KYCLOGIC_ProviderDetails *pd); + + + /** + * Initiate KYC check. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param pd provider configuration details + * @param account_id which account to trigger process for + * @return handle to cancel operation early + */ + struct TEH_KYCLOGIC_InitiateHandle * + (*initiate)(void *cls, + const struct TEH_KYCLOGIC_ProviderDetails *pd, + const struct TALER_PaytoHashP *account_id, + TEH_KYCLOGIC_InitiateCallback cb, + void *cb_cls); + + /** + * Cancel KYC check initiation. + * + * @param[in] ih handle of operation to cancel + */ + void + (*initiate_cancel) (struct TEH_KYCLOGIC_InitiateHandle *ih); + + // FIXME: add callback pair for kyc_proof + + // FIXME: add callback pair for kyc_webhook + +}; + + +#endif /* _TALER_KYCLOGIC_PLUGIN_H */ |