frosix

frosix_authorization_plugin.h (8823B)

---

 /*
   This file is part of Frosix
   Copyright (C) 2019 Anastasis SARL
 
   Frosix is free software; you can redistribute it and/or modify it under the
   terms of the GNU Affero General Public License as published by the Free Software
   Foundation; either version 3, or (at your option) any later version.
 
   Frosix is distributed in the hope that it will be useful, but WITHOUT ANY
   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
   A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
 
   You should have received a copy of the GNU Affero General Public License along with
   Frosix; see the file COPYING.GPL.  If not, see <http://www.gnu.org/licenses/>
 */
 /**
  * @file include/frosix_authorization_plugin.h
  * @brief authorization access for Frosix
  * @author Christian Grothoff
  */
 #ifndef FROSIX_AUTHORIZATION_PLUGIN_H
 #define FROSIX_AUTHORIZATION_PLUGIN_H
 
 #include "frosix_service.h"
 #include <taler/taler_util.h>
 
 
 /**
  * Plugin-specific state for an authorization operation.
  */
 struct FROSIX_AUTHORIZATION_State;
 
 
 /**
  * Enumeration values indicating the various possible
  * outcomes of the plugin's `challenge` function.
  */
 enum FROSIX_AUTHORIZATION_ChallengeResult
 {
   /**
    * We successfully sent the authorization challenge
    * and queued a reply to MHD.
    */
   FROSIX_AUTHORIZATION_CRES_SUCCESS = 0,
 
   /**
    * We failed to transmit the authorization challenge,
    * but successfully queued a failure response to MHD.
    */
   FROSIX_AUTHORIZATION_CRES_FAILED = 1,
 
   /**
    * The plugin suspended the MHD connection as it needs some more
    * time to do its (asynchronous) work before we can proceed. The
    * plugin will resume the MHD connection when its work is done, and
    * then the `process` function should be called again.
    */
   FROSIX_AUTHORIZATION_CRES_SUSPENDED = 2,
 
   /**
    * The plugin tried to queue a reply on the MHD connection and
    * failed to do so.  We should return #MHD_NO to MHD to cause the
    * HTTP connection to be closed without any reply.
    *
    * However, we were successful at transmitting the challenge,
    * so the challenge should be marked as sent.
    */
   FROSIX_AUTHORIZATION_CRES_SUCCESS_REPLY_FAILED = 4,
 
   /**
    * The plugin tried to queue a reply on the MHD connection and
    * failed to do so.  We should return #MHD_NO to MHD to cause the
    * HTTP connection to be closed without any reply.
    *
    * Additionally, we failed to transmit the challenge.
    */
   FROSIX_AUTHORIZATION_CRES_FAILED_REPLY_FAILED = 5
 };
 
 
 /**
  * Enumeration values indicating the various possible
  * outcomes of the plugin's `solve` function.
  */
 enum FROSIX_AUTHORIZATION_SolveResult
 {
   /**
    * We failed to transmit the authorization challenge,
    * but successfully queued a failure response to MHD.
    */
   FROSIX_AUTHORIZATION_SRES_FAILED = 0,
 
   /**
    * The plugin suspended the MHD connection as it needs some more
    * time to do its (asynchronous) work before we can proceed. The
    * plugin will resume the MHD connection when its work is done, and
    * then the `process` function should be called again.
    */
   FROSIX_AUTHORIZATION_SRES_SUSPENDED = 1,
 
   /**
    * The plugin tried to queue a reply on the MHD connection and
    * failed to do so.  We should return #MHD_NO to MHD to cause the
    * HTTP connection to be closed without any reply.
    *
    * Additionally, we failed to transmit the challenge.
    */
   FROSIX_AUTHORIZATION_SRES_FAILED_REPLY_FAILED = 2,
 
   /**
    * The authentication process completed successfully
    * and we should signal success to the client by
    * returning the truth.
    */
   FROSIX_AUTHORIZATION_SRES_FINISHED = 3
 };
 
 
 /**
  * Argument passed to the "init" function of each
  * plugin.
  */
 struct FROSIX_AuthorizationContext
 {
   /**
    * Database handle.
    */
   struct FROSIX_DatabasePlugin *db;
 
   /**
    * Configuration to use.
    */
   const struct GNUNET_CONFIGURATION_Handle *cfg;
 };
 
 
 /**
  * Handle to interact with a authorization backend.
  */
 struct FROSIX_AuthorizationPlugin
 {
 
   /**
    * Closure for all callbacks.
    */
   void *cls;
 
   /**
    * Cost to GET the /truth using this method.  Set by the plugin's
    * loader, not by the plugin itself.
    */
   struct TALER_Amount cost;
 
   /**
    * True if the payment is managed internally by the
    * authorization plugin.
    */
   bool payment_plugin_managed;
 
   /**
    * The plugin expects the "code" in the "start" function to be
    * provided by the user and not generated by the Frosix
    * backend. The plugin will then validate the code using its own
    * means.  Used by TOTP.
    */
   bool user_provided_code;
 
   /**
    * How often are retries allowed for challenges created
    * by this plugin?
    */
   uint32_t retry_counter;
 
   /**
    * How long should a generated challenge be valid for this type of method.
    */
   struct GNUNET_TIME_Relative code_validity_period;
 
   /**
    * How long before we should rotate a challenge for this type of method.
    */
   struct GNUNET_TIME_Relative code_rotation_period;
 
   /**
    * How long before we should retransmit a code.
    */
   struct GNUNET_TIME_Relative code_retransmission_frequency;
 
   /**
    * Validate @a data is a well-formed input into the challenge method,
    * i.e. @a data is a well-formed phone number for sending an SMS, or
    * a well-formed e-mail address for sending an e-mail. Not expected to
    * check that the phone number or e-mail account actually exists.
    *
    * To be possibly used before issuing a 402 payment required to the client.
    *
    * @param cls closure
    * @param connection HTTP client request (for queuing response)
    * @param truth_mime mime type of @e data
    * @param data input to validate (i.e. is it a valid phone number, etc.)
    * @param data_length number of bytes in @a data
    * @return #GNUNET_OK if @a data is valid,
    *         #GNUNET_NO if @a data is invalid and a reply was successfully queued on @a connection
    *         #GNUNET_SYSERR if @a data invalid but we failed to queue a reply on @a connection
    */
   enum GNUNET_GenericReturnValue
   (*validate)(void *cls,
               struct MHD_Connection *connection,
               const char *truth_mime,
               const char *data,
               size_t data_length);
 
 
   /**
    * Begin issuing authentication challenge to user based on @a data.
    * I.e. start to send SMS or e-mail or launch video identification,
    * or at least setup our authorization state (actual processing
    * may also be startedin the @e process function).
    *
    * @param cls closure
    * @param trigger function to call when we made progress
    * @param trigger_cls closure for @a trigger
    * @param truth_public_key Identifier of the challenge, to be (if possible) included in the
    *             interaction with the user
    * @param code secret code that the user has to provide back to satisfy the challenge in
    *             the main anastasis protocol
    * @param auth_command authentication command which is executed
    * @param data input to validate (i.e. is it a valid phone number, etc.)
    * @return state to track progress on the authorization operation, NULL on failure
    */
   struct FROSIX_AUTHORIZATION_State *
   (*start)(void *cls,
            GNUNET_SCHEDULER_TaskCallback trigger,
            void *trigger_cls,
            const struct FROSIX_ChallengeIdP *truth_public_key,
            uint64_t code,
            const void *data,
            size_t data_length);
 
 
   /**
    * Continue issuing authentication challenge to user based on @a data.
    * I.e. check if the transmission of the challenge via SMS or e-mail
    * has completed and/or manipulate @a connection to direct the client towards solving the challenge.
    *
    * @param as authorization state
    * @param connection HTTP client request (for queuing response, such as redirection to video portal)
    * @return state of the request
    */
   enum FROSIX_AUTHORIZATION_ChallengeResult
   (*challenge)(struct FROSIX_AUTHORIZATION_State *as,
                struct MHD_Connection *connection);
 
 
   /**
    * Check if the client has solved the challenge.
    *
    * @param as authorization state
    * @param timeout how long do we have to produce a reply
    * @param challenge_response hash of the challenge response, or NULL
    * @param connection HTTP client request (for queuing response, such as redirection to video portal)
    * @return state of the request
    */
   enum FROSIX_AUTHORIZATION_SolveResult
   (*solve)(struct FROSIX_AUTHORIZATION_State *as,
            struct GNUNET_TIME_Absolute timeout,
            const struct FROST_HashCode *challenge_response,
            struct MHD_Connection *connection);
 
 
   /**
    * Free internal state associated with @a as.
    *
    * @param as state to clean up
    */
   void
   (*cleanup)(struct FROSIX_AUTHORIZATION_State *as);
 
 };
 #endif