summaryrefslogtreecommitdiff
path: root/src/include/anastasis_authorization_plugin.h
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2021-07-30 10:38:27 +0200
committerChristian Grothoff <christian@grothoff.org>2021-07-30 10:38:27 +0200
commit7e669bcf6b6336ec429da949bcb4aa456971dba2 (patch)
treed19912f950d1cac1c38b857b7d5bdaba2289544e /src/include/anastasis_authorization_plugin.h
downloadanastasis-7e669bcf6b6336ec429da949bcb4aa456971dba2.tar.gz
anastasis-7e669bcf6b6336ec429da949bcb4aa456971dba2.tar.bz2
anastasis-7e669bcf6b6336ec429da949bcb4aa456971dba2.zip
folding history in preparation of GNU Anastasis v0.0.0 release
Diffstat (limited to 'src/include/anastasis_authorization_plugin.h')
-rw-r--r--src/include/anastasis_authorization_plugin.h183
1 files changed, 183 insertions, 0 deletions
diff --git a/src/include/anastasis_authorization_plugin.h b/src/include/anastasis_authorization_plugin.h
new file mode 100644
index 0000000..5985f52
--- /dev/null
+++ b/src/include/anastasis_authorization_plugin.h
@@ -0,0 +1,183 @@
+/*
+ This file is part of Anastasis
+ Copyright (C) 2019 Taler Systems SA
+
+ Anastasis is free software; you can redistribute it and/or modify it under the
+ terms of the GNU Lesser General Public License as published by the Free Software
+ Foundation; either version 3, or (at your option) any later version.
+
+ Anastasis 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 General Public License for more details.
+
+ You should have received a copy of the GNU General Public License along with
+ Anastasis; see the file COPYING.GPL. If not, see <http://www.gnu.org/licenses/>
+*/
+/**
+ * @file include/anastasis_authorization_plugin.h
+ * @brief authorization access for Anastasis
+ * @author Christian Grothoff
+ */
+#ifndef ANASTASIS_AUTHORIZATION_PLUGIN_H
+#define ANASTASIS_AUTHORIZATION_PLUGIN_H
+
+#include "anastasis_service.h"
+#include <taler/taler_util.h>
+
+
+/**
+ * Plugin-specific state for an authorization operation.
+ */
+struct ANASTASIS_AUTHORIZATION_State;
+
+
+/**
+ * Enumeration values indicating the various possible
+ * outcomes of the plugin's `process` function.
+ */
+enum ANASTASIS_AUTHORIZATION_Result
+{
+ /**
+ * We successfully sent the authorization challenge
+ * and queued a reply to MHD.
+ */
+ ANASTASIS_AUTHORIZATION_RES_SUCCESS = 0,
+
+ /**
+ * We failed to transmit the authorization challenge,
+ * but successfully queued a failure response to MHD.
+ */
+ ANASTASIS_AUTHORIZATION_RES_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.
+ */
+ ANASTASIS_AUTHORIZATION_RES_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.
+ */
+ ANASTASIS_AUTHORIZATION_RES_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.
+ */
+ ANASTASIS_AUTHORIZATION_RES_FAILED_REPLY_FAILED = 5
+};
+
+
+/**
+ * Handle to interact with a authorization backend.
+ */
+struct ANASTASIS_AuthorizationPlugin
+{
+
+ /**
+ * Closure for all callbacks.
+ */
+ void *cls;
+
+ /**
+ * 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 ANASTASIS_AUTHORIZATION_State *
+ (*start)(void *cls,
+ GNUNET_SCHEDULER_TaskCallback trigger,
+ void *trigger_cls,
+ const struct ANASTASIS_CRYPTO_TruthUUIDP *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 redirect the client
+ * to a video identification site.
+ *
+ * @param as authorization state
+ * @param connection HTTP client request (for queuing response, such as redirection to video portal)
+ * @return state of the request
+ */
+ enum ANASTASIS_AUTHORIZATION_Result
+ (*process)(struct ANASTASIS_AUTHORIZATION_State *as,
+ struct MHD_Connection *connection);
+
+
+ /**
+ * Free internal state associated with @a as.
+ *
+ * @param as state to clean up
+ */
+ void
+ (*cleanup)(struct ANASTASIS_AUTHORIZATION_State *as);
+
+};
+#endif