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