anastasis_api_redux.h (14668B)
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 * The typed state the reducer operates on internally; see 28 * `anastasis_api_redux_state.h`, which includes this header. 29 */ 30 struct ANASTASIS_ReduxState; 31 32 /** 33 * Fields the backup and recovery variants of a state share. 34 */ 35 struct ANASTASIS_ReduxCommon; 36 37 /** 38 * Signature of the callback used to hand a typed state back to whoever 39 * started an asynchronous step inside the reducer. The mirror image of 40 * #ANASTASIS_ActionCallback, which is what the same result eventually 41 * becomes once it leaves the reducer. 42 * 43 * Unlike the callback APIs in `anastasis.h` this one does not declare an 44 * overridable closure type: its closure is almost always the opaque 45 * `cb_cls` of the public action the reducer is in the middle of 46 * executing, which by construction has no type to name here. 47 * 48 * @param cls closure 49 * @param ec status of the step 50 * @param[in,out] rs the state that was passed in, updated in place; 51 * ownership is *not* transferred by this call 52 */ 53 typedef void 54 (*ANASTASIS_REDUX_StateCallback)(void *cls, 55 enum TALER_ErrorCode ec, 56 struct ANASTASIS_ReduxState *rs); 57 58 59 #define ANASTASIS_GENERIC_STATES(REDUX_STATE) \ 60 REDUX_STATE (INVALID) \ 61 REDUX_STATE (CONTINENT_SELECTING) \ 62 REDUX_STATE (COUNTRY_SELECTING) \ 63 REDUX_STATE (USER_ATTRIBUTES_COLLECTING) 64 65 #define GENERATE_GENERIC_ENUM(ENUM) ANASTASIS_GENERIC_STATE_ ## ENUM, 66 67 enum ANASTASIS_GenericState 68 { 69 ANASTASIS_GENERIC_STATES (GENERATE_GENERIC_ENUM) 70 }; 71 72 #undef GENERATE_GENERIC_ENUM 73 74 #define ANASTASIS_BACKUP_STATES(REDUX_STATE) \ 75 ANASTASIS_GENERIC_STATES (REDUX_STATE) \ 76 REDUX_STATE (AUTHENTICATIONS_EDITING) \ 77 REDUX_STATE (POLICIES_REVIEWING) \ 78 REDUX_STATE (SECRET_EDITING) \ 79 REDUX_STATE (TRUTHS_PAYING) \ 80 REDUX_STATE (POLICIES_PAYING) \ 81 REDUX_STATE (BACKUP_FINISHED) 82 83 #define GENERATE_BACKUP_ENUM(ENUM) ANASTASIS_BACKUP_STATE_ ## ENUM, 84 85 enum ANASTASIS_BackupState 86 { 87 ANASTASIS_BACKUP_STATES (GENERATE_BACKUP_ENUM) 88 }; 89 90 #undef GENERATE_BACKUP_ENUM 91 92 #define ANASTASIS_RECOVERY_STATES(REDUX_STATE) \ 93 ANASTASIS_GENERIC_STATES (REDUX_STATE) \ 94 REDUX_STATE (SECRET_SELECTING) \ 95 REDUX_STATE (CHALLENGE_SELECTING) \ 96 REDUX_STATE (CHALLENGE_PAYING) \ 97 REDUX_STATE (CHALLENGE_SOLVING) \ 98 REDUX_STATE (RECOVERY_FINISHED) 99 100 #define GENERATE_RECOVERY_ENUM(ENUM) ANASTASIS_RECOVERY_STATE_ ## ENUM, 101 102 enum ANASTASIS_RecoveryState 103 { 104 ANASTASIS_RECOVERY_STATES (GENERATE_RECOVERY_ENUM) 105 }; 106 107 #undef GENERATE_RECOVERY_ENUM 108 109 110 /** 111 * CURL context to be used by all operations. 112 */ 113 extern struct GNUNET_CURL_Context *ANASTASIS_REDUX_ctx_; 114 115 116 /** 117 * Initialize reducer subsystem. 118 * 119 * @param ctx context to use for CURL requests. 120 */ 121 void 122 ANASTASIS_redux_init (struct GNUNET_CURL_Context *ctx); 123 124 125 /** 126 * Terminate reducer subsystem. 127 */ 128 void 129 ANASTASIS_redux_done (void); 130 131 132 /** 133 * Produce an initial state with an initialized list of 134 * continents. 135 * 136 * @return list of continents 137 */ 138 json_t * 139 ANASTASIS_REDUX_load_continents_ (void); 140 141 142 /** 143 * Try to obtain configuration information on all configured 144 * providers. Upon success, call @a cb with the updated provider 145 * status data. 146 * 147 * @param[in] rs state we are in 148 * @param arguments our arguments with the solution 149 * @param cb functiont o call with the new state 150 * @param cb_cls closure for @a cb 151 * @return handle to cancel challenge selection step 152 */ 153 struct ANASTASIS_ReduxAction * 154 ANASTASIS_REDUX_poll_providers_ (struct ANASTASIS_ReduxState *rs, 155 const json_t *arguments, 156 ANASTASIS_ActionCallback cb, 157 void *cb_cls); 158 159 160 /** 161 * Check if we have information on all providers involved in 162 * a recovery procedure, and if not, try to obtain it. Upon 163 * success, call @a cb with the updated provider status data. 164 * 165 * @param[in] rs state we are in 166 * @param arguments our arguments with the solution 167 * @param cb functiont o call with the new state 168 * @param cb_cls closure for @a cb 169 * @return handle to cancel challenge selection step 170 */ 171 struct ANASTASIS_ReduxAction * 172 ANASTASIS_REDUX_sync_providers_ (struct ANASTASIS_ReduxState *rs, 173 const json_t *arguments, 174 ANASTASIS_ActionCallback cb, 175 void *cb_cls); 176 177 178 /** 179 * Returns the enum value to a string value of a state. 180 * 181 * @param state_string string to convert 182 * @return ANASTASIS_GENERIC_STATE_ERROR on error 183 */ 184 enum ANASTASIS_GenericState 185 ANASTASIS_generic_state_from_string_ (const char *state_string); 186 187 188 /** 189 * Returns the string value of a state. 190 * 191 * @param gs state value to convert 192 * @return NULL on error 193 */ 194 const char * 195 ANASTASIS_generic_state_to_string_ (enum ANASTASIS_GenericState gs); 196 197 198 /** 199 * Returns the enum value to a string value of a state. 200 * 201 * @param state_string string to convert 202 * @return ANASTASIS_BACKUP_STATE_ERROR on error 203 */ 204 enum ANASTASIS_BackupState 205 ANASTASIS_backup_state_from_string_ (const char *state_string); 206 207 208 /** 209 * Returns the string value of a state. 210 * 211 * @param bs state to convert to a string 212 * @return NULL on error 213 */ 214 const char * 215 ANASTASIS_backup_state_to_string_ (enum ANASTASIS_BackupState bs); 216 217 218 /** 219 * Returns the enum value to a string value of a state. 220 * 221 * @param state_string value to convert 222 * @return ANASTASIS_RECOVERY_STATE_ERROR on error 223 */ 224 enum ANASTASIS_RecoveryState 225 ANASTASIS_recovery_state_from_string_ (const char *state_string); 226 227 228 /** 229 * Returns the string value of a state. 230 * 231 * @param rs value to convert 232 * @return NULL on error 233 */ 234 const char * 235 ANASTASIS_recovery_state_to_string_ (enum ANASTASIS_RecoveryState rs); 236 237 238 /** 239 * Lookup @a salt of @a provider_url in @a state. 240 * 241 * @param state the state to inspect 242 * @param provider_url provider to look into 243 * @param[out] salt value to extract 244 * @return #GNUNET_OK on success 245 */ 246 enum GNUNET_GenericReturnValue 247 ANASTASIS_reducer_lookup_salt (const json_t *state, 248 const char *provider_url, 249 struct ANASTASIS_CRYPTO_ProviderSaltP *salt); 250 251 252 /** 253 * Lookup @a salt of @a provider_url in @a common. The typed 254 * counterpart of #ANASTASIS_reducer_lookup_salt(), which stays around 255 * for the public discovery API. 256 * 257 * @param common the state to inspect 258 * @param provider_url provider to look into 259 * @param[out] salt value to extract 260 * @return #GNUNET_OK on success, 261 * #GNUNET_NO if the provider is disabled or has no /config, 262 * #GNUNET_SYSERR if the provider is not in @a common at all 263 */ 264 enum GNUNET_GenericReturnValue 265 ANASTASIS_REDUX_lookup_salt_ (const struct ANASTASIS_ReduxCommon *common, 266 const char *provider_url, 267 struct ANASTASIS_CRYPTO_ProviderSaltP *salt); 268 269 270 /** 271 * Function to return a json error response. 272 * 273 * @param cb callback to give error to 274 * @param cb_cls callback closure 275 * @param ec error code 276 * @param detail error detail 277 */ 278 void 279 ANASTASIS_redux_fail_ (ANASTASIS_ActionCallback cb, 280 void *cb_cls, 281 enum TALER_ErrorCode ec, 282 const char *detail); 283 284 285 /** 286 * DispatchHandler/Callback function which is called for a 287 * "add_provider" action. Adds another Anastasis provider 288 * to the list of available providers for storing information. 289 * 290 * @param[in] rs state to operate on 291 * @param arguments arguments with a provider URL to add 292 * @param cb callback to call during/after operation 293 * @param cb_cls callback closure 294 * @return true if @a cb was invoked 295 */ 296 bool 297 ANASTASIS_add_provider_ (struct ANASTASIS_ReduxState *rs, 298 const json_t *arguments, 299 ANASTASIS_ActionCallback cb, 300 void *cb_cls); 301 302 303 /** 304 * Adds the server configuration of the Anastasis provider 305 * at @a url to the json @a state. Checks if we have 306 * the provider information already available. If so, 307 * imports it into @a state. If not, queries the provider, 308 * generating a success or failure outcome asynchronously. 309 * 310 * @param url the provider's base URL to add 311 * @param[in,out] rs the state to update in place; borrowed, 312 * the caller must keep it alive until it cancels the operation 313 * @param cb callback to call during/after operation 314 * @param cb_cls callback closure 315 * @return handle to cancel asynchronous operation, NULL if 316 * we completed synchronously 317 */ 318 struct ANASTASIS_ReduxAction * 319 ANASTASIS_REDUX_add_provider_to_state_ (const char *url, 320 struct ANASTASIS_ReduxState *rs, 321 ANASTASIS_REDUX_StateCallback cb, 322 void *cb_cls); 323 324 325 /** 326 * Add the provider at @a url to @a rs and return the updated state to 327 * the application. The whole of the "add_provider" action, for the 328 * state variants that have nothing else to do afterwards. 329 * 330 * @param url the provider's base URL to add 331 * @param[in] rs state to operate on; we take ownership 332 * @param cb callback to call with the new state 333 * @param cb_cls closure for @a cb 334 * @return handle to cancel the asynchronous operation 335 */ 336 struct ANASTASIS_ReduxAction * 337 ANASTASIS_REDUX_provider_add_ (const char *url, 338 struct ANASTASIS_ReduxState *rs, 339 ANASTASIS_ActionCallback cb, 340 void *cb_cls); 341 342 343 /** 344 * A generic DispatchHandler/Callback function which is called for a 345 * "back" action. 346 * 347 * @param[in] rs state to operate on 348 * @param arguments arguments to use for operation on state 349 * @param cb callback to call during/after operation 350 * @param cb_cls callback closure for @a cb 351 * @return NULL (no asynchronous action) 352 */ 353 struct ANASTASIS_ReduxAction * 354 ANASTASIS_back_generic_decrement_ (struct ANASTASIS_ReduxState *rs, 355 const json_t *arguments, 356 ANASTASIS_ActionCallback cb, 357 void *cb_cls); 358 359 360 /** 361 * Function to load json containing all countries. 362 * Returns the countries. 363 * 364 * @return list of countries 365 */ 366 const json_t * 367 ANASTASIS_redux_countries_init_ (void); 368 369 370 /** 371 * Operates on a recovery state. The new state is returned 372 * by a callback function. 373 * This function can do network access to talk to anastasis service providers. 374 * 375 * @param[in] rs state to operate on 376 * @param action what action to perform 377 * @param arguments data for the @a action 378 * @param cb function to call with the result 379 * @param cb_cls closure for @a cb 380 */ 381 struct ANASTASIS_ReduxAction * 382 ANASTASIS_recovery_action_ (struct ANASTASIS_ReduxState *rs, 383 const char *action, 384 const json_t *arguments, 385 ANASTASIS_ActionCallback cb, 386 void *cb_cls); 387 388 389 /** 390 * DispatchHandler/Callback function which is called for a 391 * "enter_user_attributes" action after verifying that the 392 * arguments provided were OK and the state transition was 393 * initiated. Begins the actual recovery logic. 394 * 395 * Returns an #ANASTASIS_ReduxAction. 396 * 397 * @param[in] rs state to operate on 398 * @param arguments data for the operation 399 * @param cb callback to call during/after operation 400 * @param cb_cls callback closure for @a cb 401 * @return NULL 402 */ 403 struct ANASTASIS_ReduxAction * 404 ANASTASIS_REDUX_recovery_challenge_begin_ (struct ANASTASIS_ReduxState *rs, 405 const json_t *arguments, 406 ANASTASIS_ActionCallback cb, 407 void *cb_cls); 408 409 410 /** 411 * DispatchHandler/Callback function which is called for a 412 * "enter_user_attributes" action after verifying that the 413 * arguments provided were OK and the state transition was 414 * initiated. Begins the actual backup logic. 415 * 416 * Returns a `struct ANASTASIS_ReduxAction`. 417 * 418 * @param[in] rs state to operate on 419 * @param arguments data for the operation 420 * @param cb callback to call during/after operation 421 * @param cb_cls callback closure 422 */ 423 struct ANASTASIS_ReduxAction * 424 ANASTASIS_REDUX_backup_begin_ (struct ANASTASIS_ReduxState *rs, 425 const json_t *arguments, 426 ANASTASIS_ActionCallback cb, 427 void *cb_cls); 428 429 430 /** 431 * Operates on a backup state and returns the new state via a 432 * callback function. 433 * This function can do network access to talk to anastasis service providers. 434 * 435 * @param[in] rs state to operate on 436 * @param action what action to perform 437 * @param arguments data for the @a action 438 * @param cb function to call with the result 439 * @param cb_cls closure for @a cb 440 */ 441 struct ANASTASIS_ReduxAction * 442 ANASTASIS_backup_action_ (struct ANASTASIS_ReduxState *rs, 443 const char *action, 444 const json_t *arguments, 445 ANASTASIS_ActionCallback cb, 446 void *cb_cls); 447 448 449 /** 450 * Check if an external reducer binary is requested. 451 * Cache the result and unset the corresponding environment 452 * variable. 453 * 454 * @returns name of the external reducer or NULL to user internal reducer 455 */ 456 const char * 457 ANASTASIS_REDUX_probe_external_reducer (void); 458 459 /** 460 * Generic container for an action with asynchronous activities. 461 */ 462 struct ANASTASIS_ReduxAction 463 { 464 /** 465 * Function to call to clean up. 466 */ 467 void (*cleanup)(void *cls); 468 469 /** 470 * Action-specific state, closure for @e cleanup. 471 */ 472 void *cleanup_cls; 473 }; 474 475 476 #endif