ikev1: Move fragment generation to message_t
[strongswan.git] / src / libcharon / encoding / message.h
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 * 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, 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 * 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 * Split the (generated) message into fragments of the given size (total IP
269 * datagram length).
270 *
271 * @note Only supported for IKEv1 at the moment.
272 *
273 * @param frag_len fragment length (maximum total IP datagram length), 0
274 * for default value depending on address family
275 * @param fragments receives an enumerator with message_t* (not generated),
276 * which are owned by the enumerator
277 * @return
278 * - SUCCESS if message could be fragmented
279 * - ALREADY_DONE if message does not need to be fragmented
280 * - INVALID_STATE if message was not generated or is IKEv2
281 * - FAILED if fragmentation failed
282 */
283 status_t (*fragment)(message_t *this, size_t frag_len,
284 enumerator_t **fragments);
285
286 /**
287 * Gets the source host informations.
288 *
289 * @warning Returned host_t object is not getting cloned,
290 * do not destroy nor modify.
291 *
292 * @return host_t object representing source host
293 */
294 host_t * (*get_source) (message_t *this);
295
296 /**
297 * Sets the source host informations.
298 *
299 * @warning host_t object is not getting cloned and gets destroyed by
300 * message_t.destroy or next call of message_t.set_source.
301 *
302 * @param host host_t object representing source host
303 */
304 void (*set_source) (message_t *this, host_t *host);
305
306 /**
307 * Gets the destination host informations.
308 *
309 * @warning Returned host_t object is not getting cloned,
310 * do not destroy nor modify.
311 *
312 * @return host_t object representing destination host
313 */
314 host_t * (*get_destination) (message_t *this);
315
316 /**
317 * Sets the destination host informations.
318 *
319 * @warning host_t object is not getting cloned and gets destroyed by
320 * message_t.destroy or next call of message_t.set_destination.
321 *
322 * @param host host_t object representing destination host
323 */
324 void (*set_destination) (message_t *this, host_t *host);
325
326 /**
327 * Create an enumerator over all payloads.
328 *
329 * @return enumerator over payload_t
330 */
331 enumerator_t * (*create_payload_enumerator) (message_t *this);
332
333 /**
334 * Remove the payload at the current enumerator position.
335 *
336 * @param enumerator enumerator created by create_payload_enumerator()
337 */
338 void (*remove_payload_at)(message_t *this, enumerator_t *enumerator);
339
340 /**
341 * Find a payload of a specific type.
342 *
343 * Returns the first occurrence.
344 *
345 * @param type type of the payload to find
346 * @return payload, or NULL if no such payload found
347 */
348 payload_t* (*get_payload) (message_t *this, payload_type_t type);
349
350 /**
351 * Get the first notify payload of a specific type.
352 *
353 * @param type type of notification payload
354 * @return notify payload, NULL if no such notify found
355 */
356 notify_payload_t* (*get_notify)(message_t *this, notify_type_t type);
357
358 /**
359 * Returns a clone of the internal stored packet_t object.
360 *
361 * @return packet_t object as clone of internal one
362 */
363 packet_t * (*get_packet) (message_t *this);
364
365 /**
366 * Returns a chunk pointing to internal packet_t data.
367 *
368 * @return packet data.
369 */
370 chunk_t (*get_packet_data) (message_t *this);
371
372 /**
373 * Destroys a message and all including objects.
374 */
375 void (*destroy) (message_t *this);
376 };
377
378 /**
379 * Creates a message_t object from an incoming UDP packet.
380 *
381 * The given packet gets owned by the message. The message is uninitialized,
382 * call parse_header() to populate header fields.
383 *
384 * @param packet packet_t object which is assigned to message
385 * @return message_t object
386 */
387 message_t *message_create_from_packet(packet_t *packet);
388
389 /**
390 * Creates an empty message_t object for a specific major/minor version.
391 *
392 * - exchange_type is set to NOT_SET
393 * - original_initiator is set to TRUE
394 * - is_request is set to TRUE
395 *
396 * @param major major IKE version of this message
397 * @param minor minor IKE version of this message
398 * @return message_t object
399 */
400 message_t *message_create(int major, int minor);
401
402 #endif /** MESSAGE_H_ @}*/