implemented and tested functionality to create sa_payload from
[strongswan.git] / Source / charon / encoding / payloads / transform_substructure.h
index 8d49874..6671dbc 100644 (file)
@@ -1,9 +1,7 @@
 /**
  * @file transform_substructure.h
  * 
- * @brief Declaration of the class transform_substructure_t. 
- * 
- * An object of this type represents an IKEv2 TRANSFORM Substructure and contains Attributes.
+ * @brief Interface of transform_substructure_t.
  * 
  */
 
 
 
 /**
- * IKEv1 Value for a transform payload
+ * IKEv1 Value for a transform payload.
+ * 
+ * @ingroup payloads
  */
 #define TRANSFORM_TYPE_VALUE 3
 
 /**
- * Length of the transform substructure header in bytes
+ * Length of the transform substructure header in bytes.
+ * 
+ * @ingroup payloads
  */
 #define TRANSFORM_SUBSTRUCTURE_HEADER_LENGTH 8
 
 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 draft 3.3.2.
+ * 
+ * @ingroup payloads
  */
 enum transform_type_t {
        UNDEFINED_TRANSFORM_TYPE = 241,
        ENCRYPTION_ALGORITHM = 1,
        PSEUDO_RANDOM_FUNCTION = 2,
-       INTEGRITIY_ALGORITHM = 3,
+       INTEGRITY_ALGORITHM = 3,
        DIFFIE_HELLMAN_GROUP = 4,
        EXTENDED_SEQUENCE_NUNBERS = 5
 };
 
 /** 
- * string mappings for transform_type_t
+ * String mappings for transform_type_t.
+ * 
+ * @ingroup payloads
  */
 extern mapping_t transform_type_m[];
 
@@ -70,7 +76,9 @@ 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 draft 3.3.2.
+ * 
+ * @ingroup payloads
  */
 enum extended_sequence_numbers_t {
        NO_EXT_SEQ_NUMBERS = 0,
@@ -78,21 +86,24 @@ enum extended_sequence_numbers_t {
 };
 
 /** 
- * string mappings for extended_sequence_numbers_t
+ * String mappings for extended_sequence_numbers_t.
+ * 
+ * @ingroup payloads
  */
 extern mapping_t extended_sequence_numbers_m[];
 
 typedef struct transform_substructure_t transform_substructure_t;
 
 /**
- * Object representing an IKEv2- TRANSFORM SUBSTRUCTURE
+ * Object representing an IKEv2- TRANSFORM SUBSTRUCTURE.
  * 
  * The TRANSFORM SUBSTRUCTURE format is described in RFC section 3.3.2.
  * 
+ * @ingroup payloads
  */
 struct transform_substructure_t {
        /**
-        * implements payload_t interface
+        * The payload_t interface.
         */
        payload_t payload_interface;
        
@@ -106,13 +117,10 @@ struct transform_substructure_t {
         *                      by calling get_length()!
         *
         * @param this                  calling transform_substructure_t object
-        * @param iterator              the created iterator is stored at the pointed pointer
         * @param[in] forward   iterator direction (TRUE: front to end)
-        * @return              
-        *                                              - SUCCESS or
-        *                                              - OUT_OF_RES if iterator could not be created
+        * @return                              created iterator_t object.
         */
-       status_t (*create_transform_attribute_iterator) (transform_substructure_t *this,iterator_t **iterator, bool forward);
+       iterator_t * (*create_transform_attribute_iterator) (transform_substructure_t *this, bool forward);
        
        /**
         * @brief Adds a transform_attribute_t object to this object.
@@ -122,22 +130,19 @@ struct transform_substructure_t {
         *
         * @param this          calling transform_substructure_t object
         * @param proposal  transform_attribute_t object to add
-        * @return                      - SUCCESS if succeeded
-        *                                      - FAILED otherwise
         */
-       status_t (*add_transform_attribute) (transform_substructure_t *this,transform_attribute_t *attribute);
+       void (*add_transform_attribute) (transform_substructure_t *this,transform_attribute_t *attribute);
        
        /**
         * @brief Sets the next_payload field of this substructure
         * 
         * If this is the last transform, next payload field is set to 0,
-        * otherwise to 3 (payload type of transform in IKEv1)
+        * otherwise to 3
         *
         * @param this          calling transform_substructure_t object
         * @param is_last       When TRUE, next payload field is set to 0, otherwise to 3
-        * @return                      - SUCCESS
         */
-       status_t (*set_is_last_transform) (transform_substructure_t *this, bool is_last);
+       void (*set_is_last_transform) (transform_substructure_t *this, bool is_last);
        
        /**
         * @brief Checks if this is the last transform.
@@ -152,9 +157,8 @@ struct transform_substructure_t {
         *
         * @param this          calling transform_substructure_t object
         * @param type          type value to set
-        * @return                      - SUCCESS
         */
-       status_t (*set_transform_type) (transform_substructure_t *this,u_int8_t type);
+       void (*set_transform_type) (transform_substructure_t *this,u_int8_t type);
        
        /**
         * @brief get transform type of the current transform.
@@ -169,9 +173,8 @@ struct transform_substructure_t {
         *
         * @param this          calling transform_substructure_t object
         * @param id                    transform id to set
-        * @return                      - SUCCESS
         */
-       status_t (*set_transform_id) (transform_substructure_t *this,u_int16_t id);
+       void (*set_transform_id) (transform_substructure_t *this,u_int16_t id);
        
        /**
         * @brief get transform id of the current transform.
@@ -180,37 +183,58 @@ struct transform_substructure_t {
         * @return                      Transform id of current transform substructure.
         */
        u_int16_t (*get_transform_id) (transform_substructure_t *this);
+       
+       /**
+        * @brief get transform id of the current transform.
+        * 
+        * @param this                  calling transform_substructure_t object
+        * @param key_length            The key length is written to this location      
+        * @return                      
+        *                                              - SUCCESS if a key length attribute is contained
+        *                                              - FAILED if no key length attribute is part of this 
+        *                                                transform or key length uses more then 16 bit!
+        */
+       status_t (*get_key_length) (transform_substructure_t *this,u_int16_t *key_length);
 
        /**
         * @brief Clones an transform_substructure_t object.
         *
         * @param this  transform_substructure_t object to clone
-        * @param clone pointer to a transform_substructure_t object pointer 
-        *                              where the new object is stored to.
-        * @return              
-        *                              - OUT_OF_RES
-        *                              - SUCCESS in any case
+        * @return              cloned transform_substructure_t object
         */
-       status_t (*clone) (transform_substructure_t *this,transform_substructure_t **clone);
+       transform_substructure_t* (*clone) (transform_substructure_t *this);
 
        /**
         * @brief Destroys an transform_substructure_t object.
         *
         * @param this  transform_substructure_t object to destroy
-        * @return              
-        *                              SUCCESS in any case
         */
-       status_t (*destroy) (transform_substructure_t *this);
+       void (*destroy) (transform_substructure_t *this);
 };
 
 /**
- * @brief Creates an empty transform_substructure_t object
+ * @brief Creates an empty transform_substructure_t object.
  * 
- * @return                     
- *                                     - created transform_substructure_t object, or
- *                                     - NULL if failed
+ * @return                     created transform_substructure_t object
+ * 
+ * @ingroup payloads
  */
 transform_substructure_t *transform_substructure_create();
 
+/**
+ * @brief Creates an empty transform_substructure_t object.
+ * 
+ * The key length is used for the transport types ENCRYPTION_ALGORITHM,
+ * PSEUDO_RANDOM_FUNCTION, INTEGRITY_ALGORITHM. For all 
+ * other transport types the key_length parameter is not used
+ * 
+ * @return                                     created transform_substructure_t object
+ * @param transform_type       type of transform to create
+ * @param transform_id         transform id specifying the specific algorithm of a transform type
+ * @param key_length           Key length for key lenght attribute
+ * 
+ * @ingroup payloads
+ */
+transform_substructure_t *transform_substructure_create_type(transform_type_t transform_type, u_int16_t transform_id, u_int16_t key_length);
+
 #endif /*TRANSFORM_SUBSTRUCTURE_H_*/