Annotation of embedaddon/strongswan/src/libcharon/encoding/message.h, revision 1.1
1.1 ! misho 1: /*
! 2: * Copyright (C) 2006-2014 Tobias Brunner
! 3: * Copyright (C) 2005-2009 Martin Willi
! 4: * Copyright (C) 2006 Daniel Roethlisberger
! 5: * Copyright (C) 2005 Jan Hutter
! 6: * HSR 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 <encoding/payloads/ike_header.h>
! 31: #include <encoding/payloads/notify_payload.h>
! 32: #include <sa/keymat.h>
! 33: #include <sa/ike_sa_id.h>
! 34: #include <networking/packet.h>
! 35: #include <collections/linked_list.h>
! 36:
! 37: /**
! 38: * This class is used to represent an IKE-Message.
! 39: *
! 40: * The message handles parsing and generation of payloads
! 41: * via parser_t/generator_t. Encryption is done transparently
! 42: * via the encrypted_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, uint8_t major_version);
! 53:
! 54: /**
! 55: * Gets the IKE major version of the message.
! 56: *
! 57: * @return major version of the message
! 58: */
! 59: uint8_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, uint8_t minor_version);
! 67:
! 68: /**
! 69: * Gets the IKE minor version of the message.
! 70: *
! 71: * @return minor version of the message
! 72: */
! 73: uint8_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, uint32_t message_id);
! 81:
! 82: /**
! 83: * Gets the Message ID of the message.
! 84: *
! 85: * @return message_id type of the message
! 86: */
! 87: uint32_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: uint64_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: uint64_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: * Set the version flag in the IKE header.
! 158: */
! 159: void (*set_version_flag)(message_t *this);
! 160:
! 161: /**
! 162: * Get a reserved bit in the IKE header.
! 163: *
! 164: * @param nr reserved bit to get in IKE header, 0-4
! 165: * @return TRUE if bit is set
! 166: */
! 167: bool (*get_reserved_header_bit)(message_t *this, u_int nr);
! 168:
! 169: /**
! 170: * Set a reserved bit in the IKE header.
! 171: *
! 172: * @param nr reserved bit to set in IKE header, 0-4
! 173: */
! 174: void (*set_reserved_header_bit)(message_t *this, u_int nr);
! 175:
! 176: /**
! 177: * Append a payload to the message.
! 178: *
! 179: * If the payload must be encrypted is not specified here. Encryption
! 180: * of payloads is evaluated via internal rules for the messages and
! 181: * is done before generation. The order of payloads may change, since
! 182: * all payloads to encrypt are added to the encryption payload, which is
! 183: * always the last one.
! 184: *
! 185: * @param payload payload to append
! 186: */
! 187: void (*add_payload) (message_t *this, payload_t *payload);
! 188:
! 189: /**
! 190: * Build a notify payload and add it to the message.
! 191: *
! 192: * This is a helper method to create notify messages or add
! 193: * notify payload to messages. The flush parameter specifies if existing
! 194: * payloads should get removed before appending the notify.
! 195: *
! 196: * @param flush TRUE to remove existing payloads
! 197: * @param type type of the notify
! 198: * @param data a chunk of data to add to the notify, gets cloned
! 199: */
! 200: void (*add_notify) (message_t *this, bool flush, notify_type_t type,
! 201: chunk_t data);
! 202:
! 203: /**
! 204: * Disable automatic payload sorting for this message.
! 205: */
! 206: void (*disable_sort)(message_t *this);
! 207:
! 208: /**
! 209: * Parses header of message.
! 210: *
! 211: * Begins parsing of a message created via message_create_from_packet().
! 212: * The parsing context is stored, so a subsequent call to parse_body()
! 213: * will continue the parsing process.
! 214: *
! 215: * @return
! 216: * - SUCCESS if header could be parsed
! 217: * - PARSE_ERROR if corrupted/invalid data found
! 218: * - FAILED if consistency check of header failed
! 219: */
! 220: status_t (*parse_header) (message_t *this);
! 221:
! 222: /**
! 223: * Parses body of message.
! 224: *
! 225: * The body gets not only parsed, but rather it gets verified.
! 226: * All payloads are verified if they are allowed to exist in the message
! 227: * of this type and if their own structure is ok.
! 228: * If there are encrypted payloads, they get decrypted and verified using
! 229: * the given aead transform (if given).
! 230: *
! 231: * @param keymat keymat to verify/decrypt message
! 232: * @return
! 233: * - SUCCESS if parsing successful
! 234: * - PARSE_ERROR if message parsing failed
! 235: * - VERIFY_ERROR if message verification failed (bad syntax)
! 236: * - FAILED if integrity check failed
! 237: * - INVALID_STATE if aead not supplied, but needed
! 238: */
! 239: status_t (*parse_body) (message_t *this, keymat_t *keymat);
! 240:
! 241: /**
! 242: * Generates the UDP packet of specific message.
! 243: *
! 244: * Payloads which must be encrypted are generated first and added to
! 245: * an encryption payload. This encryption payload will get encrypted and
! 246: * signed via the supplied aead transform (if given).
! 247: * Generation is only done once, multiple calls will just return a copy
! 248: * of the packet.
! 249: *
! 250: * @param keymat keymat to encrypt/sign message
! 251: * @param packet copy of generated packet
! 252: * @return
! 253: * - SUCCESS if packet could be generated
! 254: * - INVALID_STATE if exchange type is currently not set
! 255: * - NOT_FOUND if no rules found for message generation
! 256: * - INVALID_STATE if aead not supplied but needed.
! 257: */
! 258: status_t (*generate) (message_t *this, keymat_t *keymat, packet_t **packet);
! 259:
! 260: /**
! 261: * Check if the message has already been encoded using generate().
! 262: *
! 263: * @return TRUE if message has been encoded
! 264: */
! 265: bool (*is_encoded)(message_t *this);
! 266:
! 267: /**
! 268: * Generates the message split into fragments of the given size (total IP
! 269: * datagram length).
! 270: *
! 271: * @param keymat keymat to encrypt/sign message(s)
! 272: * @param frag_len fragment length (maximum total IP datagram length), 0
! 273: * for default value depending on address family
! 274: * @param fragments receives an enumerator with generated packet_t*,
! 275: * which are owned by the enumerator
! 276: * @return
! 277: * - SUCCESS if message could be fragmented
! 278: * - FAILED if fragmentation failed
! 279: * - and the possible return values of generate()
! 280: */
! 281: status_t (*fragment)(message_t *this, keymat_t *keymat, size_t frag_len,
! 282: enumerator_t **fragments);
! 283:
! 284: /**
! 285: * Check if the message has been encoded and fragmented using fragment(),
! 286: * and whether there actually resulted fragments (if not is_encoded() will
! 287: * be TRUE).
! 288: *
! 289: * The packets of individual fragments can be retrieved with
! 290: * get_fragments().
! 291: *
! 292: * @return TRUE if message has been encoded and fragmented
! 293: */
! 294: bool (*is_fragmented)(message_t *this);
! 295:
! 296: /**
! 297: * Add a fragment to the message if it was created with
! 298: * message_create_defrag().
! 299: *
! 300: * Once the message is completed it should be processed like any other
! 301: * inbound message.
! 302: *
! 303: * @param fragment fragment to add
! 304: * @return
! 305: * - SUCCESS if message was reassembled
! 306: * - NEED_MORE if not all fragments have yet been received
! 307: * - FAILED if reassembling failed
! 308: * - INVALID_ARG if fragment is invalid for some reason
! 309: * - INVALID_STATE if message was not created using
! 310: * message_create_defrag()
! 311: */
! 312: status_t (*add_fragment)(message_t *this, message_t *fragment);
! 313:
! 314: /**
! 315: * Gets the source host information.
! 316: *
! 317: * @warning Returned host_t object is not getting cloned,
! 318: * do not destroy nor modify.
! 319: *
! 320: * @return host_t object representing source host
! 321: */
! 322: host_t * (*get_source) (message_t *this);
! 323:
! 324: /**
! 325: * Sets the source host information.
! 326: *
! 327: * @warning host_t object is not getting cloned and gets destroyed by
! 328: * message_t.destroy or next call of message_t.set_source.
! 329: *
! 330: * @param host host_t object representing source host
! 331: */
! 332: void (*set_source) (message_t *this, host_t *host);
! 333:
! 334: /**
! 335: * Gets the destination host information.
! 336: *
! 337: * @warning Returned host_t object is not getting cloned,
! 338: * do not destroy nor modify.
! 339: *
! 340: * @return host_t object representing destination host
! 341: */
! 342: host_t * (*get_destination) (message_t *this);
! 343:
! 344: /**
! 345: * Sets the destination host information.
! 346: *
! 347: * @warning host_t object is not getting cloned and gets destroyed by
! 348: * message_t.destroy or next call of message_t.set_destination.
! 349: *
! 350: * @param host host_t object representing destination host
! 351: */
! 352: void (*set_destination) (message_t *this, host_t *host);
! 353:
! 354: /**
! 355: * Create an enumerator over all payloads.
! 356: *
! 357: * @return enumerator over payload_t
! 358: */
! 359: enumerator_t * (*create_payload_enumerator) (message_t *this);
! 360:
! 361: /**
! 362: * Remove the payload at the current enumerator position.
! 363: *
! 364: * @param enumerator enumerator created by create_payload_enumerator()
! 365: */
! 366: void (*remove_payload_at)(message_t *this, enumerator_t *enumerator);
! 367:
! 368: /**
! 369: * Find a payload of a specific type.
! 370: *
! 371: * Returns the first occurrence.
! 372: *
! 373: * @param type type of the payload to find
! 374: * @return payload, or NULL if no such payload found
! 375: */
! 376: payload_t* (*get_payload) (message_t *this, payload_type_t type);
! 377:
! 378: /**
! 379: * Get the first notify payload of a specific type.
! 380: *
! 381: * @param type type of notification payload
! 382: * @return notify payload, NULL if no such notify found
! 383: */
! 384: notify_payload_t* (*get_notify)(message_t *this, notify_type_t type);
! 385:
! 386: /**
! 387: * Returns a clone of the internally stored packet_t object.
! 388: *
! 389: * @return packet_t object as clone of internal one
! 390: */
! 391: packet_t *(*get_packet) (message_t *this);
! 392:
! 393: /**
! 394: * Returns a chunk pointing to internal packet_t data.
! 395: *
! 396: * @return packet data.
! 397: */
! 398: chunk_t (*get_packet_data) (message_t *this);
! 399:
! 400: /**
! 401: * Returns internally stored packet_t* objects for each fragment.
! 402: *
! 403: * @return enumerator internal packet_t* objects
! 404: */
! 405: enumerator_t *(*get_fragments)(message_t *this);
! 406:
! 407: /**
! 408: * Destroys a message and all including objects.
! 409: */
! 410: void (*destroy) (message_t *this);
! 411: };
! 412:
! 413: /**
! 414: * Creates a message_t object from an incoming UDP packet.
! 415: *
! 416: * The given packet gets owned by the message. The message is uninitialized,
! 417: * call parse_header() to populate header fields.
! 418: *
! 419: * @param packet packet_t object which is assigned to message
! 420: * @return message_t object
! 421: */
! 422: message_t *message_create_from_packet(packet_t *packet);
! 423:
! 424: /**
! 425: * Creates an empty message_t object for a specific major/minor version.
! 426: *
! 427: * - exchange_type is set to NOT_SET
! 428: * - original_initiator is set to TRUE
! 429: * - is_request is set to TRUE
! 430: *
! 431: * @param major major IKE version of this message
! 432: * @param minor minor IKE version of this message
! 433: * @return message_t object
! 434: */
! 435: message_t *message_create(int major, int minor);
! 436:
! 437: /**
! 438: * Creates a message_t object that is used to reassemble fragmented messages.
! 439: *
! 440: * Use add_fragment() to add fragments.
! 441: *
! 442: * @param fragment initial fragment (is not added)
! 443: * @return message_t object, NULL if fragment is not actually one
! 444: */
! 445: message_t *message_create_defrag(message_t *fragment);
! 446:
! 447: #endif /** MESSAGE_H_ @}*/
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to message.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / strongswan / src / libcharon / encoding