anastasis_authorization_plugin.h (8970B)
1 /* 2 This file is part of Anastasis 3 Copyright (C) 2019 Anastasis SARL 4 5 Anastasis is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero 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 Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero 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_authorization_plugin.h 18 * @brief authorization access for Anastasis 19 * @author Christian Grothoff 20 */ 21 #ifndef ANASTASIS_AUTHORIZATION_PLUGIN_H 22 #define ANASTASIS_AUTHORIZATION_PLUGIN_H 23 24 #include "anastasis_service.h" 25 #include <taler/taler_util.h> 26 #include <microhttpd.h> 27 28 /** 29 * Plugin-specific state for an authorization operation. 30 */ 31 struct ANASTASIS_AUTHORIZATION_State; 32 33 34 /** 35 * Enumeration values indicating the various possible 36 * outcomes of the plugin's `challenge` function. 37 */ 38 enum ANASTASIS_AUTHORIZATION_ChallengeResult 39 { 40 /** 41 * We successfully sent the authorization challenge 42 * and queued a reply to MHD. 43 */ 44 ANASTASIS_AUTHORIZATION_CRES_SUCCESS = 0, 45 46 /** 47 * We failed to transmit the authorization challenge, 48 * but successfully queued a failure response to MHD. 49 */ 50 ANASTASIS_AUTHORIZATION_CRES_FAILED = 1, 51 52 /** 53 * The plugin suspended the MHD connection as it needs some more 54 * time to do its (asynchronous) work before we can proceed. The 55 * plugin will resume the MHD connection when its work is done, and 56 * then the `process` function should be called again. 57 */ 58 ANASTASIS_AUTHORIZATION_CRES_SUSPENDED = 2, 59 60 /** 61 * The plugin tried to queue a reply on the MHD connection and 62 * failed to do so. We should return #MHD_NO to MHD to cause the 63 * HTTP connection to be closed without any reply. 64 * 65 * However, we were successful at transmitting the challenge, 66 * so the challenge should be marked as sent. 67 */ 68 ANASTASIS_AUTHORIZATION_CRES_SUCCESS_REPLY_FAILED = 4, 69 70 /** 71 * The plugin tried to queue a reply on the MHD connection and 72 * failed to do so. We should return #MHD_NO to MHD to cause the 73 * HTTP connection to be closed without any reply. 74 * 75 * Additionally, we failed to transmit the challenge. 76 */ 77 ANASTASIS_AUTHORIZATION_CRES_FAILED_REPLY_FAILED = 5 78 }; 79 80 81 /** 82 * Enumeration values indicating the various possible 83 * outcomes of the plugin's `solve` function. 84 */ 85 enum ANASTASIS_AUTHORIZATION_SolveResult 86 { 87 /** 88 * We failed to transmit the authorization challenge, 89 * but successfully queued a failure response to MHD. 90 */ 91 ANASTASIS_AUTHORIZATION_SRES_FAILED = 0, 92 93 /** 94 * The plugin suspended the MHD connection as it needs some more 95 * time to do its (asynchronous) work before we can proceed. The 96 * plugin will resume the MHD connection when its work is done, and 97 * then the `process` function should be called again. 98 */ 99 ANASTASIS_AUTHORIZATION_SRES_SUSPENDED = 1, 100 101 /** 102 * The plugin tried to queue a reply on the MHD connection and 103 * failed to do so. We should return #MHD_NO to MHD to cause the 104 * HTTP connection to be closed without any reply. 105 * 106 * Additionally, we failed to transmit the challenge. 107 */ 108 ANASTASIS_AUTHORIZATION_SRES_FAILED_REPLY_FAILED = 2, 109 110 /** 111 * The authentication process completed successfully 112 * and we should signal success to the client by 113 * returning the truth. 114 */ 115 ANASTASIS_AUTHORIZATION_SRES_FINISHED = 3 116 }; 117 118 119 /** 120 * Argument passed to the "init" function of each 121 * plugin. 122 */ 123 struct ANASTASIS_AuthorizationContext 124 { 125 /** 126 * Database handle. 127 */ 128 struct ANASTASIS_DatabasePlugin *db; 129 130 /** 131 * Configuration to use. 132 */ 133 const struct GNUNET_CONFIGURATION_Handle *cfg; 134 }; 135 136 137 /** 138 * Handle to interact with a authorization backend. 139 */ 140 struct ANASTASIS_AuthorizationPlugin 141 { 142 143 /** 144 * Closure for all callbacks. 145 */ 146 void *cls; 147 148 /** 149 * Cost to GET the /truth using this method. Set by the plugin's 150 * loader, not by the plugin itself. 151 */ 152 struct TALER_Amount cost; 153 154 /** 155 * True if the payment is managed internally by the 156 * authorization plugin. 157 */ 158 bool payment_plugin_managed; 159 160 /** 161 * The plugin expects the "code" in the "start" function to be 162 * provided by the user and not generated by the Anastasis 163 * backend. The plugin will then validate the code using its own 164 * means. Used by TOTP. 165 */ 166 bool user_provided_code; 167 168 /** 169 * How often are retries allowed for challenges created 170 * by this plugin? 171 */ 172 uint32_t retry_counter; 173 174 /** 175 * How long should a generated challenge be valid for this type of method. 176 */ 177 struct GNUNET_TIME_Relative code_validity_period; 178 179 /** 180 * How long before we should rotate a challenge for this type of method. 181 */ 182 struct GNUNET_TIME_Relative code_rotation_period; 183 184 /** 185 * How long before we should retransmit a code. 186 */ 187 struct GNUNET_TIME_Relative code_retransmission_frequency; 188 189 /** 190 * Validate @a data is a well-formed input into the challenge method, 191 * i.e. @a data is a well-formed phone number for sending an SMS, or 192 * a well-formed e-mail address for sending an e-mail. Not expected to 193 * check that the phone number or e-mail account actually exists. 194 * 195 * To be possibly used before issuing a 402 payment required to the client. 196 * 197 * @param cls closure 198 * @param connection HTTP client request (for queuing response) 199 * @param truth_mime mime type of @e data 200 * @param data input to validate (i.e. is it a valid phone number, etc.) 201 * @param data_length number of bytes in @a data 202 * @return #GNUNET_OK if @a data is valid, 203 * #GNUNET_NO if @a data is invalid and a reply was successfully queued on @a connection 204 * #GNUNET_SYSERR if @a data invalid but we failed to queue a reply on @a connection 205 */ 206 enum GNUNET_GenericReturnValue 207 (*validate)(void *cls, 208 struct MHD_Connection *connection, 209 const char *truth_mime, 210 const char *data, 211 size_t data_length); 212 213 214 /** 215 * Begin issuing authentication challenge to user based on @a data. 216 * I.e. start to send SMS or e-mail or launch video identification, 217 * or at least setup our authorization state (actual processing 218 * may also be startedin the @e process function). 219 * 220 * @param cls closure 221 * @param trigger function to call when we made progress 222 * @param trigger_cls closure for @a trigger 223 * @param truth_public_key Identifier of the challenge, to be (if possible) included in the 224 * interaction with the user 225 * @param code secret code that the user has to provide back to satisfy the challenge in 226 * the main anastasis protocol 227 * @param auth_command authentication command which is executed 228 * @param data input to validate (i.e. is it a valid phone number, etc.) 229 * @return state to track progress on the authorization operation, NULL on failure 230 */ 231 struct ANASTASIS_AUTHORIZATION_State * 232 (*start)(void *cls, 233 GNUNET_SCHEDULER_TaskCallback trigger, 234 void *trigger_cls, 235 const struct ANASTASIS_CRYPTO_TruthUUIDP *truth_public_key, 236 uint64_t code, 237 const void *data, 238 size_t data_length); 239 240 241 /** 242 * Continue issuing authentication challenge to user based on @a data. 243 * I.e. check if the transmission of the challenge via SMS or e-mail 244 * has completed and/or manipulate @a connection to direct the client towards solving the challenge. 245 * 246 * @param as authorization state 247 * @param connection HTTP client request (for queuing response, such as redirection to video portal) 248 * @return state of the request 249 */ 250 enum ANASTASIS_AUTHORIZATION_ChallengeResult 251 (*challenge)(struct ANASTASIS_AUTHORIZATION_State *as, 252 struct MHD_Connection *connection); 253 254 255 /** 256 * Check if the client has solved the challenge. 257 * 258 * @param as authorization state 259 * @param timeout how long do we have to produce a reply 260 * @param challenge_response hash of the challenge response, or NULL 261 * @param connection HTTP client request (for queuing response, such as redirection to video portal) 262 * @return state of the request 263 */ 264 enum ANASTASIS_AUTHORIZATION_SolveResult 265 (*solve)(struct ANASTASIS_AUTHORIZATION_State *as, 266 struct GNUNET_TIME_Absolute timeout, 267 const struct GNUNET_HashCode *challenge_response, 268 struct MHD_Connection *connection); 269 270 271 /** 272 * Free internal state associated with @a as. 273 * 274 * @param as state to clean up 275 */ 276 void 277 (*cleanup)(struct ANASTASIS_AUTHORIZATION_State *as); 278 279 }; 280 #endif