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