src/charon/encoding/message.h

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