src/libcharon/sa/xauth/xauth_method.h

   1 /*
   2  * Copyright (C) 2006 Martin Willi
   3  * Hochschule fuer Technik Rapperswil
   4  *
   5  * This program is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License as published by the
   7  * Free Software Foundation; either version 2 of the License, or (at your
   8  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
   9  *
  10  * This program is distributed in the hope that it will be useful, but
  11  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  12  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  13  * for more details.
  14  */
  15
  16 /**
  17  * @defgroup xauth_method xauth_method
  18  * @{ @ingroup xauth
  19  */
  20
  21 #ifndef XAUTH_METHOD_H_
  22 #define XAUTH_METHOD_H_
  23
  24 typedef struct xauth_method_t xauth_method_t;
  25 typedef enum xauth_role_t xauth_role_t;
  26
  27 #include <library.h>
  28 #include <plugins/plugin.h>
  29 #include <utils/identification.h>
  30 #include <encoding/payloads/cp_payload.h>
  31
  32 /**
  33  * Role of an xauth_method, SERVER or PEER (client)
  34  */
  35 enum xauth_role_t {
  36         XAUTH_SERVER,
  37         XAUTH_PEER,
  38 };
  39
  40 /**
  41  * enum names for xauth_role_t.
  42  */
  43 extern enum_name_t *xauth_role_names;
  44
  45 /**
  46  * Interface of an XAuth method for server and client side.
  47  *
  48  * An XAuth method initiates an XAuth exchange and processes requests and
  49  * responses. An XAuth method may need multiple exchanges before succeeding.
  50  * Sending of XAUTH(STATUS) message is done by the framework, not a method.
  51  */
  52 struct xauth_method_t {
  53
  54         /**
  55          * Initiate the XAuth exchange.
  56          *
  57          * initiate() is only usable for server implementations, as clients only
  58          * reply to server requests.
  59          * A cp_payload is created in "out" if result is NEED_MORE.
  60          *
  61          * @param out           cp_payload to send to the client
  62          * @return
  63          *                                      - NEED_MORE, if an other exchange is required
  64          *                                      - FAILED, if unable to create XAuth request payload
  65          */
  66         status_t (*initiate) (xauth_method_t *this, cp_payload_t **out);
  67
  68         /**
  69          * Process a received XAuth message.
  70          *
  71          * A cp_payload is created in "out" if result is NEED_MORE.
  72          *
  73          * @param in            cp_payload response received
  74          * @param out           created cp_payload to send
  75          * @return
  76          *                                      - NEED_MORE, if an other exchange is required
  77          *                                      - FAILED, if XAuth method failed
  78          *                                      - SUCCESS, if XAuth method succeeded
  79          */
  80         status_t (*process) (xauth_method_t *this, cp_payload_t *in,
  81                                                  cp_payload_t **out);
  82
  83         /**
  84          * Get the XAuth username received as XAuth initiator.
  85          *
  86          * @return                      used XAuth username, pointer to internal data
  87          */
  88         identification_t* (*get_identity)(xauth_method_t *this);
  89
  90         /**
  91          * Destroys a eap_method_t object.
  92          */
  93         void (*destroy) (xauth_method_t *this);
  94 };
  95
  96 /**
  97  * Constructor definition for a pluggable XAuth method.
  98  *
  99  * Each XAuth module must define a constructor function which will return
 100  * an initialized object with the methods defined in xauth_method_t.
 101  * Constructors for server and peers are identical, to support both roles
 102  * of a XAuth method, a plugin needs register two constructors in the
 103  * xauth_manager_t.
 104  *
 105  * @param server                ID of the server to use for credential lookup
 106  * @param peer                  ID of the peer to use for credential lookup
 107  * @param profile               configuration string to pass to XAuth method, or NULL
 108  * @return                              implementation of the eap_method_t interface
 109  */
 110 typedef xauth_method_t *(*xauth_constructor_t)(identification_t *server,
 111                                                                                            identification_t *peer,
 112                                                                                            char *profile);
 113
 114 /**
 115  * Helper function to (un-)register XAuth methods from plugin features.
 116  *
 117  * This function is a plugin_feature_callback_t and can be used with the
 118  * PLUGIN_CALLBACK macro to register a XAuth method constructor.
 119  *
 120  * @param plugin                plugin registering the XAuth method constructor
 121  * @param feature               associated plugin feature
 122  * @param reg                   TRUE to register, FALSE to unregister.
 123  * @param data                  data passed to callback, an xauth_constructor_t
 124  */
 125 bool xauth_method_register(plugin_t *plugin, plugin_feature_t *feature,
 126                                                    bool reg, void *data);
 127
 128 #endif /** XAUTH_METHOD_H_ @}*/