moved CHILD_SA key derivation to keymat_t
[strongswan.git] / src / charon / sa / child_sa.h
index 33d06a7..3e13814 100644 (file)
@@ -1,13 +1,7 @@
-/**
- * @file child_sa.h
- *
- * @brief Interface of child_sa_t.
- *
- */
-
 /*
- * Copyright (C) 2006 Tobias Brunner, Daniel Roethlisberger
- * Copyright (C) 2006 Martin Willi
+ * Copyright (C) 2006-2008 Tobias Brunner
+ * Copyright (C) 2006-2007 Martin Willi
+ * Copyright (C) 2006 Daniel Roethlisberger
  * Hochschule fuer Technik Rapperswil
  *
  * This program is free software; you can redistribute it and/or modify it
  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  * for more details.
+ *
+ * $Id$
  */
 
+/**
+ * @defgroup child_sa child_sa
+ * @{ @ingroup sa
+ */
 
 #ifndef CHILD_SA_H_
 #define CHILD_SA_H_
 
-#include <types.h>
+typedef enum child_sa_state_t child_sa_state_t;
+typedef struct child_sa_t child_sa_t;
+
+#include <library.h>
 #include <crypto/prf_plus.h>
 #include <encoding/payloads/proposal_substructure.h>
 #include <config/proposal.h>
-#include <utils/logger.h>
+#include <config/child_cfg.h>
 
 /**
- * Where we should start with reqid enumeration
- */
-#define REQID_START 2000000000
-
-typedef enum child_sa_state_t child_sa_state_t;
-
-/**
- * @brief States of a CHILD_SA
+ * States of a CHILD_SA
  */
 enum child_sa_state_t {
        
@@ -49,11 +45,21 @@ enum child_sa_state_t {
        CHILD_CREATED,
        
        /**
+        * Installed SPD, but no SAD entries
+        */
+       CHILD_ROUTED,
+       
+       /**
         * Installed an in-use CHILD_SA
         */
        CHILD_INSTALLED,
        
        /**
+        * While updating hosts, in update_hosts()
+        */
+       CHILD_UPDATING,
+       
+       /**
         * CHILD_SA which is rekeying
         */
        CHILD_REKEYING,
@@ -62,17 +68,20 @@ enum child_sa_state_t {
         * CHILD_SA in progress of delete
         */
        CHILD_DELETING,
+       
+       /**
+        * CHILD_SA object gets destroyed
+        */
+       CHILD_DESTROYING,
 };
 
 /**
- * String mappings for child_sa_state_t.
+ * enum strings for child_sa_state_t.
  */
-extern mapping_t child_sa_state_m[];
-
-typedef struct child_sa_t child_sa_t;
+extern enum_name_t *child_sa_state_names;
 
 /**
- * @brief Represents an IPsec SAs between two hosts.
+ * Represents an IPsec SAs between two hosts.
  * 
  * A child_sa_t contains two SAs. SAs for both
  * directions are managed in one child_sa_t object. Both
@@ -87,49 +96,96 @@ typedef struct child_sa_t child_sa_t;
  * - A calls child_sa_t.update to update the already allocated SPIs with the chosen proposal
  * 
  * Once SAs are set up, policies can be added using add_policies.
- * 
- * 
- * @b Constructors:
- *  - child_sa_create()
- * 
- * @ingroup sa
  */
 struct child_sa_t {
        
        /**
-        * @brief Get the unique reqid of the CHILD SA.
+        * Get the name of the config this CHILD_SA uses.
+        *
+        * @return                      name
+        */
+       char* (*get_name) (child_sa_t *this);
+       
+       /**
+        * Get the reqid of the CHILD SA.
         * 
-        * Every CHILD_SA has a unique reqid, which is also 
-        * stored down in the kernel.
+        * Every CHILD_SA has a reqid. The kernel uses this ID to
+        * identify it.
         *
-        * @param this          calling object
         * @return                      reqid of the CHILD SA
         */
        u_int32_t (*get_reqid)(child_sa_t *this);
        
        /**
-        * @brief Get the SPI of this CHILD_SA.
+        * Get the SPI of this CHILD_SA.
         * 
         * Set the boolean parameter inbound to TRUE to
         * get the SPI for which we receive packets, use
         * FALSE to get those we use for sending packets.
         *
-        * @param this          calling object
         * @param inbound       TRUE to get inbound SPI, FALSE for outbound.
-        * @return                      spi of the CHILD SA
+        * @return                      SPI of the CHILD SA
         */
        u_int32_t (*get_spi) (child_sa_t *this, bool inbound);
        
        /**
-        * @brief Get the protocol which this CHILD_SA uses to protect traffic.
+        * Get the CPI of this CHILD_SA.
+        * 
+        * Set the boolean parameter inbound to TRUE to
+        * get the CPI for which we receive packets, use
+        * FALSE to get those we use for sending packets.
+        *
+        * @param inbound       TRUE to get inbound CPI, FALSE for outbound.
+        * @return                      CPI of the CHILD SA
+        */
+       u_int16_t (*get_cpi) (child_sa_t *this, bool inbound);
+
+       /**
+        * Get the protocol which this CHILD_SA uses to protect traffic.
         *
-        * @param this          calling object
         * @return                      AH | ESP
         */
        protocol_id_t (*get_protocol) (child_sa_t *this);
        
        /**
-        * @brief Allocate SPIs for given proposals.
+        * Get the IPsec mode of this CHILD_SA.
+        *
+        * @return                      TUNNEL | TRANSPORT | BEET
+        */
+       ipsec_mode_t (*get_mode)(child_sa_t *this);
+       
+       /**
+        * Get the used IPComp algorithm.
+        *
+        * @return                      IPComp compression algorithm.
+        */
+       ipcomp_transform_t (*get_ipcomp)(child_sa_t *this);
+       
+       /**
+        * Check if this CHILD_SA uses UDP encapsulation.
+        *
+        * @return                      TRUE if SA encapsulates ESP packets
+        */
+       bool (*has_encap)(child_sa_t *this);
+       
+       /**
+        * Get the lifetime of the CHILD_SA.
+        *
+        * @param hard          TRUE for hard lifetime, FALSE for soft (rekey) lifetime
+        * @return                      lifetime in seconds
+        */
+       u_int32_t (*get_lifetime)(child_sa_t *this, bool hard);
+       
+       /**
+        * Get last use time of the CHILD_SA.
+        *
+        * @param inbound       TRUE for inbound traffic, FALSE for outbound
+        * @return                      time of last use in seconds
+        */
+       u_int32_t (*get_usetime)(child_sa_t *this, bool inbound);
+       
+       /**
+        * Allocate SPIs for given proposals.
         * 
         * Since the kernel manages SPIs for us, we need
         * to allocate them. If a proposal contains more
@@ -137,147 +193,146 @@ struct child_sa_t {
         * allocated. SPIs are stored internally and written
         * back to the proposal.
         *
-        * @param this          calling object
         * @param proposals     list of proposals for which SPIs are allocated
         */
        status_t (*alloc)(child_sa_t *this, linked_list_t* proposals);
        
        /**
-        * @brief Install the kernel SAs for a proposal, without previous SPI allocation.
+        * Install the kernel SAs for a proposal, without previous SPI allocation.
         *
-        * @param this          calling object
         * @param proposal      proposal for which SPIs are allocated
-        * @param prf_plus      key material to use for key derivation
+        * @param mode          mode for the CHILD_SA
+        * @param integ_in      integrity key for inbound traffic
+        * @param integ_out     integrity key for outbound traffic
+        * @param encr_in       encryption key for inbound traffic
+        * @param enc_out       encryption key for outbound traffic
         * @return                      SUCCESS or FAILED
         */
-       status_t (*add)(child_sa_t *this, proposal_t *proposal, prf_plus_t *prf_plus);
-       
+       status_t (*add)(child_sa_t *this, proposal_t *proposal, ipsec_mode_t mode,
+                                       chunk_t integ_in, chunk_t integ_out,
+                                       chunk_t encr_in, chunk_t encr_out);
        /**
-        * @brief Install the kernel SAs for a proposal, after SPIs have been allocated.
+        * Install the kernel SAs for a proposal, after SPIs have been allocated.
         *
         * Updates an SA, for which SPIs are already allocated via alloc().
         *
-        * @param this          calling object
         * @param proposal      proposal for which SPIs are allocated
-        * @param prf_plus      key material to use for key derivation
+        * @param mode          mode for the CHILD_SA
+        * @param integ_in      integrity key for inbound traffic
+        * @param integ_out     integrity key for outbound traffic
+        * @param encr_in       encryption key for inbound traffic
+        * @param enc_out       encryption key for outbound traffic
         * @return                      SUCCESS or FAILED
         */
-       status_t (*update)(child_sa_t *this, proposal_t *proposal, prf_plus_t *prf_plus);
-
+       status_t (*update)(child_sa_t *this, proposal_t *proposal, ipsec_mode_t mode,
+                                          chunk_t integ_in, chunk_t integ_out,
+                                          chunk_t encr_in, chunk_t encr_out);
        /**
-        * @brief Update the hosts in the kernel SAs and policies
+        * Get the selected proposal passed to add()/update().
         *
-        * @warning only call this after update() has been called.
+        * @return                      selected proposal
+        */
+       proposal_t* (*get_proposal)(child_sa_t *this);
+       
+       /**
+        * Update the hosts in the kernel SAs and policies.
         *
-        * @param this                  calling object
-        * @param new_me                the new local host
-        * @param new_other             the new remote host
-        * @param my_diff               differences to apply for me
-        * @param other_diff    differences to apply for other
-        * @return                              SUCCESS or FAILED
+        * The CHILD must be INSTALLED to do this update.
+        *
+        * @param me            the new local host
+        * @param other         the new remote host
+        * @param vip           virtual IP, if any
+        * @param                       TRUE to use UDP encapsulation for NAT traversal
+        * @return                      SUCCESS or FAILED
         */
-       status_t (*update_hosts) (child_sa_t *this, host_t *new_me, host_t *new_other, 
-                                                         host_diff_t my_diff, host_diff_t other_diff);
+       status_t (*update_hosts)(child_sa_t *this, host_t *me, host_t *other,
+                                                        host_t *vip, bool encap);
        
        /**
-        * @brief Install the policies using some traffic selectors.
+        * Install the policies using some traffic selectors.
         *
         * Supplied lists of traffic_selector_t's specify the policies
         * to use for this child sa.
         *
-        * @param this          calling object
         * @param my_ts         traffic selectors for local site
         * @param other_ts      traffic selectors for remote site
+        * @param mode          mode for the SA: tunnel/transport
+        * @param proto         protocol for policy, ESP/AH
         * @return                      SUCCESS or FAILED
         */     
-       status_t (*add_policies) (child_sa_t *this, linked_list_t *my_ts_list, linked_list_t *other_ts_list);
+       status_t (*add_policies)(child_sa_t *this, linked_list_t *my_ts_list,
+                                                        linked_list_t *other_ts_list, ipsec_mode_t mode,
+                                                        protocol_id_t proto);
        
        /**
-        * @brief Get the time of this child_sa_t's last use (i.e. last use of any of its policies)
-        * 
-        * @param this          calling object
-        * @param inbound       query for in- or outbound usage
-        * @param use_time      the time
-        * @return                      SUCCESS or FAILED
+        * Get the traffic selectors of added policies of local host.
+        *
+        * @param local         TRUE for own traffic selectors, FALSE for remote
+        * @return                      list of traffic selectors
         */     
-       status_t (*get_use_time) (child_sa_t *this, bool inbound, time_t *use_time);
+       linked_list_t* (*get_traffic_selectors) (child_sa_t *this, bool local);
        
        /**
-        * @brief Get the state of the CHILD_SA.
+        * Create an enumerator over installed policies.
         *
-        * @param this          calling object
+        * @return                      enumerator over pairs of traffic selectors.
+        */
+       enumerator_t* (*create_policy_enumerator)(child_sa_t *this);
+       
+       /**
+        * Get the state of the CHILD_SA.
         */     
        child_sa_state_t (*get_state) (child_sa_t *this);
        
        /**
-        * @brief Set the state of the CHILD_SA.
+        * Set the state of the CHILD_SA.
         *
-        * @param this          calling object
+        * @param state         state to set on CHILD_SA
         */     
        void (*set_state) (child_sa_t *this, child_sa_state_t state);
        
        /**
-        * @brief Set the transaction which rekeys this CHILD_SA.
+        * Get the config used to set up this child sa.
         *
-        * Since either end may initiate CHILD_SA rekeying, we must detect
-        * such situations to handle them cleanly. A rekeying transaction
-        * registers itself to the CHILD_SA, and checks later if another
-        * transaction is in progress of a rekey.
-        * 
-        * @todo Fix include problematics to allow inclusion of 
-        * the create_child_sa_t transaction.
-        *
-        * @param this          calling object
-        */     
-       void (*set_rekeying_transaction) (child_sa_t *this, void *transaction);
+        * @return                      child_cfg
+        */
+       child_cfg_t* (*get_config) (child_sa_t *this);
        
        /**
-        * @brief Get the transaction which rekeys this CHILD_SA.
-        *
-        * @see set_rekeying_transactoin().
-        *
-        * @param this          calling object
-        */     
-       void* (*get_rekeying_transaction) (child_sa_t *this);
+        * Activate IPComp by setting the transform ID and CPI values.
+        * 
+        * @param ipcomp        the IPComp transform to use
+        * @param other_cpi     other Compression Parameter Index
+        */
+       void (*activate_ipcomp) (child_sa_t *this, ipcomp_transform_t ipcomp,
+                                                        u_int16_t other_cpi);
        
        /**
-        * @brief Log the status of a child_sa to a logger.
-        *
-        * The status of ESP/AH SAs is logged with the supplied logger in
-        * a human readable form.
-        * Supplying NULL as logger uses the internal child_sa logger
-        * to do the logging. The name is only a log-prefix without further
-        * meaning.
-        *
-        * @param this          calling object
-        * @param logger        logger to use for logging
-        * @param name          connection name
-        */     
-       void (*log_status) (child_sa_t *this, logger_t *logger, char *name);
+        * Returns the Compression Parameter Index (CPI) allocated from the kernel.
+        * 
+        * @return                      allocated CPI
+        */
+       u_int16_t (*allocate_cpi) (child_sa_t *this);
        
        /**
-        * @brief Destroys a child_sa.
-        *
-        * @param this          calling object
+        * Destroys a child_sa.
         */
        void (*destroy) (child_sa_t *this);
 };
 
 /**
- * @brief Constructor to create a new child_sa_t.
+ * Constructor to create a new child_sa_t.
  *
- * @param rekey_reqid  reqid of old CHILD_SA when rekeying, 0 otherwise
  * @param me                   own address
  * @param other                        remote address
- * @param soft_lifetime        time before rekeying
- * @param hard_lifteime        time before delete
- * @param use_natt             TRUE if NAT traversal is used
+ * @param my_id                        id of own peer
+ * @param other_id             id of remote peer
+ * @param config               config to use for this CHILD_SA
+ * @param reqid                        reqid of old CHILD_SA when rekeying, 0 otherwise
+ * @param encap                        TRUE to enable UDP encapsulation (NAT traversal)
  * @return                             child_sa_t object
- * 
- * @ingroup sa
  */
-child_sa_t * child_sa_create(u_int32_t rekey_reqid, host_t *me, host_t *other, 
-                                                        u_int32_t soft_lifetime, u_int32_t hard_lifetime,
-                                                        bool use_natt);
+child_sa_t * child_sa_create(host_t *me, host_t *other, child_cfg_t *config,
+                                                        u_int32_t reqid, bool encap);
 
-#endif /*CHILD_SA_H_*/
+#endif /*CHILD_SA_H_ @} */