exchange

Base system with REST service to issue digital coins, run by the payment service provider
Log | Files | Refs | Submodules | README | LICENSE

taler-helper-auditor-aml.c (33735B)


      1 /*
      2   This file is part of TALER
      3   Copyright (C) 2026 Taler Systems SA
      4 
      5   TALER is free software; you can redistribute it and/or modify it under the
      6   terms of the GNU Affero Public License as published by the Free Software
      7   Foundation; either version 3, or (at your option) any later version.
      8 
      9   TALER is distributed in the hope that it will be useful, but WITHOUT ANY
     10   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
     11   A PARTICULAR PURPOSE.  See the GNU Affero Public License for more details.
     12 
     13   You should have received a copy of the GNU Affero Public License along with
     14   TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
     15 */
     16 /**
     17  * @file auditor/taler-helper-auditor-aml.c
     18  * @brief audits the AML decisions and the appointments of the AML staff who
     19  *        made them
     20  * @author Christian Grothoff
     21  *
     22  * Three checks, in one transaction and in this order, because each is judged
     23  * against the result of the one before it:
     24  *
     25  * 1) every row in `aml_staff` must carry a valid signature by the exchange's
     26  *    *offline* master key.  Without this an exchange could appoint an AML
     27  *    officer -- or quietly widen a read-only officer to read-write -- with
     28  *    the offline key never having been involved.
     29  *
     30  * 2) every AML decision in `aml_history` must carry a valid signature by an
     31  *    officer who, at the time of the decision, was appointed and had
     32  *    read-write access.
     33  *
     34  * 3) every row in `legitimization_outcomes` must have something that accounts
     35  *    for it.  That table holds the rules currently in force for an account,
     36  *    so it is what decides whether a customer's transaction is allowed; a row
     37  *    that nothing produced is precisely how an exchange would quietly exempt
     38  *    a customer from KYC.  See #check_outcome_cb() for what counts.
     39  *
     40  * None of the findings is a loss: neither an AML decision nor a rule change
     41  * moves money, so a bad signature or an unaccounted-for rule set costs the
     42  * exchange nothing directly.  What it costs is the point of having officers
     43  * sign at all, so the findings are reported as row inconsistencies rather
     44  * than as bad-sig losses.
     45  *
     46  * `aml_staff` is append-only -- a status change is a new row -- so the
     47  * exchange's own database does answer "was this officer allowed to decide at
     48  * that time?".  The auditor nevertheless keeps its own record of every status
     49  * change it has seen, in `auditor_aml_staff`, and answers the question from
     50  * that: append-only is a promise the exchange's code makes, not one the
     51  * database enforces against the exchange's operator, and an independent
     52  * record is the point of an auditor.
     53  *
     54  * That record is also what makes backdating detectable.  The master key is
     55  * the exchange operator's own, so a dishonest operator can sign an
     56  * appointment naming any `last_change` it likes, and a decision naming any
     57  * `decision_time`.  What it cannot do is change what the auditor already
     58  * saw: if the auditor recorded an officer as disabled before this round
     59  * began, a decision by that officer surfacing now is backdated, whatever
     60  * `decision_time` claims.  This does not stop backdating *within* the set of
     61  * rows processed in one round -- an auditor running promptly keeps that
     62  * window small, which is the whole defence.
     63  */
     64 #include "platform.h"
     65 #include <gnunet/gnunet_util_lib.h>
     66 #include "auditordb_lib.h"
     67 #include "exchangedb_lib.h"
     68 #include "report-lib.h"
     69 #include "taler/taler_dbevents.h"
     70 #include <jansson.h>
     71 #include <inttypes.h>
     72 #include "auditor-database/event_listen.h"
     73 #include "auditor-database/get_auditor_progress.h"
     74 #include "auditor-database/insert_aml_staff.h"
     75 #include "auditor-database/insert_auditor_progress.h"
     76 #include "auditor-database/insert_row_inconsistency.h"
     77 #include "auditor-database/iterate_aml_staff.h"
     78 #include "exchange-database/iterate_aml_history_above_serial_id.h"
     79 #include "exchange-database/iterate_aml_staff_above_serial_id.h"
     80 #include "exchange-database/iterate_legitimization_outcomes_above_serial_id.h"
     81 
     82 
     83 /**
     84  * Return value from main().
     85  */
     86 static int global_ret;
     87 
     88 /**
     89  * Row of `aml_history` up to which we have checked AML decisions.
     90  */
     91 static TALER_ARL_DEF_PP (aml_history_serial_id);
     92 
     93 /**
     94  * Row of `aml_staff` up to which we have checked status changes.
     95  */
     96 static TALER_ARL_DEF_PP (aml_staff_uuid);
     97 
     98 /**
     99  * Row of `legitimization_outcomes` up to which we have checked that the
    100  * rules in force for an account are accounted for.
    101  */
    102 static TALER_ARL_DEF_PP (legitimization_outcome_serial_id);
    103 
    104 /**
    105  * Run in test mode. Exit when idle instead of
    106  * going to sleep and waiting for more work.
    107  */
    108 static int test_mode;
    109 
    110 /**
    111  * Should we run checks that only work for exchange-internal audits?
    112  * Does nothing for this helper (present only for uniformity).
    113  */
    114 static int internal_checks;
    115 
    116 /**
    117  * Handle to the database event we wait on when running resident.
    118  */
    119 static struct GNUNET_DB_EventHandler *eh;
    120 
    121 /**
    122  * The auditors's configuration.
    123  */
    124 static const struct GNUNET_CONFIGURATION_Handle *cfg;
    125 
    126 /**
    127  * Map from the hash of an officer's public key to a `struct StaffMember`.
    128  */
    129 static struct GNUNET_CONTAINER_MultiHashMap *staff_map;
    130 
    131 /**
    132  * Status of the DB operations of our callbacks; they cannot return a
    133  * query status themselves.
    134  */
    135 static enum GNUNET_DB_QueryStatus global_qs;
    136 
    137 
    138 /**
    139  * One observed status of an AML staff member, in force from @e last_change
    140  * until the next status of the same member.
    141  */
    142 struct StaffStatus
    143 {
    144   /**
    145    * When this status took effect, as claimed by the exchange.
    146    */
    147   struct GNUNET_TIME_Timestamp last_change;
    148 
    149   /**
    150    * Was the member allowed to act?
    151    */
    152   bool is_active;
    153 
    154   /**
    155    * Was the member restricted to read-only access?
    156    */
    157   bool read_only;
    158 
    159   /**
    160    * Hash of the legal name of the member at this status.  Kept instead of
    161    * the name itself so that the entry owns no memory.
    162    */
    163   struct GNUNET_HashCode h_name;
    164 
    165   /**
    166    * Did the exchange's offline master key actually sign this status?
    167    * A status that fails this check confers no authority.
    168    */
    169   bool master_sig_valid;
    170 };
    171 
    172 
    173 /**
    174  * What we know about one AML staff member.
    175  */
    176 struct StaffMember
    177 {
    178   /**
    179    * Key under which this member is stored in #staff_map.  The map is
    180    * created with @a do_not_copy_keys, so it keeps this pointer: the key
    181    * has to live as long as the entry does.
    182    */
    183   struct GNUNET_HashCode key;
    184 
    185   /**
    186    * Observed statuses, oldest first.
    187    */
    188   struct StaffStatus *statuses;
    189 
    190   /**
    191    * Length of @e statuses.
    192    */
    193   unsigned int num_statuses;
    194 
    195   /**
    196    * Did we already know this member when the round began?
    197    */
    198   bool known_at_start;
    199 
    200   /**
    201    * Was the member enabled according to the most recent status we knew
    202    * when the round began?  Meaningless unless @e known_at_start.
    203    */
    204   bool active_at_start;
    205 
    206   /**
    207    * Did we observe the member being enabled during this round?
    208    */
    209   bool enabled_this_round;
    210 };
    211 
    212 
    213 /**
    214  * Compute the map key for @a decider_pub.
    215  *
    216  * @param decider_pub public key of the staff member
    217  * @param[out] key set to the key to use
    218  */
    219 static void
    220 staff_key (const struct TALER_AmlOfficerPublicKeyP *decider_pub,
    221            struct GNUNET_HashCode *key)
    222 {
    223   GNUNET_CRYPTO_hash (decider_pub,
    224                       sizeof (*decider_pub),
    225                       key);
    226 }
    227 
    228 
    229 /**
    230  * Compute the hash of the legal name @a decider_name.
    231  *
    232  * @param decider_name legal name of the staff member, NULL if not given
    233  * @param[out] h_name set to the hash to use
    234  */
    235 static void
    236 staff_name_hash (const char *decider_name,
    237                  struct GNUNET_HashCode *h_name)
    238 {
    239   if (NULL == decider_name)
    240     decider_name = "";
    241   GNUNET_CRYPTO_hash (decider_name,
    242                       strlen (decider_name),
    243                       h_name);
    244 }
    245 
    246 
    247 /**
    248  * Look up @a decider_pub in #staff_map, creating the entry if needed.
    249  *
    250  * @param decider_pub public key of the staff member
    251  * @return the entry, never NULL
    252  */
    253 static struct StaffMember *
    254 staff_member_get (const struct TALER_AmlOfficerPublicKeyP *decider_pub)
    255 {
    256   struct GNUNET_HashCode key;
    257   struct StaffMember *sm;
    258 
    259   staff_key (decider_pub,
    260              &key);
    261   sm = GNUNET_CONTAINER_multihashmap_get (staff_map,
    262                                           &key);
    263   if (NULL != sm)
    264     return sm;
    265   sm = GNUNET_new (struct StaffMember);
    266   sm->key = key;
    267   GNUNET_assert (GNUNET_OK ==
    268                  GNUNET_CONTAINER_multihashmap_put (
    269                    staff_map,
    270                    &sm->key,
    271                    sm,
    272                    GNUNET_CONTAINER_MULTIHASHMAPOPTION_UNIQUE_ONLY));
    273   return sm;
    274 }
    275 
    276 
    277 /**
    278  * Append @a status to the statuses of @a sm, keeping them ordered by
    279  * @e last_change.
    280  *
    281  * @param[in,out] sm staff member to extend
    282  * @param status status to add
    283  */
    284 static void
    285 staff_member_add (struct StaffMember *sm,
    286                   const struct StaffStatus *status)
    287 {
    288   unsigned int i;
    289 
    290   GNUNET_array_grow (sm->statuses,
    291                      sm->num_statuses,
    292                      sm->num_statuses + 1);
    293   for (i = sm->num_statuses - 1; i > 0; i--)
    294   {
    295     if (GNUNET_TIME_timestamp_cmp (sm->statuses[i - 1].last_change,
    296                                    <=,
    297                                    status->last_change))
    298       break;
    299     sm->statuses[i] = sm->statuses[i - 1];
    300   }
    301   sm->statuses[i] = *status;
    302 }
    303 
    304 
    305 /**
    306  * Find the status that was in force for @a sm at @a when, considering only
    307  * statuses the offline master key really signed.
    308  *
    309  * @param sm staff member to look at
    310  * @param when point in time of interest
    311  * @return NULL if no signed status covers @a when
    312  */
    313 static const struct StaffStatus *
    314 staff_member_status_at (const struct StaffMember *sm,
    315                         struct GNUNET_TIME_Timestamp when)
    316 {
    317   const struct StaffStatus *ret = NULL;
    318 
    319   for (unsigned int i = 0; i < sm->num_statuses; i++)
    320   {
    321     const struct StaffStatus *ss = &sm->statuses[i];
    322 
    323     if (GNUNET_TIME_timestamp_cmp (ss->last_change,
    324                                    >,
    325                                    when))
    326       break; /* sorted, so no later entry can apply either */
    327     if (ss->master_sig_valid)
    328       ret = ss;
    329   }
    330   return ret;
    331 }
    332 
    333 
    334 /**
    335  * Report a row inconsistency.
    336  *
    337  * @param table name of the exchange table the bad row is in
    338  * @param rowid row that is bad
    339  * @param diagnostic what is wrong with it
    340  * @return true on success, false if the database failed us
    341  */
    342 static bool
    343 report_row (const char *table,
    344             uint64_t rowid,
    345             const char *diagnostic)
    346 {
    347   struct TALER_AUDITORDB_RowInconsistency ri = {
    348     .problem_row_id = rowid,
    349     .row_table = (char *) table,
    350     .diagnostic = (char *) diagnostic
    351   };
    352   enum GNUNET_DB_QueryStatus qs;
    353 
    354   GNUNET_log (GNUNET_ERROR_TYPE_WARNING,
    355               "Row %llu of `%s' is bad: %s\n",
    356               (unsigned long long) rowid,
    357               table,
    358               diagnostic);
    359   qs = TALER_AUDITORDB_insert_row_inconsistency (TALER_ARL_adb,
    360                                                  &ri);
    361   if (0 > qs)
    362   {
    363     GNUNET_break (GNUNET_DB_STATUS_SOFT_ERROR == qs);
    364     global_qs = qs;
    365     return false;
    366   }
    367   return true;
    368 }
    369 
    370 
    371 /**
    372  * Function called with an AML staff status change we recorded earlier.
    373  * Rebuilds our view of who was allowed to decide when.
    374  *
    375  * @param cls NULL
    376  * @param decider_pub public key of the staff member
    377  * @param decider_name legal name of the staff member
    378  * @param is_active true if the member could act from @a last_change on
    379  * @param read_only true if the member had read-only access
    380  * @param master_sig_valid true if the master key really signed this status
    381  * @param last_change when the status took effect
    382  * @return #GNUNET_OK to continue to iterate
    383  */
    384 static enum GNUNET_GenericReturnValue
    385 known_staff_cb (void *cls,
    386                 const struct TALER_AmlOfficerPublicKeyP *decider_pub,
    387                 const char *decider_name,
    388                 bool is_active,
    389                 bool read_only,
    390                 bool master_sig_valid,
    391                 struct GNUNET_TIME_Timestamp last_change)
    392 {
    393   struct StaffMember *sm = staff_member_get (decider_pub);
    394   struct StaffStatus ss = {
    395     .last_change = last_change,
    396     .is_active = is_active,
    397     .read_only = read_only,
    398     .master_sig_valid = master_sig_valid
    399   };
    400 
    401   (void) cls;
    402   staff_name_hash (decider_name,
    403                    &ss.h_name);
    404   staff_member_add (sm,
    405                     &ss);
    406   /* We are called oldest-first, so the last call for a member leaves the
    407      status that was in force when this round began. */
    408   sm->known_at_start = true;
    409   sm->active_at_start = is_active && master_sig_valid;
    410   return GNUNET_OK;
    411 }
    412 
    413 
    414 /**
    415  * Function called with a status change of an AML staff member the exchange
    416  * recorded.  Verifies the offline master key's signature on it and, if this
    417  * is a status we have not seen before, records it.
    418  *
    419  * @param cls NULL
    420  * @param rowid row in `aml_staff`
    421  * @param decider_pub public key of the staff member
    422  * @param master_sig signature by the offline master key, NULL if absent
    423  * @param decider_name legal name of the staff member
    424  * @param is_active true if the member may currently act
    425  * @param read_only true if the member has read-only access
    426  * @param last_change when the status took effect, as claimed
    427  * @return #GNUNET_OK to continue to iterate, #GNUNET_SYSERR to stop
    428  */
    429 static enum GNUNET_GenericReturnValue
    430 check_staff_cb (void *cls,
    431                 uint64_t rowid,
    432                 const struct TALER_AmlOfficerPublicKeyP *decider_pub,
    433                 const struct TALER_MasterSignatureP *master_sig,
    434                 const char *decider_name,
    435                 bool is_active,
    436                 bool read_only,
    437                 struct GNUNET_TIME_Timestamp last_change)
    438 {
    439   struct StaffMember *sm = staff_member_get (decider_pub);
    440   struct StaffStatus ss = {
    441     .last_change = last_change,
    442     .is_active = is_active,
    443     .read_only = read_only,
    444     .master_sig_valid = false
    445   };
    446   enum GNUNET_DB_QueryStatus qs;
    447   bool regression = false;
    448 
    449   (void) cls;
    450   TALER_ARL_USE_PP (aml_staff_uuid) = rowid + 1;
    451   staff_name_hash (decider_name,
    452                    &ss.h_name);
    453   for (unsigned int i = 0; i < sm->num_statuses; i++)
    454   {
    455     const struct StaffStatus *os = &sm->statuses[i];
    456 
    457     if (GNUNET_TIME_timestamp_cmp (os->last_change,
    458                                    ==,
    459                                    last_change))
    460     {
    461       if ( (os->is_active == is_active) &&
    462            (os->read_only == read_only) &&
    463            (0 == GNUNET_memcmp (&os->h_name,
    464                                 &ss.h_name)) )
    465         return GNUNET_OK; /* already seen and judged in an earlier round */
    466       /* Same timestamp, but a different status: this widens (or narrows) the
    467          officer's authority and must be judged and recorded like any other
    468          status change. */
    469       continue;
    470     }
    471     if (GNUNET_TIME_timestamp_cmp (os->last_change,
    472                                    >,
    473                                    last_change))
    474       regression = true;
    475   }
    476   if (NULL == master_sig)
    477   {
    478     if (! report_row ("aml_staff",
    479                       rowid,
    480                       "staff status without a master key signature"))
    481       return GNUNET_SYSERR;
    482   }
    483   else if (GNUNET_OK !=
    484            TALER_exchange_offline_aml_officer_status_verify (
    485              decider_pub,
    486              decider_name,
    487              last_change,
    488              is_active,
    489              read_only,
    490              &TALER_ARL_master_pub,
    491              master_sig))
    492   {
    493     if (! report_row ("aml_staff",
    494                       rowid,
    495                       "invalid master key signature on staff status")
    496         )
    497       return GNUNET_SYSERR;
    498   }
    499   else
    500   {
    501     ss.master_sig_valid = true;
    502   }
    503   if (regression)
    504   {
    505     /* exchange_do_insert_aml_officer() refuses to store a status older than
    506        the one it has, so seeing one means somebody wrote to the table
    507        behind the exchange's back. */
    508     if (! report_row ("aml_staff",
    509                       rowid,
    510                       "staff status is older than one seen before"))
    511       return GNUNET_SYSERR;
    512   }
    513   if (ss.master_sig_valid && is_active)
    514     sm->enabled_this_round = true;
    515   staff_member_add (sm,
    516                     &ss);
    517   qs = TALER_AUDITORDB_insert_aml_staff (TALER_ARL_adb,
    518                                          decider_pub,
    519                                          decider_name,
    520                                          is_active,
    521                                          read_only,
    522                                          ss.master_sig_valid,
    523                                          last_change);
    524   if (0 > qs)
    525   {
    526     GNUNET_break (GNUNET_DB_STATUS_SOFT_ERROR == qs);
    527     global_qs = qs;
    528     return GNUNET_SYSERR;
    529   }
    530   return GNUNET_OK;
    531 }
    532 
    533 
    534 /**
    535  * Function called with an AML decision the exchange recorded.  Checks the
    536  * officer's signature and that the officer was allowed to make it.
    537  *
    538  * @param cls NULL
    539  * @param rowid row in `aml_history`
    540  * @param h_payto account the decision is about
    541  * @param justification justification given
    542  * @param decider_pub officer who decided, NULL if not recorded
    543  * @param decider_sig the officer's signature, NULL if not recorded
    544  * @param decision_time when the decision was taken, as claimed
    545  * @param jproperties new account properties, NULL for none
    546  * @param jnew_rules new KYC rules, NULL if not recorded
    547  * @param new_measure_name measure to apply, NULL for none
    548  * @param to_investigate whether staff should investigate the account
    549  * @param attributes_expiration when attributes set with the decision expire
    550  * @param h_attributes hash of the attributes set, NULL if none
    551  * @return #GNUNET_OK to continue to iterate, #GNUNET_SYSERR to stop
    552  */
    553 static enum GNUNET_GenericReturnValue
    554 check_decision_cb (void *cls,
    555                    uint64_t rowid,
    556                    const struct TALER_NormalizedPaytoHashP *h_payto,
    557                    const char *justification,
    558                    const struct TALER_AmlOfficerPublicKeyP *decider_pub,
    559                    const struct TALER_AmlOfficerSignatureP *decider_sig,
    560                    struct GNUNET_TIME_Timestamp decision_time,
    561                    const json_t *jproperties,
    562                    const json_t *jnew_rules,
    563                    const char *new_measure_name,
    564                    bool to_investigate,
    565                    struct GNUNET_TIME_Timestamp attributes_expiration,
    566                    const struct GNUNET_HashCode *h_attributes)
    567 {
    568   struct StaffMember *sm;
    569   const struct StaffStatus *ss;
    570 
    571   (void) cls;
    572   GNUNET_log (GNUNET_ERROR_TYPE_INFO,
    573               "Analyzing AML decision %llu taken at %s\n",
    574               (unsigned long long) rowid,
    575               GNUNET_TIME_timestamp2s (decision_time));
    576   TALER_ARL_USE_PP (aml_history_serial_id) = rowid + 1;
    577   if (NULL == decider_pub)
    578   {
    579     /* exchange_do_insert_aml_decision() only writes an aml_history row when
    580        it has a decider, so this cannot happen without tampering. */
    581     if (! report_row ("aml_history",
    582                       rowid,
    583                       "decision without an officer public key"))
    584       return GNUNET_SYSERR;
    585     return GNUNET_OK;
    586   }
    587   if (NULL == decider_sig)
    588   {
    589     if (! report_row ("aml_history",
    590                       rowid,
    591                       "decision without an officer signature"))
    592       return GNUNET_SYSERR;
    593   }
    594   else if (NULL == jnew_rules)
    595   {
    596     /* The signature is over the new rules, so without them there is nothing
    597        we could check it against. */
    598     if (! report_row ("aml_history",
    599                       rowid,
    600                       "decision without the new rules it signed over"))
    601       return GNUNET_SYSERR;
    602   }
    603   else if (GNUNET_OK !=
    604            TALER_officer_aml_decision_verify_hashed (
    605              justification,
    606              decision_time,
    607              h_payto,
    608              jnew_rules,
    609              jproperties,
    610              new_measure_name,
    611              to_investigate,
    612              attributes_expiration,
    613              h_attributes,
    614              decider_pub,
    615              decider_sig))
    616   {
    617     if (! report_row ("aml_history",
    618                       rowid,
    619                       "invalid officer signature on decision"))
    620       return GNUNET_SYSERR;
    621   }
    622   sm = staff_member_get (decider_pub);
    623   ss = staff_member_status_at (sm,
    624                                decision_time);
    625   if (NULL == ss)
    626   {
    627     if (! report_row ("aml_history",
    628                       rowid,
    629                       "officer was not appointed when the decision was made"))
    630       return GNUNET_SYSERR;
    631   }
    632   else if (! ss->is_active)
    633   {
    634     if (! report_row ("aml_history",
    635                       rowid,
    636                       "officer was not active when the decision was made"))
    637       return GNUNET_SYSERR;
    638   }
    639   else if (ss->read_only)
    640   {
    641     if (! report_row ("aml_history",
    642                       rowid,
    643                       "officer had read-only access when deciding"))
    644       return GNUNET_SYSERR;
    645   }
    646   /* The eligibility check above trusts decision_time, which the exchange
    647      picks.  This one does not: whatever the decision claims, a record for an
    648      officer we already knew to be disabled has no business appearing now. */
    649   if (sm->known_at_start &&
    650       (! sm->active_at_start) &&
    651       (! sm->enabled_this_round))
    652   {
    653     if (! report_row ("aml_history",
    654                       rowid,
    655                       "decision appeared after the officer was disabled"))
    656       return GNUNET_SYSERR;
    657   }
    658   return GNUNET_OK;
    659 }
    660 
    661 
    662 /**
    663  * Function called with a row of `legitimization_outcomes`, the table that
    664  * says which KYC rules currently apply to an account.  Checks that something
    665  * in the exchange's books accounts for the row existing.
    666  *
    667  * The exchange has exactly three ways to create one, and each leaves its own
    668  * trace:
    669  *
    670  * - an AML officer decides, and `exchange_do_insert_aml_decision()` writes an
    671  *   `aml_history` row pointing at the outcome.  #check_decision_cb() has
    672  *   already checked that decision's signature and the officer's appointment,
    673  *   so this is the strongest of the three;
    674  * - a customer passes (or fails) a KYC check, and the AML program's verdict
    675  *   on it becomes the outcome.  What is left of the check is a row in
    676  *   `legitimization_processes` for the same account, started no later than
    677  *   the decision;
    678  * - the rules in force expire, and `exchange_do_insert_successor_measure()`
    679  *   or a re-run of the AML program replaces them.  What is left of that is
    680  *   the expired predecessor outcome.
    681  *
    682  * A row with none of the three was written by something other than the
    683  * exchange's own code.  Note that the third alternative is the weak one: an
    684  * account that has ever had an outcome expire can be given further outcomes
    685  * without any fresh justification, exactly as the exchange legitimately does
    686  * on expiry.  The check is a floor, not a proof that the rules are right.
    687  *
    688  * @param cls NULL
    689  * @param rowid row in `legitimization_outcomes`
    690  * @param h_payto account the outcome is about
    691  * @param decision_time when the outcome was decided, as claimed
    692  * @param expiration_time when the outcome expires
    693  * @param has_aml_decision an `aml_history` row points at this outcome
    694  * @param has_legitimization_process the account had a legitimization process
    695  *        that had started by @a decision_time
    696  * @param has_expired_predecessor an earlier outcome for the account had
    697  *        expired by @a decision_time
    698  * @return #GNUNET_OK to continue to iterate, #GNUNET_SYSERR to stop
    699  */
    700 static enum GNUNET_GenericReturnValue
    701 check_outcome_cb (void *cls,
    702                   uint64_t rowid,
    703                   const struct TALER_NormalizedPaytoHashP *h_payto,
    704                   struct GNUNET_TIME_Timestamp decision_time,
    705                   struct GNUNET_TIME_Timestamp expiration_time,
    706                   bool has_aml_decision,
    707                   bool has_legitimization_process,
    708                   bool has_expired_predecessor)
    709 {
    710   (void) cls;
    711   (void) h_payto;
    712   (void) expiration_time;
    713   GNUNET_log (GNUNET_ERROR_TYPE_INFO,
    714               "Analyzing legitimization outcome %llu decided at %s\n",
    715               (unsigned long long) rowid,
    716               GNUNET_TIME_timestamp2s (decision_time));
    717   TALER_ARL_USE_PP (legitimization_outcome_serial_id) = rowid + 1;
    718   if (has_aml_decision ||
    719       has_legitimization_process ||
    720       has_expired_predecessor)
    721     return GNUNET_OK;
    722   if (! report_row ("legitimization_outcomes",
    723                     rowid,
    724                     "KYC rules in force without an AML decision,"
    725                     " a legitimization process or an expired predecessor"))
    726     return GNUNET_SYSERR;
    727   return GNUNET_OK;
    728 }
    729 
    730 
    731 /**
    732  * Free a `struct StaffMember`.
    733  *
    734  * @param cls NULL
    735  * @param key unused
    736  * @param value the `struct StaffMember` to free
    737  * @return #GNUNET_OK
    738  */
    739 static enum GNUNET_GenericReturnValue
    740 free_staff_member (void *cls,
    741                    const struct GNUNET_HashCode *key,
    742                    void *value)
    743 {
    744   struct StaffMember *sm = value;
    745 
    746   (void) cls;
    747   (void) key;
    748   GNUNET_assert (GNUNET_YES ==
    749                  GNUNET_CONTAINER_multihashmap_remove (staff_map,
    750                                                        &sm->key,
    751                                                        sm));
    752   GNUNET_array_grow (sm->statuses,
    753                      sm->num_statuses,
    754                      0);
    755   GNUNET_free (sm);
    756   return GNUNET_OK;
    757 }
    758 
    759 
    760 /**
    761  * Drop our in-memory view of the AML staff.
    762  */
    763 static void
    764 clear_staff_map (void)
    765 {
    766   if (NULL == staff_map)
    767     return;
    768   GNUNET_CONTAINER_multihashmap_iterate (staff_map,
    769                                          &free_staff_member,
    770                                          NULL);
    771   GNUNET_CONTAINER_multihashmap_destroy (staff_map);
    772   staff_map = NULL;
    773 }
    774 
    775 
    776 /**
    777  * Analyze the AML staff appointments and the decisions they justify.
    778  *
    779  * @param cls NULL
    780  * @return transaction status code
    781  */
    782 static enum GNUNET_DB_QueryStatus
    783 analyze_aml (void *cls)
    784 {
    785   enum GNUNET_DB_QueryStatus qs;
    786   bool had_pp;
    787 
    788   (void) cls;
    789   global_qs = GNUNET_DB_STATUS_SUCCESS_NO_RESULTS;
    790   clear_staff_map ();
    791   staff_map = GNUNET_CONTAINER_multihashmap_create (32,
    792                                                     GNUNET_YES);
    793   qs = TALER_AUDITORDB_get_auditor_progress (
    794     TALER_ARL_adb,
    795     TALER_ARL_GET_PP (aml_history_serial_id),
    796     TALER_ARL_GET_PP (aml_staff_uuid),
    797     TALER_ARL_GET_PP (legitimization_outcome_serial_id),
    798     NULL);
    799   if (0 > qs)
    800   {
    801     GNUNET_break (GNUNET_DB_STATUS_SOFT_ERROR == qs);
    802     return qs;
    803   }
    804   /* Not from @a qs: auditor_do_get_auditor_progress() returns one row per
    805      key whether or not the key is on file, so the query status says nothing
    806      about whether we have run before. */
    807   had_pp = (0 != TALER_ARL_USE_PP (aml_staff_uuid)) ||
    808            (0 != TALER_ARL_USE_PP (aml_history_serial_id)) ||
    809            (0 != TALER_ARL_USE_PP (legitimization_outcome_serial_id));
    810   if (had_pp)
    811     GNUNET_log (GNUNET_ERROR_TYPE_INFO,
    812                 "Resuming AML audit at %llu/%llu/%llu\n",
    813                 (unsigned long long) TALER_ARL_USE_PP (aml_staff_uuid),
    814                 (unsigned long long) TALER_ARL_USE_PP (aml_history_serial_id),
    815                 (unsigned long long) TALER_ARL_USE_PP (
    816                   legitimization_outcome_serial_id));
    817   else
    818     GNUNET_log (GNUNET_ERROR_TYPE_MESSAGE,
    819                 "First analysis using AML auditor, starting audit from scratch\n");
    820 
    821   /* What we knew about the staff when this round began. */
    822   qs = TALER_AUDITORDB_iterate_aml_staff (TALER_ARL_adb,
    823                                           &known_staff_cb,
    824                                           NULL);
    825   if (0 > qs)
    826   {
    827     GNUNET_break (GNUNET_DB_STATUS_SOFT_ERROR == qs);
    828     return qs;
    829   }
    830 
    831   /* Status changes the exchange recorded since we last looked.  Must run
    832      before the decisions below, which are judged against the result. */
    833   qs = TALER_EXCHANGEDB_iterate_aml_staff_above_serial_id (
    834     TALER_ARL_edb,
    835     TALER_ARL_USE_PP (aml_staff_uuid),
    836     &check_staff_cb,
    837     NULL);
    838   if (0 > qs)
    839   {
    840     GNUNET_break (GNUNET_DB_STATUS_SOFT_ERROR == qs);
    841     return qs;
    842   }
    843   if (0 > global_qs)
    844     return global_qs;
    845 
    846   qs = TALER_EXCHANGEDB_iterate_aml_history_above_serial_id (
    847     TALER_ARL_edb,
    848     TALER_ARL_USE_PP (aml_history_serial_id),
    849     &check_decision_cb,
    850     NULL);
    851   if (0 > qs)
    852   {
    853     GNUNET_break (GNUNET_DB_STATUS_SOFT_ERROR == qs);
    854     return qs;
    855   }
    856   if (0 > global_qs)
    857     return global_qs;
    858   GNUNET_log (GNUNET_ERROR_TYPE_INFO,
    859               "Analyzed %d AML decisions\n",
    860               (int) qs);
    861 
    862   /* Runs after the decisions: an outcome an AML officer signed is accounted
    863      for by the `aml_history' row we just judged, so leaving that judgement
    864      for a later round would report the outcome against an incomplete
    865      picture. */
    866   qs = TALER_EXCHANGEDB_iterate_legitimization_outcomes_above_serial_id (
    867     TALER_ARL_edb,
    868     TALER_ARL_USE_PP (legitimization_outcome_serial_id),
    869     &check_outcome_cb,
    870     NULL);
    871   if (0 > qs)
    872   {
    873     GNUNET_break (GNUNET_DB_STATUS_SOFT_ERROR == qs);
    874     return qs;
    875   }
    876   if (0 > global_qs)
    877     return global_qs;
    878   GNUNET_log (GNUNET_ERROR_TYPE_INFO,
    879               "Analyzed %d legitimization outcomes\n",
    880               (int) qs);
    881   /* Insert first (a no-op once the rows exist), then update: the three
    882      progress points are written on the very first round as well as on
    883      every later one.  Branching on @e had_pp instead would leave the
    884      rows uncreated for ever, and the helper would re-audit the whole
    885      history every time it woke up. */
    886   qs = TALER_AUDITORDB_insert_auditor_progress (
    887     TALER_ARL_adb,
    888     TALER_ARL_SET_PP (aml_history_serial_id),
    889     TALER_ARL_SET_PP (aml_staff_uuid),
    890     TALER_ARL_SET_PP (legitimization_outcome_serial_id),
    891     NULL);
    892   if (0 > qs)
    893   {
    894     GNUNET_log (GNUNET_ERROR_TYPE_INFO,
    895                 "Failed to update auditor DB, not recording progress\n");
    896     GNUNET_break (GNUNET_DB_STATUS_SOFT_ERROR == qs);
    897     return qs;
    898   }
    899   return GNUNET_DB_STATUS_SUCCESS_ONE_RESULT;
    900 }
    901 
    902 
    903 /**
    904  * Function called when the exchange recorded an AML staff status change or
    905  * an AML decision.  Re-runs the analysis.
    906  *
    907  * @param cls NULL
    908  * @param extra additional event data provided
    909  * @param extra_size number of bytes in @a extra
    910  */
    911 static void
    912 db_notify (void *cls,
    913            const void *extra,
    914            size_t extra_size)
    915 {
    916   (void) cls;
    917   (void) extra;
    918   (void) extra_size;
    919   GNUNET_log (GNUNET_ERROR_TYPE_INFO,
    920               "Received notification for new AML data\n");
    921   if (GNUNET_OK !=
    922       TALER_ARL_setup_sessions_and_run (&analyze_aml,
    923                                         NULL))
    924   {
    925     GNUNET_log (GNUNET_ERROR_TYPE_ERROR,
    926                 "Audit failed\n");
    927     GNUNET_SCHEDULER_shutdown ();
    928     global_ret = EXIT_FAILURE;
    929     return;
    930   }
    931 }
    932 
    933 
    934 /**
    935  * Function called on shutdown.
    936  *
    937  * @param cls NULL
    938  */
    939 static void
    940 do_shutdown (void *cls)
    941 {
    942   (void) cls;
    943   if (NULL != eh)
    944   {
    945     TALER_AUDITORDB_event_listen_cancel (eh);
    946     eh = NULL;
    947   }
    948   clear_staff_map ();
    949   TALER_ARL_done ();
    950 }
    951 
    952 
    953 /**
    954  * Main function that will be run.
    955  *
    956  * @param cls closure
    957  * @param args remaining command-line arguments
    958  * @param cfgfile name of the configuration file used (for saving, can be NULL!)
    959  * @param c configuration
    960  */
    961 static void
    962 run (void *cls,
    963      char *const *args,
    964      const char *cfgfile,
    965      const struct GNUNET_CONFIGURATION_Handle *c)
    966 {
    967   (void) cls;
    968   (void) args;
    969   (void) cfgfile;
    970   cfg = c;
    971   GNUNET_SCHEDULER_add_shutdown (&do_shutdown,
    972                                  NULL);
    973   GNUNET_log (GNUNET_ERROR_TYPE_DEBUG,
    974               "Launching AML auditor\n");
    975   if (EXIT_SUCCESS !=
    976       (global_ret = TALER_ARL_init (c)))
    977   {
    978     return;
    979   }
    980   if (test_mode != 1)
    981   {
    982     struct GNUNET_DB_EventHeaderP es = {
    983       .size = htons (sizeof (es)),
    984       .type = htons (TALER_DBEVENT_EXCHANGE_AUDITOR_WAKE_HELPER_AML)
    985     };
    986 
    987     GNUNET_log (GNUNET_ERROR_TYPE_INFO,
    988                 "Running helper indefinitely\n");
    989     eh = TALER_AUDITORDB_event_listen (TALER_ARL_adb,
    990                                        &es,
    991                                        GNUNET_TIME_UNIT_FOREVER_REL,
    992                                        &db_notify,
    993                                        NULL);
    994   }
    995   GNUNET_log (GNUNET_ERROR_TYPE_DEBUG,
    996               "Starting audit\n");
    997   if (GNUNET_OK !=
    998       TALER_ARL_setup_sessions_and_run (&analyze_aml,
    999                                         NULL))
   1000   {
   1001     GNUNET_SCHEDULER_shutdown ();
   1002     global_ret = EXIT_FAILURE;
   1003     return;
   1004   }
   1005 }
   1006 
   1007 
   1008 /**
   1009  * The main function of the AML auditing helper tool.
   1010  *
   1011  * @param argc number of arguments from the command line
   1012  * @param argv command line arguments
   1013  * @return 0 ok, 1 on error
   1014  */
   1015 int
   1016 main (int argc,
   1017       char *const *argv)
   1018 {
   1019   const struct GNUNET_GETOPT_CommandLineOption options[] = {
   1020     GNUNET_GETOPT_option_flag ('i',
   1021                                "internal",
   1022                                "perform checks only applicable for exchange-internal audits",
   1023                                &internal_checks),
   1024     GNUNET_GETOPT_option_flag ('t',
   1025                                "test",
   1026                                "run in test mode and exit when idle",
   1027                                &test_mode),
   1028     GNUNET_GETOPT_option_timetravel ('T',
   1029                                      "timetravel"),
   1030     GNUNET_GETOPT_OPTION_END
   1031   };
   1032   enum GNUNET_GenericReturnValue ret;
   1033 
   1034   ret = GNUNET_PROGRAM_run (
   1035     TALER_AUDITOR_project_data (),
   1036     argc,
   1037     argv,
   1038     "taler-helper-auditor-aml",
   1039     gettext_noop (
   1040       "Audit exchange database for AML decisions made by unauthorised staff"),
   1041     options,
   1042     &run,
   1043     NULL);
   1044   if (GNUNET_SYSERR == ret)
   1045     return EXIT_NOTCONFIGURED;
   1046   if (GNUNET_NO == ret)
   1047     return EXIT_SUCCESS;
   1048   return global_ret;
   1049 }
   1050 
   1051 
   1052 /* end of taler-helper-auditor-aml.c */