src/libipsec/ipsec_sa_mgr.h

   1 /*
   2  * Copyright (C) 2012 Tobias Brunner
   3  * Copyright (C) 2012 Giuliano Grassi
   4  * Copyright (C) 2012 Ralf Sager
   5  * Hochschule fuer Technik Rapperswil
   6  *
   7  * This program is free software; you can redistribute it and/or modify it
   8  * under the terms of the GNU General Public License as published by the
   9  * Free Software Foundation; either version 2 of the License, or (at your
  10  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  11  *
  12  * This program is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  14  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  15  * for more details.
  16  */
  17
  18 /**
  19  * @defgroup ipsec_sa_mgr ipsec_sa_mgr
  20  * @{ @ingroup libipsec
  21  */
  22
  23 #ifndef IPSEC_SA_MGR_H_
  24 #define IPSEC_SA_MGR_H_
  25
  26 #include "ipsec_sa.h"
  27
  28 #include <library.h>
  29 #include <ipsec/ipsec_types.h>
  30 #include <selectors/traffic_selector.h>
  31 #include <networking/host.h>
  32
  33 typedef struct ipsec_sa_mgr_t ipsec_sa_mgr_t;
  34
  35 /**
  36  * IPsec SA manager
  37  *
  38  * The first methods are modeled after those in kernel_ipsec_t.
  39  */
  40 struct ipsec_sa_mgr_t {
  41
  42         /**
  43          * Allocate an SPI for an inbound IPsec SA
  44          *
  45          * @param src                   source address of the SA
  46          * @param dst                   destination address of the SA
  47          * @param protocol              protocol of the SA (only ESP supported)
  48          * @param spi                   the allocated SPI
  49          * @return                              SUCCESS of operation successful
  50          */
  51         status_t (*get_spi)(ipsec_sa_mgr_t *this, host_t *src, host_t *dst,
  52                                                 u_int8_t protocol, u_int32_t *spi);
  53
  54         /**
  55          * Add a new SA
  56          *
  57          * @param src                   source address for this SA (gets cloned)
  58          * @param dst                   destination address for this SA (gets cloned)
  59          * @param spi                   SPI for this SA
  60          * @param protocol              protocol for this SA (only ESP is supported)
  61          * @param reqid                 reqid for this SA
  62          * @param mark                  mark for this SA (ignored)
  63          * @param tfc                   Traffic Flow Confidentiality (not yet supported)
  64          * @param lifetime              lifetime for this SA
  65          * @param enc_alg               encryption algorithm for this SA
  66          * @param enc_key               encryption key for this SA
  67          * @param int_alg               integrity protection algorithm
  68          * @param int_key               integrity protection key
  69          * @param mode                  mode for this SA (only tunnel mode is supported)
  70          * @param ipcomp                IPcomp transform (not supported, use IPCOMP_NONE)
  71          * @param cpi                   CPI for IPcomp (ignored)
  72          * @param initiator             TRUE if initiator of the exchange creating this SA
  73          * @param encap                 enable UDP encapsulation (must be TRUE)
  74          * @param esn                   Extended Sequence Numbers (currently not supported)
  75          * @param inbound               TRUE if this is an inbound SA, FALSE otherwise
  76          * @return                              SUCCESS if operation completed
  77          */
  78         status_t (*add_sa)(ipsec_sa_mgr_t *this, host_t *src, host_t *dst,
  79                                            u_int32_t spi, u_int8_t protocol, u_int32_t reqid,
  80                                            mark_t mark, u_int32_t tfc,  lifetime_cfg_t *lifetime,
  81                                            u_int16_t enc_alg, chunk_t enc_key, u_int16_t int_alg,
  82                                            chunk_t int_key, ipsec_mode_t mode, u_int16_t ipcomp,
  83                                            u_int16_t cpi, bool initiator, bool encap, bool esn,
  84                                            bool inbound);
  85
  86         /**
  87          * Update the hosts on an installed SA.
  88          *
  89          * @param spi                   SPI of the SA
  90          * @param protocol              protocol for this SA (ESP/AH)
  91          * @param cpi                   CPI for IPComp, 0 if no IPComp is used
  92          * @param src                   current source address
  93          * @param dst                   current destination address
  94          * @param new_src               new source address
  95          * @param new_dst               new destination address
  96          * @param encap                 current use of UDP encapsulation
  97          * @param new_encap             new use of UDP encapsulation
  98          * @param mark                  optional mark for this SA
  99          * @return                              SUCCESS if operation completed
 100          */
 101         status_t (*update_sa)(ipsec_sa_mgr_t *this,
 102                                                   u_int32_t spi, u_int8_t protocol, u_int16_t cpi,
 103                                                   host_t *src, host_t *dst,
 104                                                   host_t *new_src, host_t *new_dst,
 105                                                   bool encap, bool new_encap, mark_t mark);
 106
 107         /**
 108          * Query the number of bytes processed by an SA from the SAD.
 109          *
 110          * @param src                   source address for this SA
 111          * @param dst                   destination address for this SA
 112          * @param spi                   SPI allocated by us or remote peer
 113          * @param protocol              protocol for this SA (ESP/AH)
 114          * @param mark                  optional mark for this SA
 115          * @param[out] bytes    the number of bytes processed by SA
 116          * @param[out] packets  number of packets processed by SA
 117          * @param[out] time             last (monotonic) time of SA use
 118          * @return                              SUCCESS if operation completed
 119          */
 120         status_t (*query_sa)(ipsec_sa_mgr_t *this, host_t *src, host_t *dst,
 121                                                  u_int32_t spi, u_int8_t protocol, mark_t mark,
 122                                                  u_int64_t *bytes, u_int64_t *packets, time_t *time);
 123
 124         /**
 125          * Delete a previously added SA
 126          *
 127          * @param spi                   SPI of the SA
 128          * @param src                   source address of the SA
 129          * @param dst                   destination address of the SA
 130          * @param protocol              protocol of the SA
 131          * @param cpi                   CPI for IPcomp
 132          * @param mark                  optional mark
 133          * @return                              SUCCESS if operation completed
 134          */
 135         status_t (*del_sa)(ipsec_sa_mgr_t *this, host_t *src, host_t *dst,
 136                                            u_int32_t spi, u_int8_t protocol, u_int16_t cpi,
 137                                            mark_t mark);
 138
 139         /**
 140          * Flush all SAs
 141          *
 142          * @return                              SUCCESS if operation completed
 143          */
 144         status_t (*flush_sas)(ipsec_sa_mgr_t *this);
 145
 146         /**
 147          * Checkout an installed IPsec SA by SPI and destination address
 148          * Can be used to find the correct SA for an inbound packet.
 149          *
 150          * The matching SA is locked until it is checked in using checkin().
 151          * If the matching SA is already checked out, this call blocks until the
 152          * SA is checked in.
 153          *
 154          * Since other threads may be waiting for the checked out SA, it should be
 155          * checked in as soon as possible after use.
 156          *
 157          * @param spi                   SPI (e.g. of an inbound packet)
 158          * @param dst                   destination address (e.g. of an inbound packet)
 159          * @return                              the matching IPsec SA, or NULL if none is found
 160          */
 161         ipsec_sa_t *(*checkout_by_spi)(ipsec_sa_mgr_t *this, u_int32_t spi,
 162                                                                    host_t *dst);
 163
 164         /**
 165          * Checkout an installed IPsec SA by its reqid and inbound/outbound flag.
 166          * Can be used to find the correct SA for an outbound packet.
 167          *
 168          * The matching SA is locked until it is checked in using checkin().
 169          * If the matching SA is already checked out, this call blocks until the
 170          * SA is checked in.
 171          *
 172          * Since other threads may be waiting for a checked out SA, it should be
 173          * checked in as soon as possible after use.
 174          *
 175          * @param reqid                 reqid of the SA
 176          * @param inbound               TRUE for an inbound SA, FALSE for an outbound SA
 177          * @return                              the matching IPsec SA, or NULL if none is found
 178          */
 179         ipsec_sa_t *(*checkout_by_reqid)(ipsec_sa_mgr_t *this, u_int32_t reqid,
 180                                                                          bool inbound);
 181
 182         /**
 183          * Checkin an SA after use.
 184          *
 185          * @param sa                    checked out SA
 186          */
 187         void (*checkin)(ipsec_sa_mgr_t *this, ipsec_sa_t *sa);
 188
 189         /**
 190          * Destroy an ipsec_sa_mgr_t
 191          */
 192         void (*destroy)(ipsec_sa_mgr_t *this);
 193
 194 };
 195
 196 /**
 197  * Create an ipsec_sa_mgr instance
 198  *
 199  * @return                                      IPsec SA manager instance
 200  */
 201 ipsec_sa_mgr_t *ipsec_sa_mgr_create();
 202
 203 #endif /** IPSEC_SA_MGR_H_ @}*/