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