src/libcharon/encoding/message.h

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