implemented enumerator for linked_list
[strongswan.git] / src / charon / encoding / message.h
1 /**
2 * @file message.h
3 *
4 * @brief Interface of message_t.
5 *
6 */
7
8 /*
9 * Copyright (C) 2006-2007 Tobias Brunner
10 * Copyright (C) 2006 Daniel Roethlisberger
11 * Copyright (C) 2005-2006 Martin Willi
12 * Copyright (C) 2005 Jan Hutter
13 * Hochschule fuer Technik Rapperswil
14 *
15 * This program is free software; you can redistribute it and/or modify it
16 * under the terms of the GNU General Public License as published by the
17 * Free Software Foundation; either version 2 of the License, or (at your
18 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
19 *
20 * This program is distributed in the hope that it will be useful, but
21 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
22 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
23 * for more details.
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 * @brief 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 * @b Constructors:
49 * - message_create()
50 * - message_create_from_packet()
51 * - message_create_notify_reply()
52 *
53 * @ingroup encoding
54 */
55 struct message_t {
56
57 /**
58 * @brief Sets the IKE major version of the message.
59 *
60 * @param this message_t object
61 * @param major_version major version to set
62 */
63 void (*set_major_version) (message_t *this,u_int8_t major_version);
64
65 /**
66 * @brief Gets the IKE major version of the message.
67 *
68 * @param this message_t object
69 * @return major version of the message
70 */
71 u_int8_t (*get_major_version) (message_t *this);
72
73 /**
74 * @brief Sets the IKE minor version of the message.
75 *
76 * @param this message_t object
77 * @param minor_version minor version to set
78 */
79 void (*set_minor_version) (message_t *this,u_int8_t minor_version);
80
81 /**
82 * @brief Gets the IKE minor version of the message.
83 *
84 * @param this message_t object
85 * @return minor version of the message
86 */
87 u_int8_t (*get_minor_version) (message_t *this);
88
89 /**
90 * @brief Sets the Message ID of the message.
91 *
92 * @param this message_t object
93 * @param message_id message_id to set
94 */
95 void (*set_message_id) (message_t *this,u_int32_t message_id);
96
97 /**
98 * @brief Gets the Message ID of the message.
99 *
100 * @param this message_t object
101 * @return message_id type of the message
102 */
103 u_int32_t (*get_message_id) (message_t *this);
104
105 /**
106 * @brief Gets the initiator SPI of the message.
107 *
108 * @param this message_t object
109 * @return initiator spi of the message
110 */
111 u_int64_t (*get_initiator_spi) (message_t *this);
112
113 /**
114 * @brief Gets the responder SPI of the message.
115 *
116 * @param this message_t object
117 * @return responder spi of the message
118 */
119 u_int64_t (*get_responder_spi) (message_t *this);
120
121 /**
122 * @brief Sets the IKE_SA ID of the message.
123 *
124 * ike_sa_id gets cloned.
125 *
126 * @param this message_t object
127 * @param ike_sa_id ike_sa_id to set
128 */
129 void (*set_ike_sa_id) (message_t *this, ike_sa_id_t * ike_sa_id);
130
131 /**
132 * @brief Gets the IKE_SA ID of the message.
133 *
134 * The ike_sa_id points to the message internal id, do not modify.
135 *
136 * @param this message_t object
137 * @return ike_sa_id of message
138 */
139 ike_sa_id_t *(*get_ike_sa_id) (message_t *this);
140
141 /**
142 * @brief Sets the exchange type of the message.
143 *
144 * @param this message_t object
145 * @param exchange_type exchange_type to set
146 */
147 void (*set_exchange_type) (message_t *this,exchange_type_t exchange_type);
148
149 /**
150 * @brief Gets the exchange type of the message.
151 *
152 * @param this message_t object
153 * @return exchange type of the message
154 */
155 exchange_type_t (*get_exchange_type) (message_t *this);
156
157 /**
158 * @brief Gets the payload type of the first payload.
159 *
160 * @param this message_t object
161 * @return payload type of the first payload
162 */
163 payload_type_t (*get_first_payload_type) (message_t *this);
164
165 /**
166 * @brief Sets the request flag.
167 *
168 * @param this message_t object
169 * @param original_initiator TRUE if message is a request, FALSE if it is a reply
170 */
171 void (*set_request) (message_t *this,bool request);
172
173 /**
174 * @brief Gets request flag.
175 *
176 * @param this message_t object
177 * @return TRUE if message is a request, FALSE if it is a reply
178 */
179 bool (*get_request) (message_t *this);
180
181 /**
182 * @brief Append a payload to the message.
183 *
184 * If the payload must be encrypted is not specified here. Encryption
185 * of payloads is evaluated via internal rules for the messages and
186 * is done before generation. The order of payloads may change, since
187 * all payloads to encrypt are added to the encryption payload, which is
188 * always the last one.
189 *
190 * @param this message_t object
191 * @param payload payload to append
192 */
193 void (*add_payload) (message_t *this, payload_t *payload);
194
195 /**
196 * @brief Build a notify payload and add it to the message.
197 *
198 * This is a helper method to create notify messages or add
199 * notify payload to messages. The flush parameter specifies if existing
200 * payloads should get removed before appending the notify.
201 *
202 * @param this message_t object
203 * @param flush TRUE to remove existing payloads
204 * @param type type of the notify
205 * @param data a chunk of data to add to the notify, gets cloned
206 */
207 void (*add_notify) (message_t *this, bool flush, notify_type_t type,
208 chunk_t data);
209
210 /**
211 * @brief Parses header of message.
212 *
213 * Begins parisng of a message created via message_create_from_packet().
214 * The parsing context is stored, so a subsequent call to parse_body()
215 * will continue the parsing process.
216 *
217 * @param this message_t object
218 * @return
219 * - SUCCESS if header could be parsed
220 * - PARSE_ERROR if corrupted/invalid data found
221 * - FAILED if consistence check of header failed
222 */
223 status_t (*parse_header) (message_t *this);
224
225 /**
226 * @brief Parses body of message.
227 *
228 * The body gets not only parsed, but rather it gets verified.
229 * All payloads are verified if they are allowed to exist in the message
230 * of this type and if their own structure is ok.
231 * If there are encrypted payloads, they get decrypted via the supplied
232 * crypter. Also the message integrity gets verified with the supplied
233 * signer.
234 * Crypter/signer can be omitted (by passing NULL) when no encryption
235 * payload is expected.
236 *
237 * @param this message_t object
238 * @param crypter crypter to decrypt encryption payloads
239 * @param signer signer to verifiy a message with an encryption payload
240 * @return
241 * - SUCCESS if parsing successful
242 * - NOT_SUPPORTED if ciritcal unknown payloads found
243 * - NOT_SUPPORTED if message type is not supported!
244 * - PARSE_ERROR if message parsing failed
245 * - VERIFY_ERROR if message verification failed (bad syntax)
246 * - FAILED if integrity check failed
247 * - INVALID_STATE if crypter/signer not supplied, but needed
248 */
249 status_t (*parse_body) (message_t *this, crypter_t *crypter, signer_t *signer);
250
251 /**
252 * @brief Generates the UDP packet of specific message.
253 *
254 * Payloads which must be encrypted are generated first and added to
255 * an encryption payload. This encryption payload will get encrypted via
256 * the supplied crypter. Then all other payloads and the header get generated.
257 * After that, the checksum is added to the encryption payload over the full
258 * message.
259 * Crypter/signer can be omitted (by passing NULL) when no encryption
260 * payload is expected.
261 * Generation is only done once, multiple calls will just return a packet copy.
262 *
263 * @param this message_t object
264 * @param crypter crypter to use when a payload must be encrypted
265 * @param signer signer to build a mac
266 * @param packet copy of generated packet
267 * @return
268 * - SUCCESS if packet could be generated
269 * - INVALID_STATE if exchange type is currently not set
270 * - NOT_FOUND if no rules found for message generation
271 * - INVALID_STATE if crypter/signer not supplied but needed.
272 */
273 status_t (*generate) (message_t *this, crypter_t *crypter, signer_t *signer, packet_t **packet);
274
275 /**
276 * @brief Gets the source host informations.
277 *
278 * @warning Returned host_t object is not getting cloned,
279 * do not destroy nor modify.
280 *
281 * @param this message_t object
282 * @return host_t object representing source host
283 */
284 host_t * (*get_source) (message_t *this);
285
286 /**
287 * @brief Sets the source host informations.
288 *
289 * @warning host_t object is not getting cloned and gets destroyed by
290 * message_t.destroy or next call of message_t.set_source.
291 *
292 * @param this message_t object
293 * @param host host_t object representing source host
294 */
295 void (*set_source) (message_t *this, host_t *host);
296
297 /**
298 * @brief Gets the destination host informations.
299 *
300 * @warning Returned host_t object is not getting cloned,
301 * do not destroy nor modify.
302 *
303 * @param this message_t object
304 * @return host_t object representing destination host
305 */
306 host_t * (*get_destination) (message_t *this);
307
308 /**
309 * @brief Sets the destination host informations.
310 *
311 * @warning host_t object is not getting cloned and gets destroyed by
312 * message_t.destroy or next call of message_t.set_destination.
313 *
314 * @param this message_t object
315 * @param host host_t object representing destination host
316 */
317 void (*set_destination) (message_t *this, host_t *host);
318
319 /**
320 * @brief Returns an iterator on all stored payloads.
321 *
322 * @warning Don't insert payloads over this iterator.
323 * Use add_payload() instead.
324 *
325 * @param this message_t object
326 * @return iterator_t object which has to get destroyd by the caller
327 */
328 iterator_t * (*get_payload_iterator) (message_t *this);
329
330 /**
331 * @brief Find a payload of a specific type.
332 *
333 * Returns the first occurance.
334 *
335 * @param this message_t object
336 * @param type type of the payload to find
337 * @return payload, or NULL if no such payload found
338 */
339 payload_t* (*get_payload) (message_t *this, payload_type_t type);
340
341 /**
342 * @brief Returns a clone of the internal stored packet_t object.
343 *
344 * @param this message_t object
345 * @return packet_t object as clone of internal one
346 */
347 packet_t * (*get_packet) (message_t *this);
348
349 /**
350 * @brief Returns a clone of the internal stored packet_t data.
351 *
352 * @param this message_t object
353 * @return clone of the internal stored packet_t data.
354 */
355 chunk_t (*get_packet_data) (message_t *this);
356
357 /**
358 * @brief Destroys a message and all including objects.
359 *
360 * @param this message_t object
361 */
362 void (*destroy) (message_t *this);
363 };
364
365 /**
366 * @brief Creates an message_t object from a incoming UDP Packet.
367 *
368 * @warning the given packet_t object is not copied and gets
369 * destroyed in message_t's destroy call.
370 *
371 * @warning Packet is not parsed in here!
372 *
373 * - exchange_type is set to NOT_SET
374 * - original_initiator is set to TRUE
375 * - is_request is set to TRUE
376 * Call message_t.parse_header afterwards.
377 *
378 * @param packet packet_t object which is assigned to message
379 * @return message_t object
380 *
381 * @ingroup encoding
382 */
383 message_t * message_create_from_packet(packet_t *packet);
384
385
386 /**
387 * @brief Creates an empty message_t object.
388 *
389 * - exchange_type is set to NOT_SET
390 * - original_initiator is set to TRUE
391 * - is_request is set to TRUE
392 *
393 * @return message_t object
394 *
395 * @ingroup encoding
396 */
397 message_t * message_create(void);
398
399 #endif /*MESSAGE_H_*/