anastasis_authorization_plugin.h (8896B)
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 * Configuration to use. 127 */ 128 const struct GNUNET_CONFIGURATION_Handle *cfg; 129 }; 130 131 132 /** 133 * Handle to interact with a authorization backend. 134 */ 135 struct ANASTASIS_AuthorizationPlugin 136 { 137 138 /** 139 * Closure for all callbacks. 140 */ 141 void *cls; 142 143 /** 144 * Cost to GET the /truth using this method. Set by the plugin's 145 * loader, not by the plugin itself. 146 */ 147 struct TALER_Amount cost; 148 149 /** 150 * True if the payment is managed internally by the 151 * authorization plugin. 152 */ 153 bool payment_plugin_managed; 154 155 /** 156 * The plugin expects the "code" in the "start" function to be 157 * provided by the user and not generated by the Anastasis 158 * backend. The plugin will then validate the code using its own 159 * means. Used by TOTP. 160 */ 161 bool user_provided_code; 162 163 /** 164 * How often are retries allowed for challenges created 165 * by this plugin? 166 */ 167 uint32_t retry_counter; 168 169 /** 170 * How long should a generated challenge be valid for this type of method. 171 */ 172 struct GNUNET_TIME_Relative code_validity_period; 173 174 /** 175 * How long before we should rotate a challenge for this type of method. 176 */ 177 struct GNUNET_TIME_Relative code_rotation_period; 178 179 /** 180 * How long before we should retransmit a code. 181 */ 182 struct GNUNET_TIME_Relative code_retransmission_frequency; 183 184 /** 185 * Validate @a data is a well-formed input into the challenge method, 186 * i.e. @a data is a well-formed phone number for sending an SMS, or 187 * a well-formed e-mail address for sending an e-mail. Not expected to 188 * check that the phone number or e-mail account actually exists. 189 * 190 * To be possibly used before issuing a 402 payment required to the client. 191 * 192 * @param cls closure 193 * @param connection HTTP client request (for queuing response) 194 * @param truth_mime mime type of @e data 195 * @param data input to validate (i.e. is it a valid phone number, etc.) 196 * @param data_length number of bytes in @a data 197 * @return #GNUNET_OK if @a data is valid, 198 * #GNUNET_NO if @a data is invalid and a reply was successfully queued on @a connection 199 * #GNUNET_SYSERR if @a data invalid but we failed to queue a reply on @a connection 200 */ 201 enum GNUNET_GenericReturnValue 202 (*validate)(void *cls, 203 struct MHD_Connection *connection, 204 const char *truth_mime, 205 const char *data, 206 size_t data_length); 207 208 209 /** 210 * Begin issuing authentication challenge to user based on @a data. 211 * I.e. start to send SMS or e-mail or launch video identification, 212 * or at least setup our authorization state (actual processing 213 * may also be startedin the @e process function). 214 * 215 * @param cls closure 216 * @param trigger function to call when we made progress 217 * @param trigger_cls closure for @a trigger 218 * @param truth_public_key Identifier of the challenge, to be (if possible) included in the 219 * interaction with the user 220 * @param code secret code that the user has to provide back to satisfy the challenge in 221 * the main anastasis protocol 222 * @param auth_command authentication command which is executed 223 * @param data input to validate (i.e. is it a valid phone number, etc.) 224 * @return state to track progress on the authorization operation, NULL on failure 225 */ 226 struct ANASTASIS_AUTHORIZATION_State * 227 (*start)(void *cls, 228 GNUNET_SCHEDULER_TaskCallback trigger, 229 void *trigger_cls, 230 const struct ANASTASIS_CRYPTO_TruthUUIDP *truth_public_key, 231 uint64_t code, 232 const void *data, 233 size_t data_length); 234 235 236 /** 237 * Continue issuing authentication challenge to user based on @a data. 238 * I.e. check if the transmission of the challenge via SMS or e-mail 239 * has completed and/or manipulate @a connection to direct the client towards solving the challenge. 240 * 241 * @param as authorization state 242 * @param connection HTTP client request (for queuing response, such as redirection to video portal) 243 * @return state of the request 244 */ 245 enum ANASTASIS_AUTHORIZATION_ChallengeResult 246 (*challenge)(struct ANASTASIS_AUTHORIZATION_State *as, 247 struct MHD_Connection *connection); 248 249 250 /** 251 * Check if the client has solved the challenge. 252 * 253 * @param as authorization state 254 * @param timeout how long do we have to produce a reply 255 * @param challenge_response hash of the challenge response, or NULL 256 * @param connection HTTP client request (for queuing response, such as redirection to video portal) 257 * @return state of the request 258 */ 259 enum ANASTASIS_AUTHORIZATION_SolveResult 260 (*solve)(struct ANASTASIS_AUTHORIZATION_State *as, 261 struct GNUNET_TIME_Absolute timeout, 262 const struct GNUNET_HashCode *challenge_response, 263 struct MHD_Connection *connection); 264 265 266 /** 267 * Free internal state associated with @a as. 268 * 269 * @param as state to clean up 270 */ 271 void 272 (*cleanup)(struct ANASTASIS_AUTHORIZATION_State *as); 273 274 }; 275 #endif