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