src/libcharon/bus/listeners/listener.h

   1 /*
   2  * Copyright (C) 2009 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 listener listener
  18  * @{ @ingroup listeners
  19  */
  20
  21 #ifndef LISTENER_H_
  22 #define LISTENER_H_
  23
  24 typedef struct listener_t listener_t;
  25
  26 #include <bus/bus.h>
  27
  28 /**
  29  * Listener interface, listens to events if registered to the bus.
  30  */
  31 struct listener_t {
  32
  33         /**
  34          * Hook called if a critical alert is risen.
  35          *
  36          * @param ike_sa        IKE_SA associated to the alert, if any
  37          * @param alert         kind of alert
  38          * @param ...           alert specific argument list
  39          * @return                      TRUE to stay registered, FALSE to unregister
  40          */
  41         bool (*alert)(listener_t *this, ike_sa_t *ike_sa,
  42                                   alert_t alert, va_list args);
  43
  44         /**
  45          * Handle state changes in an IKE_SA.
  46          *
  47          * @param ike_sa        IKE_SA which changes its state
  48          * @param state         new IKE_SA state this IKE_SA changes to
  49          * @return                      TRUE to stay registered, FALSE to unregister
  50          */
  51         bool (*ike_state_change)(listener_t *this, ike_sa_t *ike_sa,
  52                                                          ike_sa_state_t state);
  53
  54         /**
  55          * Handle state changes in a CHILD_SA.
  56          *
  57          * @param ike_sa        IKE_SA containing the affected CHILD_SA
  58          * @param child_sa      CHILD_SA which changes its state
  59          * @param state         new CHILD_SA state this CHILD_SA changes to
  60          * @return                      TRUE to stay registered, FALSE to unregister
  61          */
  62         bool (*child_state_change)(listener_t *this, ike_sa_t *ike_sa,
  63                                                            child_sa_t *child_sa, child_sa_state_t state);
  64
  65         /**
  66          * Hook called for received/sent messages of an IKE_SA.
  67          *
  68          * The hook is invoked twice for each message: Once with plain, parsed data
  69          * and once encoded and encrypted.
  70          *
  71          * @param ike_sa        IKE_SA sending/receiving a message
  72          * @param message       message object
  73          * @param incoming      TRUE for incoming messages, FALSE for outgoing
  74          * @param plain         TRUE if message is parsed and decrypted, FALSE it not
  75          * @return                      TRUE to stay registered, FALSE to unregister
  76          */
  77         bool (*message)(listener_t *this, ike_sa_t *ike_sa, message_t *message,
  78                                         bool incoming, bool plain);
  79
  80         /**
  81          * Hook called with IKE_SA key material.
  82          *
  83          * @param ike_sa        IKE_SA this keymat belongs to
  84          * @param dh            diffie hellman shared secret
  85          * @param dh_other      others DH public value (IKEv1 only)
  86          * @param nonce_i       initiators nonce
  87          * @param nonce_r       responders nonce
  88          * @param rekey         IKE_SA we are rekeying, if any (IKEv2 only)
  89          * @param shared        shared key used for key derivation (IKEv1-PSK only)
  90          * @return                      TRUE to stay registered, FALSE to unregister
  91          */
  92         bool (*ike_keys)(listener_t *this, ike_sa_t *ike_sa, diffie_hellman_t *dh,
  93                                          chunk_t dh_other, chunk_t nonce_i, chunk_t nonce_r,
  94                                          ike_sa_t *rekey, shared_key_t *shared);
  95
  96         /**
  97          * Hook called with CHILD_SA key material.
  98          *
  99          * @param ike_sa        IKE_SA the child sa belongs to
 100          * @param child_sa      CHILD_SA this keymat is used for
 101          * @param initiator     initiator of the CREATE_CHILD_SA exchange
 102          * @param dh            diffie hellman shared secret
 103          * @param nonce_i       initiators nonce
 104          * @param nonce_r       responders nonce
 105          * @return                      TRUE to stay registered, FALSE to unregister
 106          */
 107         bool (*child_keys)(listener_t *this, ike_sa_t *ike_sa, child_sa_t *child_sa,
 108                                            bool initiator, diffie_hellman_t *dh,
 109                                            chunk_t nonce_i, chunk_t nonce_r);
 110
 111         /**
 112          * Hook called if an IKE_SA gets up or down.
 113          *
 114          * @param ike_sa        IKE_SA coming up/going down
 115          * @param up            TRUE for an up event, FALSE for a down event
 116          * @return                      TRUE to stay registered, FALSE to unregister
 117          */
 118         bool (*ike_updown)(listener_t *this, ike_sa_t *ike_sa, bool up);
 119
 120         /**
 121          * Hook called when an IKE_SA gets rekeyed.
 122          *
 123          * @param old           rekeyed IKE_SA getting obsolete
 124          * @param new           new IKE_SA replacing old
 125          * @return                      TRUE to stay registered, FALSE to unregister
 126          */
 127         bool (*ike_rekey)(listener_t *this, ike_sa_t *old, ike_sa_t *new);
 128
 129         /**
 130          * Hook called when an initiator reestablishes an IKE_SA.
 131          *
 132          * This is invoked right before the new IKE_SA is checked in after
 133          * initiating it.  It is not invoked on the responder.
 134          *
 135          * @param old           IKE_SA getting reestablished (is destroyed)
 136          * @param new           new IKE_SA replacing old (gets established)
 137          * @return                      TRUE to stay registered, FALSE to unregister
 138          */
 139         bool (*ike_reestablish)(listener_t *this, ike_sa_t *old, ike_sa_t *new);
 140
 141         /**
 142          * Hook called when a CHILD_SA gets up or down.
 143          *
 144          * @param ike_sa        IKE_SA containing the handled CHILD_SA
 145          * @param child_sa      CHILD_SA coming up/going down
 146          * @param up            TRUE for an up event, FALSE for a down event
 147          * @return                      TRUE to stay registered, FALSE to unregister
 148          */
 149         bool (*child_updown)(listener_t *this, ike_sa_t *ike_sa,
 150                                                  child_sa_t *child_sa, bool up);
 151
 152         /**
 153          * Hook called when an CHILD_SA gets rekeyed.
 154          *
 155          * @param ike_sa        IKE_SA containing the rekeyed CHILD_SA
 156          * @param old           rekeyed CHILD_SA getting obsolete
 157          * @param new           new CHILD_SA replacing old
 158          * @return                      TRUE to stay registered, FALSE to unregister
 159          */
 160         bool (*child_rekey)(listener_t *this, ike_sa_t *ike_sa,
 161                                                 child_sa_t *old, child_sa_t *new);
 162
 163         /**
 164          * Hook called to invoke additional authorization rules.
 165          *
 166          * An authorization hook gets invoked several times: After each
 167          * authentication round, the hook gets invoked with with final = FALSE.
 168          * After authentication is complete and the peer configuration is selected,
 169          * it is invoked again, but with final = TRUE.
 170          *
 171          * @param ike_sa        IKE_SA to authorize
 172          * @param final         TRUE if this is the final hook invocation
 173          * @param success       set to TRUE to complete IKE_SA, FALSE abort
 174          * @return                      TRUE to stay registered, FALSE to unregister
 175          */
 176         bool (*authorize)(listener_t *this, ike_sa_t *ike_sa,
 177                                           bool final, bool *success);
 178
 179         /**
 180          * CHILD_SA traffic selector narrowing hook.
 181          *
 182          * This hook is invoked for each CHILD_SA and allows plugins to modify
 183          * the traffic selector list negotiated for this CHILD_SA.
 184          *
 185          * @param ike_sa        IKE_SA the created CHILD_SA is created in
 186          * @param child_sa      CHILD_SA set up with these traffic selectors
 187          * @param type          type of hook getting invoked
 188          * @param local         list of local traffic selectors to narrow
 189          * @param remote        list of remote traffic selectors to narrow
 190          */
 191         bool (*narrow)(listener_t *this, ike_sa_t *ike_sa, child_sa_t *child_sa,
 192                                 narrow_hook_t type, linked_list_t *local, linked_list_t *remote);
 193
 194         /**
 195          * Virtual IP address assignment hook
 196          *
 197          * This hook gets invoked when a a Virtual IP address is assigned to an
 198          * IKE_SA (assign = TRUE) and again when it is released (assign = FALSE)
 199          *
 200          * @param ike_sa        IKE_SA the VIP is assigned to
 201          * @param vip           Virtual IPv4 or IV6 address
 202          * @param assign        TRUE if assigned to IKE_SA, FALSE if released
 203          * @return                      TRUE to stay registered, FALSE to unregister
 204          */
 205         bool (*assign_vip)(listener_t *this, ike_sa_t *ike_sa, host_t *vip,
 206                                            bool assign);
 207
 208 };
 209
 210 #endif /** LISTENER_H_ @}*/