Annotation of embedaddon/strongswan/src/libcharon/encoding/message.h, revision 1.1.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