Source/charon/sa/child_sa.h

   1 /**
   2  * @file child_sa.h
   3  *
   4  * @brief Interface of child_sa_t.
   5  *
   6  */
   7
   8 /*
   9  * Copyright (C) 2005 Martin Willi
  10  * Hochschule fuer Technik Rapperswil
  11  *
  12  * This program is free software; you can redistribute it and/or modify it
  13  * under the terms of the GNU General Public License as published by the
  14  * Free Software Foundation; either version 2 of the License, or (at your
  15  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  16  *
  17  * This program is distributed in the hope that it will be useful, but
  18  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  19  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  20  * for more details.
  21  */
  22
  23
  24 #ifndef _CHILD_SA_H_
  25 #define _CHILD_SA_H_
  26
  27 #include <types.h>
  28 #include <transforms/prf_plus.h>
  29 #include <encoding/payloads/proposal_substructure.h>
  30
  31 typedef struct child_sa_t child_sa_t;
  32
  33 /**
  34  * @brief Represents multiple IPsec SAs between two hosts.
  35  *
  36  * A child_sa_t contains multiple SAs. SAs for both
  37  * directions are managed in one child_sa_t object, and
  38  * if both AH and ESP is set up, both protocols are managed
  39  * by one child_sa_t. This means we can have two or
  40  * in the AH+ESP case four IPsec-SAs in one child_sa_t.
  41  *
  42  * The procedure for child sa setup is as follows:
  43  * - A gets SPIs for a proposal via child_sa_t.alloc
  44  * - A send the updated proposal to B
  45  * - B selects a suitable proposal
  46  * - B calls child_sa_t.add to add and update the selected proposal
  47  * - B sends the updated proposal to A
  48  * - A calls child_sa_t.update to update the already allocated SPIs with the chosen proposal
  49  *
  50  *
  51  * @b Constructors:
  52  *  - child_sa_create()
  53  *
  54  * @ingroup sa
  55  */
  56 struct child_sa_t {
  57
  58         /**
  59          * @brief Allocate SPIs for a given proposals.
  60          *
  61          * Since the kernel manages SPIs for us, we need
  62          * to allocate them. If the proposal contains more
  63          * than one protocol, for each protocol an SPI is
  64          * allocated. SPIs are stored internally and written
  65          * back to the proposal.
  66          *
  67          * @param this          calling object
  68          * @param proposal      proposal for which SPIs are allocated
  69          */
  70         status_t (*alloc)(child_sa_t *this, linked_list_t* proposals);
  71
  72         /**
  73          * @brief Install the kernel SAs for a proposal.
  74          *
  75          * Since the kernel manages SPIs for us, we need
  76          * to allocate them. If the proposal contains more
  77          * than one protocol, for each protocol an SPI is
  78          * allocated. SPIs are stored internally and written
  79          * back to the proposal.
  80          *
  81          * @param this          calling object
  82          * @param proposal      proposal for which SPIs are allocated
  83          * @param prf_plus      key material to use for key derivation
  84          */
  85         status_t (*add)(child_sa_t *this, proposal_t *proposal, prf_plus_t *prf_plus);
  86
  87         /**
  88          * @brief Install the kernel SAs for a proposal, if SPIs already allocated.
  89          *
  90          * This one updates the SAs in the kernel, which are
  91          * allocated via alloc, with a selected proposals.
  92          *
  93          * @param this          calling object
  94          * @param proposal      proposal for which SPIs are allocated
  95          * @param prf_plus      key material to use for key derivation
  96          */
  97         status_t (*update)(child_sa_t *this, proposal_t *proposal, prf_plus_t *prf_plus);
  98
  99         /**
 100          * @brief Install the policies using some traffic selectors.
 101          *
 102          * Spplied lists of traffic_selector_t's specify the policies
 103          * to use for this child sa.
 104          *
 105          * @param this          calling object
 106          * @param my_ts         traffic selectors for local site
 107          * @param other_ts      traffic selectors for remote site
 108          * @return                      SUCCESS or FAILED
 109          */
 110         status_t (*add_policies) (child_sa_t *this, linked_list_t *my_ts_list, linked_list_t *other_ts_list);
 111
 112         /**
 113          * @brief Destroys a child_sa.
 114          *
 115          * @param this          calling object
 116          */
 117         void (*destroy) (child_sa_t *this);
 118 };
 119
 120 /**
 121  * @brief Constructor to create a new child_sa_t.
 122  *
 123  * @param me                    own address
 124  * @param other                 remote address
 125  * @return                              child_sa_t object
 126  *
 127  * @ingroup sa
 128  */
 129 child_sa_t * child_sa_create(host_t *me, host_t *other);
 130
 131 #endif /*_CHILD_SA_H_*/