anastasis_api_redux.h (11797B)
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 reducer/anastasis_api_redux.h 18 * @brief anastasis reducer api, internal data structures 19 * @author Christian Grothoff 20 * @author Dominik Meister 21 * @author Dennis Neufeld 22 */ 23 #ifndef ANASTASIS_API_REDUX_H 24 #define ANASTASIS_API_REDUX_H 25 26 27 #define ANASTASIS_GENERIC_STATES(REDUX_STATE) \ 28 REDUX_STATE (INVALID) \ 29 REDUX_STATE (CONTINENT_SELECTING) \ 30 REDUX_STATE (COUNTRY_SELECTING) \ 31 REDUX_STATE (USER_ATTRIBUTES_COLLECTING) 32 33 #define GENERATE_GENERIC_ENUM(ENUM) ANASTASIS_GENERIC_STATE_ ## ENUM, 34 35 enum ANASTASIS_GenericState 36 { 37 ANASTASIS_GENERIC_STATES (GENERATE_GENERIC_ENUM) 38 }; 39 40 #undef GENERATE_GENERIC_ENUM 41 42 #define ANASTASIS_BACKUP_STATES(REDUX_STATE) \ 43 ANASTASIS_GENERIC_STATES (REDUX_STATE) \ 44 REDUX_STATE (AUTHENTICATIONS_EDITING) \ 45 REDUX_STATE (POLICIES_REVIEWING) \ 46 REDUX_STATE (SECRET_EDITING) \ 47 REDUX_STATE (TRUTHS_PAYING) \ 48 REDUX_STATE (POLICIES_PAYING) \ 49 REDUX_STATE (BACKUP_FINISHED) 50 51 #define GENERATE_BACKUP_ENUM(ENUM) ANASTASIS_BACKUP_STATE_ ## ENUM, 52 53 enum ANASTASIS_BackupState 54 { 55 ANASTASIS_BACKUP_STATES (GENERATE_BACKUP_ENUM) 56 }; 57 58 #undef GENERATE_BACKUP_ENUM 59 60 #define ANASTASIS_RECOVERY_STATES(REDUX_STATE) \ 61 ANASTASIS_GENERIC_STATES (REDUX_STATE) \ 62 REDUX_STATE (SECRET_SELECTING) \ 63 REDUX_STATE (CHALLENGE_SELECTING) \ 64 REDUX_STATE (CHALLENGE_PAYING) \ 65 REDUX_STATE (CHALLENGE_SOLVING) \ 66 REDUX_STATE (RECOVERY_FINISHED) 67 68 #define GENERATE_RECOVERY_ENUM(ENUM) ANASTASIS_RECOVERY_STATE_ ## ENUM, 69 70 enum ANASTASIS_RecoveryState 71 { 72 ANASTASIS_RECOVERY_STATES (GENERATE_RECOVERY_ENUM) 73 }; 74 75 #undef GENERATE_RECOVERY_ENUM 76 77 78 /** 79 * CURL context to be used by all operations. 80 */ 81 extern struct GNUNET_CURL_Context *ANASTASIS_REDUX_ctx_; 82 83 84 /** 85 * Initialize reducer subsystem. 86 * 87 * @param ctx context to use for CURL requests. 88 */ 89 void 90 ANASTASIS_redux_init (struct GNUNET_CURL_Context *ctx); 91 92 93 /** 94 * Terminate reducer subsystem. 95 */ 96 void 97 ANASTASIS_redux_done (void); 98 99 100 /** 101 * Produce an initial state with an initialized list of 102 * continents. 103 * 104 * @return list of continents 105 */ 106 json_t * 107 ANASTASIS_REDUX_load_continents_ (void); 108 109 110 /** 111 * Try to obtain configuration information on all configured 112 * providers. Upon success, call @a cb with the updated provider 113 * status data. 114 * 115 * @param[in] state we are in 116 * @param arguments our arguments with the solution 117 * @param cb functiont o call with the new state 118 * @param cb_cls closure for @a cb 119 * @return handle to cancel challenge selection step 120 */ 121 struct ANASTASIS_ReduxAction * 122 ANASTASIS_REDUX_poll_providers_ (json_t *state, 123 const json_t *arguments, 124 ANASTASIS_ActionCallback cb, 125 void *cb_cls); 126 127 128 /** 129 * Check if we have information on all providers involved in 130 * a recovery procedure, and if not, try to obtain it. Upon 131 * success, call @a cb with the updated provider status data. 132 * 133 * @param[in] state we are in 134 * @param arguments our arguments with the solution 135 * @param cb functiont o call with the new state 136 * @param cb_cls closure for @a cb 137 * @return handle to cancel challenge selection step 138 */ 139 struct ANASTASIS_ReduxAction * 140 ANASTASIS_REDUX_sync_providers_ (json_t *state, 141 const json_t *arguments, 142 ANASTASIS_ActionCallback cb, 143 void *cb_cls); 144 145 146 /** 147 * Returns the enum value to a string value of a state. 148 * 149 * @param state_string string to convert 150 * @return ANASTASIS_GENERIC_STATE_ERROR on error 151 */ 152 enum ANASTASIS_GenericState 153 ANASTASIS_generic_state_from_string_ (const char *state_string); 154 155 156 /** 157 * Returns the string value of a state. 158 * 159 * @param gs state value to convert 160 * @return NULL on error 161 */ 162 const char * 163 ANASTASIS_generic_state_to_string_ (enum ANASTASIS_GenericState gs); 164 165 166 /** 167 * Returns the enum value to a string value of a state. 168 * 169 * @param state_string string to convert 170 * @return ANASTASIS_BACKUP_STATE_ERROR on error 171 */ 172 enum ANASTASIS_BackupState 173 ANASTASIS_backup_state_from_string_ (const char *state_string); 174 175 176 /** 177 * Returns the string value of a state. 178 * 179 * @param bs state to convert to a string 180 * @return NULL on error 181 */ 182 const char * 183 ANASTASIS_backup_state_to_string_ (enum ANASTASIS_BackupState bs); 184 185 186 /** 187 * Returns the enum value to a string value of a state. 188 * 189 * @param state_string value to convert 190 * @return ANASTASIS_RECOVERY_STATE_ERROR on error 191 */ 192 enum ANASTASIS_RecoveryState 193 ANASTASIS_recovery_state_from_string_ (const char *state_string); 194 195 196 /** 197 * Returns the string value of a state. 198 * 199 * @param rs value to convert 200 * @return NULL on error 201 */ 202 const char * 203 ANASTASIS_recovery_state_to_string_ (enum ANASTASIS_RecoveryState rs); 204 205 206 /** 207 * Lookup @a salt of @a provider_url in @a state. 208 * 209 * @param state the state to inspect 210 * @param provider_url provider to look into 211 * @param[out] salt value to extract 212 * @return #GNUNET_OK on success 213 */ 214 enum GNUNET_GenericReturnValue 215 ANASTASIS_reducer_lookup_salt (const json_t *state, 216 const char *provider_url, 217 struct ANASTASIS_CRYPTO_ProviderSaltP *salt); 218 219 220 /** 221 * Function to return a json error response. 222 * 223 * @param cb callback to give error to 224 * @param cb_cls callback closure 225 * @param ec error code 226 * @param detail error detail 227 */ 228 void 229 ANASTASIS_redux_fail_ (ANASTASIS_ActionCallback cb, 230 void *cb_cls, 231 enum TALER_ErrorCode ec, 232 const char *detail); 233 234 235 /** 236 * DispatchHandler/Callback function which is called for a 237 * "add_provider" action. Adds another Anastasis provider 238 * to the list of available providers for storing information. 239 * 240 * @param state state to operate on 241 * @param arguments arguments with a provider URL to add 242 * @param cb callback to call during/after operation 243 * @param cb_cls callback closure 244 * @return true if @a cb was invoked 245 */ 246 bool 247 ANASTASIS_add_provider_ (json_t *state, 248 const json_t *arguments, 249 ANASTASIS_ActionCallback cb, 250 void *cb_cls); 251 252 253 /** 254 * Adds the server configuration of the Anastasis provider 255 * at @a url to the json @a state. Checks if we have 256 * the provider information already available. If so, 257 * imports it into @a state. If not, queries the provider, 258 * generating a success or failure outcome asynchronously. 259 * 260 * @param url the provider's base URL to add 261 * @param[in,out] state the json state to operate on 262 * @param cb callback to call during/after operation 263 * @param cb_cls callback closure 264 * @return handle to cancel asynchronous operation, NULL if 265 * we completed synchronously 266 */ 267 struct ANASTASIS_ReduxAction * 268 ANASTASIS_REDUX_add_provider_to_state_ (const char *url, 269 json_t *state, 270 ANASTASIS_ActionCallback cb, 271 void *cb_cls); 272 273 274 /** 275 * A generic DispatchHandler/Callback function which is called for a 276 * "back" action. 277 * 278 * @param[in,out] state state to operate on 279 * @param arguments arguments to use for operation on state 280 * @param cb callback to call during/after operation 281 * @param cb_cls callback closure for @a cb 282 * @return NULL (no asynchronous action) 283 */ 284 struct ANASTASIS_ReduxAction * 285 ANASTASIS_back_generic_decrement_ (json_t *state, 286 const json_t *arguments, 287 ANASTASIS_ActionCallback cb, 288 void *cb_cls); 289 290 291 /** 292 * Function to load json containing all countries. 293 * Returns the countries. 294 * 295 * @return list of countries 296 */ 297 const json_t * 298 ANASTASIS_redux_countries_init_ (void); 299 300 301 /** 302 * Operates on a recovery state. The new state is returned 303 * by a callback function. 304 * This function can do network access to talk to anastasis service providers. 305 * 306 * @param[in,out] state input/output state (to be modified) 307 * @param action what action to perform 308 * @param arguments data for the @a action 309 * @param cb function to call with the result 310 * @param cb_cls closure for @a cb 311 */ 312 struct ANASTASIS_ReduxAction * 313 ANASTASIS_recovery_action_ (json_t *state, 314 const char *action, 315 const json_t *arguments, 316 ANASTASIS_ActionCallback cb, 317 void *cb_cls); 318 319 320 /** 321 * DispatchHandler/Callback function which is called for a 322 * "enter_user_attributes" action after verifying that the 323 * arguments provided were OK and the state transition was 324 * initiated. Begins the actual recovery logic. 325 * 326 * Returns an #ANASTASIS_ReduxAction. 327 * 328 * @param state state to operate on 329 * @param arguments data for the operation 330 * @param cb callback to call during/after operation 331 * @param cb_cls callback closure for @a cb 332 * @return NULL 333 */ 334 struct ANASTASIS_ReduxAction * 335 ANASTASIS_REDUX_recovery_challenge_begin_ (json_t *state, 336 const json_t *arguments, 337 ANASTASIS_ActionCallback cb, 338 void *cb_cls); 339 340 341 /** 342 * DispatchHandler/Callback function which is called for a 343 * "enter_user_attributes" action after verifying that the 344 * arguments provided were OK and the state transition was 345 * initiated. Begins the actual backup logic. 346 * 347 * Returns a `struct ANASTASIS_ReduxAction`. 348 * 349 * @param state state to operate on 350 * @param arguments data for the operation 351 * @param cb callback to call during/after operation 352 * @param cb_cls callback closure 353 */ 354 struct ANASTASIS_ReduxAction * 355 ANASTASIS_REDUX_backup_begin_ (json_t *state, 356 const json_t *arguments, 357 ANASTASIS_ActionCallback cb, 358 void *cb_cls); 359 360 361 /** 362 * Operates on a backup state and returns the new state via a 363 * callback function. 364 * This function can do network access to talk to anastasis service providers. 365 * 366 * @param[in,out] state input/output state (to be modified) 367 * @param action what action to perform 368 * @param arguments data for the @a action 369 * @param cb function to call with the result 370 * @param cb_cls closure for @a cb 371 */ 372 struct ANASTASIS_ReduxAction * 373 ANASTASIS_backup_action_ (json_t *state, 374 const char *action, 375 const json_t *arguments, 376 ANASTASIS_ActionCallback cb, 377 void *cb_cls); 378 379 380 /** 381 * Check if an external reducer binary is requested. 382 * Cache the result and unset the corresponding environment 383 * variable. 384 * 385 * @returns name of the external reducer or NULL to user internal reducer 386 */ 387 const char * 388 ANASTASIS_REDUX_probe_external_reducer (void); 389 390 /** 391 * Generic container for an action with asynchronous activities. 392 */ 393 struct ANASTASIS_ReduxAction 394 { 395 /** 396 * Function to call to clean up. 397 */ 398 void (*cleanup)(void *cls); 399 400 /** 401 * Action-specific state, closure for @e cleanup. 402 */ 403 void *cleanup_cls; 404 }; 405 406 407 #endif