src/charon/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 <encoding/payloads/notify_payload.h>
  31 #include <utils/linked_list.h>
  32 #include <crypto/crypters/crypter.h>
  33 #include <crypto/signers/signer.h>
  34
  35
  36 typedef struct message_t message_t;
  37
  38 /**
  39  * @brief This class is used to represent an IKEv2-Message.
  40  *
  41  * The message handles parsing and generation of payloads
  42  * via parser_t/generator_t. Encryption is done transparently
  43  * via the encryption_payload_t. A set of rules for messages
  44  * and payloads does check parsed messages.
  45  *
  46  * @b Constructors:
  47  * - message_create()
  48  * - message_create_from_packet()
  49  * - message_create_notify_reply()
  50  *
  51  * @ingroup encoding
  52  */
  53 struct message_t {
  54
  55         /**
  56          * @brief Sets the IKE major version of the message.
  57          *
  58          * @param this                  message_t object
  59          * @param major_version major version to set
  60          */
  61         void (*set_major_version) (message_t *this,u_int8_t major_version);
  62
  63         /**
  64          * @brief Gets the IKE major version of the message.
  65          *
  66          * @param this                  message_t object
  67          * @return                              major version of the message
  68          */
  69         u_int8_t (*get_major_version) (message_t *this);
  70
  71         /**
  72          * @brief Sets the IKE minor version of the message.
  73          *
  74          * @param this                  message_t object
  75          * @param minor_version minor version to set
  76          */
  77         void (*set_minor_version) (message_t *this,u_int8_t minor_version);
  78
  79         /**
  80          * @brief Gets the IKE minor version of the message.
  81          *
  82          * @param this                  message_t object
  83          * @return                              minor version of the message
  84          */
  85         u_int8_t (*get_minor_version) (message_t *this);
  86
  87         /**
  88          * @brief Sets the Message ID of the message.
  89          *
  90          * @param this                  message_t object
  91          * @param message_id            message_id to set
  92          */
  93         void (*set_message_id) (message_t *this,u_int32_t message_id);
  94
  95         /**
  96          * @brief Gets the Message ID of the message.
  97          *
  98          * @param this                  message_t object
  99          * @return                              message_id type of the message
 100          */
 101         u_int32_t (*get_message_id) (message_t *this);
 102
 103         /**
 104          * @brief Gets the responder SPI of the message.
 105          *
 106          * @param this                  message_t object
 107          * @return                              responder spi of the message
 108          */
 109         u_int64_t (*get_responder_spi) (message_t *this);
 110
 111         /**
 112          * @brief Sets the IKE_SA ID of the message.
 113          *
 114          * @warning ike_sa_id gets cloned  internaly and
 115          * so can be destroyed afterwards.
 116          *
 117          * @param this                  message_t object
 118          * @param ike_sa_id             ike_sa_id to set
 119          */
 120         void (*set_ike_sa_id) (message_t *this,ike_sa_id_t * ike_sa_id);
 121
 122         /**
 123          * @brief Gets the IKE_SA ID of the message.
 124          *
 125          * @warning The returned ike_sa_id is a clone of the internal one.
 126          * So it has to be destroyed by the caller.
 127          *
 128          * @param this                  message_t object
 129          * @param ike_sa_id             pointer to ike_sa_id pointer which will be set
 130          * @return
 131          *                                              - SUCCESS
 132          *                                              - FAILED if no ike_sa_id is set
 133          */
 134         status_t (*get_ike_sa_id) (message_t *this,ike_sa_id_t **ike_sa_id);
 135
 136         /**
 137          * @brief Sets the exchange type of the message.
 138          *
 139          * @param this                  message_t object
 140          * @param exchange_type exchange_type to set
 141          */
 142         void (*set_exchange_type) (message_t *this,exchange_type_t exchange_type);
 143
 144         /**
 145          * @brief Gets the exchange type of the message.
 146          *
 147          * @param this                  message_t object
 148          * @return                              exchange type of the message
 149          */
 150         exchange_type_t (*get_exchange_type) (message_t *this);
 151
 152         /**
 153          * @brief Sets the request flag.
 154          *
 155          * @param this                                  message_t object
 156          * @param original_initiator            TRUE if message is a request, FALSE if it is a reply
 157          */
 158         void (*set_request) (message_t *this,bool request);
 159
 160         /**
 161          * @brief Gets request flag.
 162          *
 163          * @param this                  message_t object
 164          * @return                              TRUE if message is a request, FALSE if it is a reply
 165          */
 166         bool (*get_request) (message_t *this);
 167
 168         /**
 169          * @brief Append a payload to the message.
 170          *
 171          * If the payload must be encrypted is not specified here. Encryption
 172          * of payloads is evaluated via internal rules for the messages and
 173          * is done before generation. The order of payloads may change, since
 174          * all payloads to encrypt are added to the encryption payload, which is
 175          * always the last one.
 176          *
 177          * @param this                  message_t object
 178          * @param payload               payload to append
 179          */
 180         void (*add_payload) (message_t *this, payload_t *payload);
 181
 182         /**
 183          * @brief Parses header of message.
 184          *
 185          * Begins parisng of a message created via message_create_from_packet().
 186          * The parsing context is stored, so a subsequent call to parse_body()
 187          * will continue the parsing process.
 188          *
 189          * @param this          message_t object
 190          * @return
 191          *                                      - SUCCESS if header could be parsed
 192          *                                      - PARSE_ERROR if corrupted/invalid data found
 193          *                                      - FAILED if consistence check of header failed
 194          */
 195         status_t (*parse_header) (message_t *this);
 196
 197         /**
 198          * @brief Parses body of message.
 199          *
 200          * The body gets not only parsed, but rather it gets verified.
 201          * All payloads are verified if they are allowed to exist in the message
 202          * of this type and if their own structure is ok.
 203          * If there are encrypted payloads, they get decrypted via the supplied
 204          * crypter. Also the message integrity gets verified with the supplied
 205          * signer.
 206          * Crypter/signer can be omitted (by passing NULL) when no encryption
 207          * payload is expected.
 208          *
 209          * @param this          message_t object
 210          * @param crypter       crypter to decrypt encryption payloads
 211          * @param signer        signer to verifiy a message with an encryption payload
 212          * @return
 213          *                                      - SUCCESS if header could be parsed
 214          *                                      - NOT_SUPPORTED if ciritcal unknown payloads found
 215          *                                      - FAILED if message type is not suppported!
 216          *                                      - PARSE_ERROR if corrupted/invalid data found
 217          *                                      - VERIFY_ERROR if verification of some payload failed
 218          *                                      - INVALID_STATE if crypter/signer not supplied, but needed
 219          */
 220         status_t (*parse_body) (message_t *this, crypter_t *crypter, signer_t *signer);
 221
 222         /**
 223          * @brief Generates the UDP packet of specific message.
 224          *
 225          * Payloads which must be encrypted are generated first and added to
 226          * an encryption payload. This encryption payload will get encrypted via
 227          * the supplied crypter. Then all other payloads and the header get generated.
 228          * After that, the checksum is added to the encryption payload over the full
 229          * message.
 230          * Crypter/signer can be omitted (by passing NULL) when no encryption
 231          * payload is expected.
 232          *
 233          * @param this          message_t object
 234          * @param crypter       crypter to use when a payload must be encrypted
 235          * @param signer        signer to build a mac
 236          * @return
 237          *                                      - SUCCESS if packet could be generated
 238          *                                      - INVALID_STATE if exchange type is currently not set
 239          *                                      - NOT_FOUND if no rules found for message generation
 240          *                                      - INVALID_STATE if crypter/signer not supplied but needed.
 241          */
 242         status_t (*generate) (message_t *this, crypter_t *crypter, signer_t *signer, packet_t **packet);
 243
 244         /**
 245          * @brief Gets the source host informations.
 246          *
 247          * @warning Returned host_t object is not getting cloned,
 248          * do not destroy nor modify.
 249          *
 250          * @param this          message_t object
 251          * @return                      host_t object representing source host
 252          */
 253         host_t * (*get_source) (message_t *this);
 254
 255         /**
 256          * @brief Sets the source host informations.
 257          *
 258          * @warning host_t object is not getting cloned and gets destroyed by
 259          *                      message_t.destroy or next call of message_t.set_source.
 260          *
 261          * @param this          message_t object
 262          * @param host          host_t object representing source host
 263          */
 264         void (*set_source) (message_t *this, host_t *host);
 265
 266         /**
 267          * @brief Gets the destination host informations.
 268          *
 269          * @warning Returned host_t object is not getting cloned,
 270          * do not destroy nor modify.
 271          *
 272          * @param this          message_t object
 273          * @return                      host_t object representing destination host
 274          */
 275         host_t * (*get_destination) (message_t *this);
 276
 277         /**
 278          * @brief Sets the destination host informations.
 279          *
 280          * @warning host_t object is not getting cloned and gets destroyed by
 281          *                      message_t.destroy or next call of message_t.set_destination.
 282          *
 283          * @param this          message_t object
 284          * @param host          host_t object representing destination host
 285          */
 286         void (*set_destination) (message_t *this, host_t *host);
 287
 288         /**
 289          * @brief Returns an iterator on all stored payloads.
 290          *
 291          * @warning Don't insert payloads over this iterator.
 292          *                      Use add_payload() instead.
 293          *
 294          * @param this          message_t object
 295          * @return                      iterator_t object which has to get destroyd by the caller
 296          */
 297         iterator_t * (*get_payload_iterator) (message_t *this);
 298
 299         /**
 300          * Returns a clone of the internal stored packet_t object.
 301          *
 302          * @param this          message_t object
 303          * @return                      packet_t object as clone of internal one
 304          */
 305         packet_t * (*get_packet) (message_t *this);
 306
 307         /**
 308          * Returns a clone of the internal stored packet_t data.
 309          *
 310          * @param this          message_t object
 311          * @return                      clone of the internal stored packet_t data.
 312          */
 313         chunk_t (*get_packet_data) (message_t *this);
 314
 315
 316         /**
 317          * @brief Destroys a message and all including objects.
 318          *
 319          * @param this          message_t object
 320          */
 321         void (*destroy) (message_t *this);
 322 };
 323
 324 /**
 325  * @brief Creates an message_t object from a incoming UDP Packet.
 326  *
 327  * @warning the given packet_t object is not copied and gets
 328  *                      destroyed in message_t's destroy call.
 329  *
 330  * @warning Packet is not parsed in here!
 331  *
 332  * - exchange_type is set to NOT_SET
 333  * - original_initiator is set to TRUE
 334  * - is_request is set to TRUE
 335  * Call message_t.parse_header afterwards.
 336  *
 337  * @param packet                packet_t object which is assigned to message
 338  * @return                              message_t object
 339  *
 340  * @ingroup encoding
 341  */
 342 message_t * message_create_from_packet(packet_t *packet);
 343
 344
 345 /**
 346  * @brief Creates an empty message_t object.
 347  *
 348  * - exchange_type is set to NOT_SET
 349  * - original_initiator is set to TRUE
 350  * - is_request is set to TRUE
 351  *
 352  * @return message_t object
 353  *
 354  * @ingroup encoding
 355  */
 356 message_t * message_create(void);
 357
 358 /**
 359  * @brief Creates an message_t object of type reply containing a notify payload.
 360  *
 361  * @return message_t object
 362  *
 363  * @ingroup encoding
 364  */
 365 message_t *message_create_notify_reply(host_t *source, host_t *destination, exchange_type_t exchange_type, bool original_initiator,ike_sa_id_t *ike_sa_id,notify_message_type_t notify_type);
 366
 367 #endif /*MESSAGE_H_*/