- fixed doxygen build
[strongswan.git] / Source / charon / config / proposal.h
index 53d417b..48e3ad8 100644 (file)
  * for more details.
  */
 
-#ifndef _PROPOSAL_H_
-#define _PROPOSAL_H_
+#ifndef PROPOSAL_H_
+#define PROPOSAL_H_
 
 #include <types.h>
 #include <utils/identification.h>
 #include <utils/linked_list.h>
-#include <network/host.h>
-#include <transforms/crypters/crypter.h>
-#include <transforms/signers/signer.h>
-#include <transforms/diffie_hellman.h>
+#include <utils/host.h>
+#include <crypto/crypters/crypter.h>
+#include <crypto/signers/signer.h>
+#include <crypto/diffie_hellman.h>
 #include <config/traffic_selector.h>
 
 
@@ -41,10 +41,10 @@ typedef enum protocol_id_t protocol_id_t;
  * @ingroup config
  */
 enum protocol_id_t {
-       UNDEFINED_PROTOCOL_ID = 201,
-       IKE = 1,
-       AH = 2,
-       ESP = 3,
+       PROTO_NONE = 0,
+       PROTO_IKE = 1,
+       PROTO_AH = 2,
+       PROTO_ESP = 3,
 };
 
 /** 
@@ -58,7 +58,7 @@ extern mapping_t protocol_id_m[];
 typedef enum transform_type_t transform_type_t;
 
 /**
- * Type of a transform, as in IKEv2 draft 3.3.2.
+ * Type of a transform, as in IKEv2 RFC 3.3.2.
  * 
  * @ingroup payloads
  */
@@ -82,7 +82,7 @@ extern mapping_t transform_type_m[];
 typedef enum extended_sequence_numbers_t extended_sequence_numbers_t;
 
 /** 
- * Extended sequence numbers, as in IKEv2 draft 3.3.2.
+ * Extended sequence numbers, as in IKEv2 RFC 3.3.2.
  * 
  * @ingroup payloads
  */
@@ -120,8 +120,12 @@ struct algorithm_t {
 typedef struct proposal_t proposal_t;
 
 /**
- * @brief Stores a proposal for a child SA.
+ * @brief Stores a set of algorithms used for an SA.
  * 
+ * A proposal stores algorithms for a specific 
+ * protocol. It can store algorithms for more than
+ * one protocol (e.g. AH and ESP). Then the proposal
+ * means both protocols must be used.
  * A proposal may contain more than one algorithm
  * of the same kind. ONE of them can be selected.
  *
@@ -140,8 +144,8 @@ struct proposal_t {
         * The algorithms are stored by priority, first added
         * is the most preferred.
         * Key size is only needed for encryption algorithms
-        * with variable key size (such as AES), or integrity
-        * algorithms.
+        * with variable key size (such as AES). Must be set
+        * to zero if key size is not specified.
         * The alg parameter accepts encryption_algorithm_t,
         * integrity_algorithm_t, dh_group_number_t and
         * extended_sequence_numbers_t.
@@ -233,6 +237,14 @@ struct proposal_t {
        void (*set_spi) (proposal_t *this, protocol_id_t proto, u_int64_t spi);
        
        /**
+        * @brief Clone a proposal.
+        * 
+        * @param this                          proposal to clone
+        * @return                                      clone of it
+        */
+       proposal_t *(*clone) (proposal_t *this);
+       
+       /**
         * @brief Destroys the proposal object.
         * 
         * @param this                          calling object
@@ -243,6 +255,10 @@ struct proposal_t {
 /**
  * @brief Create a child proposal for AH and/or ESP.
  * 
+ * Since the order of multiple proposals is important for
+ * key derivation, we must assign them numbers as they
+ * appear in the raw payload. Numbering starts at 1.
+ * 
  * @param number                       number of the proposal, as in the payload
  * @return                                     proposal_t object
  * 
@@ -250,4 +266,4 @@ struct proposal_t {
  */
 proposal_t *proposal_create(u_int8_t number);
 
-#endif //_PROPOSAL_H_
+#endif /* PROPOSAL_H_ */