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