diff options
Diffstat (limited to 'src/include')
| -rw-r--r-- | src/include/Makefile.am | 1 | ||||
| -rw-r--r-- | src/include/taler_kyclogic_lib.h | 226 |
2 files changed, 227 insertions, 0 deletions
diff --git a/src/include/Makefile.am b/src/include/Makefile.am index f3388507d..5cb1698cc 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_lib.h \ taler_kyclogic_plugin.h \ taler_json_lib.h \ taler_testing_lib.h \ diff --git a/src/include/taler_kyclogic_lib.h b/src/include/taler_kyclogic_lib.h new file mode 100644 index 000000000..6b54276f6 --- /dev/null +++ b/src/include/taler_kyclogic_lib.h @@ -0,0 +1,226 @@ +/* + 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_kyclogic_lib.h + * @brief server-side KYC API + * @author Christian Grothoff + */ +#ifndef TALER_KYCLOGIC_LIB_H +#define TALER_KYCLOGIC_LIB_H + +#include <microhttpd.h> +#include <taler_exchangedb_plugin.h> +#include <taler_kyclogic_plugin.h> + + +/** + * Enumeration for our KYC user types. + */ +enum TALER_KYCLOGIC_KycUserType +{ + /** + * KYC rule is for an individual. + */ + TALER_KYCLOGIC_KYC_UT_INDIVIDUAL = 0, + + /** + * KYC rule is for a business. + */ + TALER_KYCLOGIC_KYC_UT_BUSINESS = 1 +}; + + +/** + * Enumeration of possible events that may trigger + * KYC requirements. + */ +enum TALER_KYCLOGIC_KycTriggerEvent +{ + + /** + * Customer withdraws coins. + */ + TALER_KYCLOGIC_KYC_TRIGGER_WITHDRAW = 0, + + /** + * Merchant deposits coins. + */ + TALER_KYCLOGIC_KYC_TRIGGER_DEPOSIT = 1, + + /** + * Wallet receives P2P payment. + */ + TALER_KYCLOGIC_KYC_TRIGGER_P2P_RECEIVE = 2, + + /** + * Wallet balance exceeds threshold. + */ + TALER_KYCLOGIC_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 +TALER_KYCLOGIC_kyc_trigger_from_string ( + const char *trigger_s, + enum TALER_KYCLOGIC_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 * +TALER_KYCLOGIC_kyc_trigger2s (enum TALER_KYCLOGIC_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 +TALER_KYCLOGIC_kyc_user_type_from_string (const char *ut_s, + enum TALER_KYCLOGIC_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 * +TALER_KYCLOGIC_kyc_user_type2s (enum TALER_KYCLOGIC_KycUserType ut); + + +/** + * Initialize KYC subsystem. Loads the KYC configuration. + * + * @param cfg configuration to parse + * @return #GNUNET_OK on success + */ +enum GNUNET_GenericReturnValue +TALER_KYCLOGIC_kyc_init (const struct GNUNET_CONFIGURATION_Handle *cfg); + + +/** + * Shut down the KYC subsystem. + */ +void +TALER_KYCLOGIC_kyc_done (void); + + +/** + * 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 + */ +typedef void +(*TALER_KYCLOGIC_KycAmountIterator)(void *cls, + struct GNUNET_TIME_Absolute limit, + TALER_EXCHANGEDB_KycAmountCallback cb, + void *cb_cls); + + +/** + * Call us on KYC processes satisfied for the given + * account. Must match the ``select_satisfied_kyc_processes`` of the exchange database plugin. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param h_payto account identifier + * @param spc function to call for each satisfied KYC process + * @param spc_cls closure for @a spc + * @return transaction status code + */ +typedef enum GNUNET_DB_QueryStatus +(*TALER_KYCLOGIC_KycSatisfiedIterator)( + void *cls, + const struct TALER_PaytoHashP *h_payto, + TALER_EXCHANGEDB_SatisfiedProviderCallback spc, + void *spc_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 ki callback that returns list of already + * satisfied KYC checks, implemented by ``select_satisfied_kyc_processes`` of the exchangedb + * @param ki_cls closure for @a ki + * @param ai callback offered to inquire about historic + * amounts involved in this type of operation + * at the given account + * @param ai_cls closure for @a ai + * @return NULL if no check is needed + */ +const char * +TALER_KYCLOGIC_kyc_test_required (enum TALER_KYCLOGIC_KycTriggerEvent event, + const struct TALER_PaytoHashP *h_payto, + TALER_KYCLOGIC_KycSatisfiedIterator ki, + void *ki_cls, + TALER_KYCLOGIC_KycAmountIterator ai, + void *ai_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 +TALER_KYCLOGIC_kyc_get_logic (const char *provider_section_name, + struct TALER_KYCLOGIC_Plugin **plugin, + struct TALER_KYCLOGIC_ProviderDetails **pd); + + +#endif |