programs/charon/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 <crypto/prf_plus.h>
  29 #include <encoding/payloads/proposal_substructure.h>
  30 #include <utils/logger.h>
  31
  32 typedef struct child_sa_t child_sa_t;
  33
  34 /**
  35  * @brief Represents multiple IPsec SAs between two hosts.
  36  *
  37  * A child_sa_t contains multiple SAs. SAs for both
  38  * directions are managed in one child_sa_t object, and
  39  * if both AH and ESP is set up, both protocols are managed
  40  * by one child_sa_t. This means we can have two or
  41  * in the AH+ESP case four IPsec-SAs in one child_sa_t.
  42  *
  43  * The procedure for child sa setup is as follows:
  44  * - A gets SPIs for a proposal via child_sa_t.alloc
  45  * - A send the updated proposal to B
  46  * - B selects a suitable proposal
  47  * - B calls child_sa_t.add to add and update the selected proposal
  48  * - B sends the updated proposal to A
  49  * - A calls child_sa_t.update to update the already allocated SPIs with the chosen proposal
  50  *
  51  * Once SAs are set up, policies can be added using add_policies.
  52  *
  53  *
  54  * @b Constructors:
  55  *  - child_sa_create()
  56  *
  57  * @ingroup sa
  58  */
  59 struct child_sa_t {
  60
  61         /**
  62          * @brief Allocate SPIs for a given proposals.
  63          *
  64          * Since the kernel manages SPIs for us, we need
  65          * to allocate them. If the proposal contains more
  66          * than one protocol, for each protocol an SPI is
  67          * allocated. SPIs are stored internally and written
  68          * back to the proposal.
  69          *
  70          * @param this          calling object
  71          * @param proposal      proposal for which SPIs are allocated
  72          */
  73         status_t (*alloc)(child_sa_t *this, linked_list_t* proposals);
  74
  75         /**
  76          * @brief Install the kernel SAs for a proposal.
  77          *
  78          * Since the kernel manages SPIs for us, we need
  79          * to allocate them. If the proposal contains more
  80          * than one protocol, for each protocol an SPI is
  81          * allocated. SPIs are stored internally and written
  82          * back to the proposal.
  83          *
  84          * @param this          calling object
  85          * @param proposal      proposal for which SPIs are allocated
  86          * @param prf_plus      key material to use for key derivation
  87          */
  88         status_t (*add)(child_sa_t *this, proposal_t *proposal, prf_plus_t *prf_plus);
  89
  90         /**
  91          * @brief Install the kernel SAs for a proposal, if SPIs already allocated.
  92          *
  93          * This one updates the SAs in the kernel, which are
  94          * allocated via alloc, with a selected proposals.
  95          *
  96          * @param this          calling object
  97          * @param proposal      proposal for which SPIs are allocated
  98          * @param prf_plus      key material to use for key derivation
  99          */
 100         status_t (*update)(child_sa_t *this, proposal_t *proposal, prf_plus_t *prf_plus);
 101
 102         /**
 103          * @brief Install the policies using some traffic selectors.
 104          *
 105          * Spplied lists of traffic_selector_t's specify the policies
 106          * to use for this child sa.
 107          *
 108          * @param this          calling object
 109          * @param my_ts         traffic selectors for local site
 110          * @param other_ts      traffic selectors for remote site
 111          * @return                      SUCCESS or FAILED
 112          */
 113         status_t (*add_policies) (child_sa_t *this, linked_list_t *my_ts_list, linked_list_t *other_ts_list);
 114
 115         /**
 116          * @brief Log the status of a child_sa to a logger.
 117          *
 118          * The status of ESP/AH SAs is logged with the supplied logger in
 119          * a human readable form.
 120          * Supplying NULL as logger uses the internal child_sa logger
 121          * to do the logging. The name is only a log-prefix without further
 122          * meaning.
 123          *
 124          * @param this          calling object
 125          * @param logger        logger to use for logging
 126          * @param name          connection name
 127          */
 128         void (*log_status) (child_sa_t *this, logger_t *logger, char *name);
 129
 130         /**
 131          * @brief Destroys a child_sa.
 132          *
 133          * @param this          calling object
 134          */
 135         void (*destroy) (child_sa_t *this);
 136 };
 137
 138 /**
 139  * @brief Constructor to create a new child_sa_t.
 140  *
 141  * @param me                    own address
 142  * @param other                 remote address
 143  * @return                              child_sa_t object
 144  *
 145  * @ingroup sa
 146  */
 147 child_sa_t * child_sa_create(host_t *me, host_t *other);
 148
 149 #endif /*CHILD_SA_H_*/