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-2006 Martin Willi
  11  * Copyright (C) 2005 Jan Hutter
  12  * Hochschule fuer Technik Rapperswil
  13  *
  14  * This program is free software; you can redistribute it and/or modify it
  15  * under the terms of the GNU General Public License as published by the
  16  * Free Software Foundation; either version 2 of the License, or (at your
  17  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  18  *
  19  * This program is distributed in the hope that it will be useful, but
  20  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  21  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  22  * for more details.
  23  */
  24
  25 #ifndef MESSAGE_H_
  26 #define MESSAGE_H_
  27
  28 typedef struct message_t message_t;
  29
  30 #include <library.h>
  31 #include <sa/ike_sa_id.h>
  32 #include <network/packet.h>
  33 #include <encoding/payloads/ike_header.h>
  34 #include <encoding/payloads/notify_payload.h>
  35 #include <utils/linked_list.h>
  36 #include <crypto/crypters/crypter.h>
  37 #include <crypto/signers/signer.h>
  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 Build a notify payload and add it to the message.
 188          *
 189          * This is a helper method to create notify messages or add
 190          * notify payload to messages. The flush parameter specifies if existing
 191          * payloads should get removed before appending the notify.
 192          *
 193          * @param this                  message_t object
 194          * @param flush                 TRUE to remove existing payloads
 195          * @param type                  type of the notify
 196          * @param data                  a chunk of data to add to the notify, gets cloned
 197          */
 198         void (*add_notify) (message_t *this, bool flush, notify_type_t type,
 199                                                 chunk_t data);
 200
 201         /**
 202          * @brief Parses header of message.
 203          *
 204          * Begins parisng of a message created via message_create_from_packet().
 205          * The parsing context is stored, so a subsequent call to parse_body()
 206          * will continue the parsing process.
 207          *
 208          * @param this          message_t object
 209          * @return
 210          *                                      - SUCCESS if header could be parsed
 211          *                                      - PARSE_ERROR if corrupted/invalid data found
 212          *                                      - FAILED if consistence check of header failed
 213          */
 214         status_t (*parse_header) (message_t *this);
 215
 216         /**
 217          * @brief Parses body of message.
 218          *
 219          * The body gets not only parsed, but rather it gets verified.
 220          * All payloads are verified if they are allowed to exist in the message
 221          * of this type and if their own structure is ok.
 222          * If there are encrypted payloads, they get decrypted via the supplied
 223          * crypter. Also the message integrity gets verified with the supplied
 224          * signer.
 225          * Crypter/signer can be omitted (by passing NULL) when no encryption
 226          * payload is expected.
 227          *
 228          * @param this          message_t object
 229          * @param crypter       crypter to decrypt encryption payloads
 230          * @param signer        signer to verifiy a message with an encryption payload
 231          * @return
 232          *                                      - SUCCESS if parsing successful
 233          *                                      - NOT_SUPPORTED if ciritcal unknown payloads found
 234          *                                      - NOT_SUPPORTED if message type is not supported!
 235          *                                      - PARSE_ERROR if message parsing failed
 236          *                                      - VERIFY_ERROR if message verification failed (bad syntax)
 237          *                                      - FAILED if integrity check failed
 238          *                                      - INVALID_STATE if crypter/signer not supplied, but needed
 239          */
 240         status_t (*parse_body) (message_t *this, crypter_t *crypter, signer_t *signer);
 241
 242         /**
 243          * @brief Generates the UDP packet of specific message.
 244          *
 245          * Payloads which must be encrypted are generated first and added to
 246          * an encryption payload. This encryption payload will get encrypted via
 247          * the supplied crypter. Then all other payloads and the header get generated.
 248          * After that, the checksum is added to the encryption payload over the full
 249          * message.
 250          * Crypter/signer can be omitted (by passing NULL) when no encryption
 251          * payload is expected.
 252          * Generation is only done once, multiple calls will just return a packet copy.
 253          *
 254          * @param this          message_t object
 255          * @param crypter       crypter to use when a payload must be encrypted
 256          * @param signer        signer to build a mac
 257          * @param packet        copy of generated packet
 258          * @return
 259          *                                      - SUCCESS if packet could be generated
 260          *                                      - INVALID_STATE if exchange type is currently not set
 261          *                                      - NOT_FOUND if no rules found for message generation
 262          *                                      - INVALID_STATE if crypter/signer not supplied but needed.
 263          */
 264         status_t (*generate) (message_t *this, crypter_t *crypter, signer_t *signer, packet_t **packet);
 265
 266         /**
 267          * @brief Gets the source 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 source host
 274          */
 275         host_t * (*get_source) (message_t *this);
 276
 277         /**
 278          * @brief Sets the source 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_source.
 282          *
 283          * @param this          message_t object
 284          * @param host          host_t object representing source host
 285          */
 286         void (*set_source) (message_t *this, host_t *host);
 287
 288         /**
 289          * @brief Gets the destination host informations.
 290          *
 291          * @warning Returned host_t object is not getting cloned,
 292          * do not destroy nor modify.
 293          *
 294          * @param this          message_t object
 295          * @return                      host_t object representing destination host
 296          */
 297         host_t * (*get_destination) (message_t *this);
 298
 299         /**
 300          * @brief Sets the destination host informations.
 301          *
 302          * @warning host_t object is not getting cloned and gets destroyed by
 303          *                      message_t.destroy or next call of message_t.set_destination.
 304          *
 305          * @param this          message_t object
 306          * @param host          host_t object representing destination host
 307          */
 308         void (*set_destination) (message_t *this, host_t *host);
 309
 310         /**
 311          * @brief Returns an iterator on all stored payloads.
 312          *
 313          * @warning Don't insert payloads over this iterator.
 314          *                      Use add_payload() instead.
 315          *
 316          * @param this          message_t object
 317          * @return                      iterator_t object which has to get destroyd by the caller
 318          */
 319         iterator_t * (*get_payload_iterator) (message_t *this);
 320
 321         /**
 322          * @brief Find a payload of a specific type.
 323          *
 324          * Returns the first occurance.
 325          *
 326          * @param this          message_t object
 327          * @param type          type of the payload to find
 328          * @return                      payload, or NULL if no such payload found
 329          */
 330         payload_t* (*get_payload) (message_t *this, payload_type_t type);
 331
 332         /**
 333          * @brief Returns a clone of the internal stored packet_t object.
 334          *
 335          * @param this          message_t object
 336          * @return                      packet_t object as clone of internal one
 337          */
 338         packet_t * (*get_packet) (message_t *this);
 339
 340         /**
 341          * @brief Returns a clone of the internal stored packet_t data.
 342          *
 343          * @param this          message_t object
 344          * @return                      clone of the internal stored packet_t data.
 345          */
 346         chunk_t (*get_packet_data) (message_t *this);
 347
 348         /**
 349          * @brief Destroys a message and all including objects.
 350          *
 351          * @param this          message_t object
 352          */
 353         void (*destroy) (message_t *this);
 354 };
 355
 356 /**
 357  * @brief Creates an message_t object from a incoming UDP Packet.
 358  *
 359  * @warning the given packet_t object is not copied and gets
 360  *                      destroyed in message_t's destroy call.
 361  *
 362  * @warning Packet is not parsed in here!
 363  *
 364  * - exchange_type is set to NOT_SET
 365  * - original_initiator is set to TRUE
 366  * - is_request is set to TRUE
 367  * Call message_t.parse_header afterwards.
 368  *
 369  * @param packet                packet_t object which is assigned to message
 370  * @return                              message_t object
 371  *
 372  * @ingroup encoding
 373  */
 374 message_t * message_create_from_packet(packet_t *packet);
 375
 376
 377 /**
 378  * @brief Creates an empty message_t object.
 379  *
 380  * - exchange_type is set to NOT_SET
 381  * - original_initiator is set to TRUE
 382  * - is_request is set to TRUE
 383  *
 384  * @return message_t object
 385  *
 386  * @ingroup encoding
 387  */
 388 message_t * message_create(void);
 389
 390 #endif /*MESSAGE_H_*/