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          * @param update                TRUE if an SPI has already been allocated for SA
  77          * @return                              SUCCESS if operation completed
  78          */
  79         status_t (*add_sa)(ipsec_sa_mgr_t *this, host_t *src, host_t *dst,
  80                                            u_int32_t spi, u_int8_t protocol, u_int32_t reqid,
  81                                            mark_t mark, u_int32_t tfc,  lifetime_cfg_t *lifetime,
  82                                            u_int16_t enc_alg, chunk_t enc_key, u_int16_t int_alg,
  83                                            chunk_t int_key, ipsec_mode_t mode, u_int16_t ipcomp,
  84                                            u_int16_t cpi, bool initiator, bool encap, bool esn,
  85                                            bool inbound, bool update);
  86
  87         /**
  88          * Update the hosts on an installed SA.
  89          *
  90          * @param spi                   SPI of the SA
  91          * @param protocol              protocol for this SA (ESP/AH)
  92          * @param cpi                   CPI for IPComp, 0 if no IPComp is used
  93          * @param src                   current source address
  94          * @param dst                   current destination address
  95          * @param new_src               new source address
  96          * @param new_dst               new destination address
  97          * @param encap                 current use of UDP encapsulation
  98          * @param new_encap             new use of UDP encapsulation
  99          * @param mark                  optional mark for this SA
 100          * @return                              SUCCESS if operation completed
 101          */
 102         status_t (*update_sa)(ipsec_sa_mgr_t *this,
 103                                                   u_int32_t spi, u_int8_t protocol, u_int16_t cpi,
 104                                                   host_t *src, host_t *dst,
 105                                                   host_t *new_src, host_t *new_dst,
 106                                                   bool encap, bool new_encap, mark_t mark);
 107
 108         /**
 109          * Query the number of bytes processed by an SA from the SAD.
 110          *
 111          * @param src                   source address for this SA
 112          * @param dst                   destination address for this SA
 113          * @param spi                   SPI allocated by us or remote peer
 114          * @param protocol              protocol for this SA (ESP/AH)
 115          * @param mark                  optional mark for this SA
 116          * @param[out] bytes    the number of bytes processed by SA
 117          * @param[out] packets  number of packets processed by SA
 118          * @param[out] time             last (monotonic) time of SA use
 119          * @return                              SUCCESS if operation completed
 120          */
 121         status_t (*query_sa)(ipsec_sa_mgr_t *this, host_t *src, host_t *dst,
 122                                                  u_int32_t spi, u_int8_t protocol, mark_t mark,
 123                                                  u_int64_t *bytes, u_int64_t *packets, time_t *time);
 124
 125         /**
 126          * Delete a previously added SA
 127          *
 128          * @param spi                   SPI of the SA
 129          * @param src                   source address of the SA
 130          * @param dst                   destination address of the SA
 131          * @param protocol              protocol of the SA
 132          * @param cpi                   CPI for IPcomp
 133          * @param mark                  optional mark
 134          * @return                              SUCCESS if operation completed
 135          */
 136         status_t (*del_sa)(ipsec_sa_mgr_t *this, host_t *src, host_t *dst,
 137                                            u_int32_t spi, u_int8_t protocol, u_int16_t cpi,
 138                                            mark_t mark);
 139
 140         /**
 141          * Flush all SAs
 142          *
 143          * @return                              SUCCESS if operation completed
 144          */
 145         status_t (*flush_sas)(ipsec_sa_mgr_t *this);
 146
 147         /**
 148          * Checkout an installed IPsec SA by SPI and destination address
 149          * Can be used to find the correct SA for an inbound packet.
 150          *
 151          * The matching SA is locked until it is checked in using checkin().
 152          * If the matching SA is already checked out, this call blocks until the
 153          * SA is checked in.
 154          *
 155          * Since other threads may be waiting for the checked out SA, it should be
 156          * checked in as soon as possible after use.
 157          *
 158          * @param spi                   SPI (e.g. of an inbound packet)
 159          * @param dst                   destination address (e.g. of an inbound packet)
 160          * @return                              the matching IPsec SA, or NULL if none is found
 161          */
 162         ipsec_sa_t *(*checkout_by_spi)(ipsec_sa_mgr_t *this, u_int32_t spi,
 163                                                                    host_t *dst);
 164
 165         /**
 166          * Checkout an installed IPsec SA by its reqid and inbound/outbound flag.
 167          * Can be used to find the correct SA for an outbound packet.
 168          *
 169          * The matching SA is locked until it is checked in using checkin().
 170          * If the matching SA is already checked out, this call blocks until the
 171          * SA is checked in.
 172          *
 173          * Since other threads may be waiting for a checked out SA, it should be
 174          * checked in as soon as possible after use.
 175          *
 176          * @param reqid                 reqid of the SA
 177          * @param inbound               TRUE for an inbound SA, FALSE for an outbound SA
 178          * @return                              the matching IPsec SA, or NULL if none is found
 179          */
 180         ipsec_sa_t *(*checkout_by_reqid)(ipsec_sa_mgr_t *this, u_int32_t reqid,
 181                                                                          bool inbound);
 182
 183         /**
 184          * Checkin an SA after use.
 185          *
 186          * @param sa                    checked out SA
 187          */
 188         void (*checkin)(ipsec_sa_mgr_t *this, ipsec_sa_t *sa);
 189
 190         /**
 191          * Destroy an ipsec_sa_mgr_t
 192          */
 193         void (*destroy)(ipsec_sa_mgr_t *this);
 194
 195 };
 196
 197 /**
 198  * Create an ipsec_sa_mgr instance
 199  *
 200  * @return                                      IPsec SA manager instance
 201  */
 202 ipsec_sa_mgr_t *ipsec_sa_mgr_create();
 203
 204 #endif /** IPSEC_SA_MGR_H_ @}*/