anastasis_redux.h (6884B)
1 /* 2 This file is part of Anastasis 3 Copyright (C) 2020, 2021 Anastasis SARL 4 5 Anastasis is free software; you can redistribute it and/or modify it under the 6 terms of the GNU General Public License as published by the Free Software 7 Foundation; either version 3, or (at your option) any later version. 8 9 Anastasis 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 General Public License for more details. 12 13 You should have received a copy of the GNU General Public License along with 14 Anastasis; see the file COPYING.GPL. If not, see <http://www.gnu.org/licenses/> 15 */ 16 /** 17 * @file include/anastasis_redux.h 18 * @brief anastasis reducer api 19 * @author Christian Grothoff 20 * @author Dominik Meister 21 * @author Dennis Neufeld 22 */ 23 #ifndef ANASTASIS_REDUX_H 24 #define ANASTASIS_REDUX_H 25 26 #include <jansson.h> 27 #include "anastasis.h" 28 #include <taler/taler_mhd_lib.h> 29 #include <regex.h> 30 31 32 /** 33 * Initialize reducer subsystem. 34 * 35 * @param ctx context to use for CURL requests. 36 */ 37 void 38 ANASTASIS_redux_init (struct GNUNET_CURL_Context *ctx); 39 40 41 /** 42 * Terminate reducer subsystem. 43 */ 44 void 45 ANASTASIS_redux_done (void); 46 47 48 /** 49 * Returns an initial ANASTASIS backup state. 50 * 51 * @return NULL on failure 52 */ 53 json_t * 54 ANASTASIS_backup_start (const struct GNUNET_CONFIGURATION_Handle *cfg); 55 56 57 /** 58 * Returns an initial ANASTASIS recovery state. 59 * 60 * @return NULL on failure 61 */ 62 json_t * 63 ANASTASIS_recovery_start (const struct GNUNET_CONFIGURATION_Handle *cfg); 64 65 66 /** 67 * Signature of the callback passed to #ANASTASIS_redux_action() 68 * 69 * @param cls closure 70 * @param error error code, #TALER_EC_NONE if @a new_bs is the new successful state 71 * @param new_state the new state of the operation (client should json_incref() to keep an alias) 72 */ 73 typedef void 74 (*ANASTASIS_ActionCallback)(void *cls, 75 enum TALER_ErrorCode error, 76 json_t *new_state); 77 78 79 /** 80 * Handle to an ongoing action. Only valid until the #ANASTASIS_ActionCallback is invoked. 81 */ 82 struct ANASTASIS_ReduxAction; 83 84 85 /** 86 * Operates on a state. The new state is returned by a callback 87 * function. This function can do network access to talk to Anastasis 88 * service providers. 89 * 90 * @param state input state 91 * @param action what action to perform 92 * @param arguments data for the @a action 93 * @param cb function to call with the result 94 * @param cb_cls closure for @a cb 95 * @return failure state or new state 96 */ 97 struct ANASTASIS_ReduxAction * 98 ANASTASIS_redux_action (const json_t *state, 99 const char *action, 100 const json_t *arguments, 101 ANASTASIS_ActionCallback cb, 102 void *cb_cls); 103 104 105 /** 106 * Cancel ongoing redux action. 107 * 108 * @param ra action to cancel 109 */ 110 void 111 ANASTASIS_redux_action_cancel (struct ANASTASIS_ReduxAction *ra); 112 113 114 /** 115 * Handle for a policy discovery operation. 116 */ 117 struct ANASTASIS_PolicyDiscovery; 118 119 120 /** 121 * Function called on each discovered recovery policy. 122 * 123 * The client can then start a new policy discovery process, using the 124 * smallest (also most recent) @a version received per @a provider_url 125 * in the cursor to resume. Note that in this case, the application 126 * logic is responsible for de-duplication using @a hcpd, or it may show 127 * policies again if they are at different providers under versions not 128 * queried up to the cursor. 129 * 130 * @param cls closure 131 * @param hcpd hash of the compressed policy document (unique per policy) 132 * @param provider_url which provider claims to have this policy 133 * @param version version of the policy at this provider 134 * @param attribute_mask combination of optional identity attributes 135 * present in the state that was used to locate this version 136 * @param server_time when did the provider receive the upload 137 * @param secret_name name the user assigned to the backup 138 * @param providers json array of providers with this policy 139 */ 140 typedef void 141 (*ANASTASIS_PolicyDiscoveryCallback)(void *cls, 142 const struct GNUNET_HashCode *hcpd, 143 const char *provider_url, 144 uint32_t version, 145 json_int_t attribute_mask, 146 struct GNUNET_TIME_Timestamp server_time, 147 const char *secret_name, 148 const json_t *providers); 149 150 151 /** 152 * Start requesting providers for available policies for the 153 * recovery specified in @a state. 154 * 155 * @param state state to discover polices in 156 * @param cursor array containing "provider_url", attribute "mask", 157 * and "max_version" values (max_version is exclusive). 158 * Used for incremental discovery, NULL is allowed 159 * to begin from the latest version(s). 160 * @param cb function to call with results 161 * @param cb_cls closure for @a cb 162 * @return NULL on failure 163 */ 164 struct ANASTASIS_PolicyDiscovery * 165 ANASTASIS_policy_discovery_start (const json_t *state, 166 const json_t *cursor, 167 ANASTASIS_PolicyDiscoveryCallback cb, 168 void *cb_cls); 169 170 171 /** 172 * Add another provider to the list of providers to do discovery 173 * on. 174 * 175 * @param[in,out] pd policy discovery to expand 176 * @param provider_url the provider to add to the set of providers 177 * @param provider_state configuration state for that provider 178 */ 179 void 180 ANASTASIS_policy_discovery_more (struct ANASTASIS_PolicyDiscovery *pd, 181 const char *provider_url, 182 json_t *provider_state); 183 184 /** 185 * Stop policy discovery. 186 * 187 * @param[in] pd operation to stop 188 */ 189 void 190 ANASTASIS_policy_discovery_stop (struct ANASTASIS_PolicyDiscovery *pd); 191 192 193 /** 194 * Compute a subset of @a master_id removing optional attributes 195 * based on the bits set in @a mask. 196 * 197 * @param state reducer state (tells us which attributes are optional) 198 * @param master_id set of identity attributes to mask 199 * @param mask bitmask to apply 200 * @return masked copy of the @a master_id 201 */ 202 json_t * 203 ANASTASIS_mask_id_data (const json_t *state, 204 const json_t *master_id, 205 json_int_t mask); 206 207 /** 208 * Lookup @a salt of @a provider_url in @a state. 209 * 210 * @param state the state to inspect 211 * @param provider_url provider to look into 212 * @param[out] salt value to extract 213 * @return #GNUNET_OK on success 214 */ 215 enum GNUNET_GenericReturnValue 216 ANASTASIS_reducer_lookup_salt (const json_t *state, 217 const char *provider_url, 218 struct ANASTASIS_CRYPTO_ProviderSaltP *salt); 219 220 221 #endif /* _ANASTASIS_REDUX_H */