Source/charon/encoding/message.h

   1 /**
   2  * @file message.h
   3  *
   4  * @brief Interface of message_t.
   5  *
   6  */
   7
   8 /*
   9  * Copyright (C) 2005 Jan Hutter, 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 #ifndef MESSAGE_H_
  24 #define MESSAGE_H_
  25
  26 #include <types.h>
  27 #include <sa/ike_sa_id.h>
  28 #include <network/packet.h>
  29 #include <encoding/payloads/ike_header.h>
  30 #include <utils/linked_list.h>
  31 #include <transforms/crypters/crypter.h>
  32 #include <transforms/signers/signer.h>
  33
  34
  35 typedef struct message_t message_t;
  36
  37 /**
  38  * @brief This class is used to represent an IKEv2-Message.
  39  *
  40  * An IKEv2-Message is either a request or response.
  41  *
  42  * @ingroup encoding
  43  */
  44 struct message_t {
  45
  46         /**
  47          * @brief Sets the IKE major version of the message.
  48          *
  49          * @param this                  message_t object
  50          * @param major_version major version to set
  51          */
  52         void (*set_major_version) (message_t *this,u_int8_t major_version);
  53
  54         /**
  55          * @brief Gets the IKE major version of the message.
  56          *
  57          * @param this                  message_t object
  58          * @return                              major version of the message
  59          */
  60         u_int8_t (*get_major_version) (message_t *this);
  61
  62         /**
  63          * @brief Sets the IKE minor version of the message.
  64          *
  65          * @param this                  message_t object
  66          * @param minor_version minor version to set
  67          */
  68         void (*set_minor_version) (message_t *this,u_int8_t minor_version);
  69
  70         /**
  71          * @brief Gets the IKE minor version of the message.
  72          *
  73          * @param this                  message_t object
  74          * @return                              minor version of the message
  75          */
  76         u_int8_t (*get_minor_version) (message_t *this);
  77
  78         /**
  79          * @brief Sets the Message ID of the message.
  80          *
  81          * @param this                  message_t object
  82          * @param message_id            message_id to set
  83          */
  84         void (*set_message_id) (message_t *this,u_int32_t message_id);
  85
  86         /**
  87          * @brief Gets the Message ID of the message.
  88          *
  89          * @param this                  message_t object
  90          * @return                              message_id type of the message
  91          */
  92         u_int32_t (*get_message_id) (message_t *this);
  93
  94         /**
  95          * @brief Gets the responder SPI of the message.
  96          *
  97          * @param this                  message_t object
  98          * @return                              responder spi of the message
  99          */
 100         u_int64_t (*get_responder_spi) (message_t *this);
 101
 102         /**
 103          * @brief Sets the IKE_SA ID of the message.
 104          *
 105          * @warning ike_sa_id gets cloned  internaly and
 106          * so can be destroyed afterwards.
 107          *
 108          * @param this                  message_t object
 109          * @param ike_sa_id             ike_sa_id to set
 110          */
 111         void (*set_ike_sa_id) (message_t *this,ike_sa_id_t * ike_sa_id);
 112
 113         /**
 114          * @brief Gets the IKE_SA ID of the message.
 115          *
 116          * @warning The returned ike_sa_id is a clone of the internal one.
 117          * So it has to be destroyed by the caller.
 118          *
 119          * @param this                  message_t object
 120          * @param ike_sa_id             pointer to ike_sa_id pointer which will be set
 121          * @return
 122          *                                              - SUCCESS
 123          *                                              - FAILED if no ike_sa_id is set
 124          */
 125         status_t (*get_ike_sa_id) (message_t *this,ike_sa_id_t **ike_sa_id);
 126
 127         /**
 128          * @brief Sets the exchange type of the message.
 129          *
 130          * @param this                  message_t object
 131          * @param exchange_type exchange_type to set
 132          */
 133         void (*set_exchange_type) (message_t *this,exchange_type_t exchange_type);
 134
 135         /**
 136          * @brief Gets the exchange type of the message.
 137          *
 138          * @param this                  message_t object
 139          * @return                              exchange type of the message
 140          */
 141         exchange_type_t (*get_exchange_type) (message_t *this);
 142
 143         /**
 144          * @brief Sets the original initiator flag.
 145          *
 146          * @param this                                  message_t object
 147          * @param original_initiator            TRUE if message is from original initiator
 148          */
 149         void (*set_original_initiator) (message_t *this,bool original_initiator);
 150
 151         /**
 152          * @brief Gets original initiator flag.
 153          *
 154          * @param this                  message_t object
 155          * @return                              TRUE if message is from original initiator, FALSE otherwise
 156          */
 157         bool (*get_original_initiator) (message_t *this);
 158
 159         /**
 160          * @brief Sets the request flag.
 161          *
 162          * @param this                                  message_t object
 163          * @param original_initiator            TRUE if message is a request, FALSE if it is a reply
 164          */
 165         void (*set_request) (message_t *this,bool request);
 166
 167         /**
 168          * @brief Gets request flag.
 169          *
 170          * @param this                  message_t object
 171          * @return                              TRUE if message is a request, FALSE if it is a reply
 172          */
 173         bool (*get_request) (message_t *this);
 174
 175         /**
 176          * @brief Append a payload to the message.
 177          *
 178          * @param this                  message_t object
 179          * @param payload               payload to append
 180          */
 181         void (*add_payload) (message_t *this, payload_t *payload);
 182
 183         /**
 184          * @brief Parses header of message
 185          *
 186          * @param this          message_t object
 187          * @return
 188          *                                      - SUCCESS if header could be parsed
 189          *                                      - PARSE_ERROR if corrupted/invalid data found
 190          *                                      - FAILED if consistence check of header failed
 191          */
 192         status_t (*parse_header) (message_t *this);
 193
 194         /**
 195          * @brief Parses body of message.
 196          *
 197          * The body gets not only parsed, but rather it gets verified.
 198          * All payloads are verified if they are allowed to exist in the message
 199          * of this type and if their own structure is ok.
 200          *
 201          * @param this          message_t object
 202          * @return
 203          *                                      - SUCCESS if header could be parsed
 204          *                                      - NOT_SUPPORTED if unsupported payload are contained in body
 205          *                                      - FAILED if message type is not suppported!
 206          *                                      - PARSE_ERROR if corrupted/invalid data found
 207          *                                      - VERIFY_ERROR if verification of some payload failed
 208          */
 209         status_t (*parse_body) (message_t *this, crypter_t *crypter, signer_t *signer);
 210
 211         /**
 212          * @brief Generates the UDP packet of specific message
 213          *
 214          * @param this          message_t object
 215          * @return
 216          *                                      - SUCCESS if packet could be generated
 217          *                                      - EXCHANGE_TYPE_NOT_SET if exchange type is currently not set
 218          * ....
 219          */
 220         status_t (*generate) (message_t *this, crypter_t *crypter, signer_t *signer, packet_t **packet);
 221
 222         /**
 223          * Verifies the structure of the message_t object.
 224          *
 225          * The payloads are checked for the correct occurence count.
 226          *
 227          * @param this          message_t object
 228          */
 229         status_t (*verify) (message_t *this);
 230
 231         /**
 232          * Gets the source host informations.
 233          *
 234          * @warning Returned host_t object is not getting cloned.
 235          *
 236          * @param this          message_t object
 237          * @return                      host_t object representing source host
 238          */
 239         host_t * (*get_source) (message_t *this);
 240
 241         /**
 242          * Sets the source host informations.
 243          *
 244          * @warning host_t object is not getting cloned and gets destroyed by
 245          *                      message_t.destroy or next call of message_t.set_source.
 246          *
 247          * @param this          message_t object
 248          * @param host          host_t object representing source host
 249          */
 250         void (*set_source) (message_t *this, host_t *host);
 251
 252         /**
 253          * Gets the destination host informations.
 254          *
 255          * @warning Returned host_t object is not getting cloned.
 256          *
 257          * @param this          message_t object
 258          * @return                      host_t object representing destination host
 259          */
 260         host_t * (*get_destination) (message_t *this);
 261
 262         /**
 263          * Sets the destination host informations.
 264          *
 265          * @warning host_t object is not getting cloned and gets destroyed by
 266          *                      message_t.destroy or next call of message_t.set_destination.
 267          *
 268          * @param this          message_t object
 269          * @param host          host_t object representing destination host
 270          */
 271         void (*set_destination) (message_t *this, host_t *host);
 272
 273         /**
 274          * Returns an iterator on all stored payloads.
 275          *
 276          * @warning Don't insert payloads over this iterator.
 277          *                      Use message_t.add_payload instead.
 278          *
 279          * @param this          message_t object
 280          * @return                      iterator_t object which has to get destroyd by the caller
 281          */
 282         iterator_t * (*get_payload_iterator) (message_t *this);
 283
 284         /**
 285          * @brief Destroys a message and all including objects.
 286          *
 287          * @param this          message_t object
 288          */
 289         void (*destroy) (message_t *this);
 290 };
 291
 292 /**
 293  * Creates an message_t object from a incoming UDP Packet.
 294  *
 295  * @warning the given packet_t object is not copied and gets
 296  *                      destroyed in message_t's destroy call.
 297  *
 298  * @warning Packet is not parsed in here!
 299  *
 300  * - exchange_type is set to NOT_SET
 301  * - original_initiator is set to TRUE
 302  * - is_request is set to TRUE
 303  *
 304  * @param packet                packet_t object which is assigned to message
 305  *
 306  * @return                              created message_t object
 307  *
 308  * @ingroup encoding
 309  */
 310 message_t * message_create_from_packet(packet_t *packet);
 311
 312
 313 /**
 314  * Creates an empty message_t object.
 315  *
 316  * - exchange_type is set to NOT_SET
 317  * - original_initiator is set to TRUE
 318  * - is_request is set to TRUE
 319  *
 320  * @return created message_t object
 321  *
 322  * @ingroup encoding
 323  */
 324 message_t * message_create();
 325
 326 #endif /*MESSAGE_H_*/