some message code cleanups
[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 Jan Hutter, Martin Willi
11 * Hochschule fuer Technik Rapperswil
12 *
13 * This program is free software; you can redistribute it and/or modify it
14 * under the terms of the GNU General Public License as published by the
15 * Free Software Foundation; either version 2 of the License, or (at your
16 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
17 *
18 * This program is distributed in the hope that it will be useful, but
19 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
20 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
21 * for more details.
22 */
23
24 #ifndef MESSAGE_H_
25 #define MESSAGE_H_
26
27 #include <types.h>
28 #include <sa/ike_sa_id.h>
29 #include <network/packet.h>
30 #include <encoding/payloads/ike_header.h>
31 #include <encoding/payloads/notify_payload.h>
32 #include <utils/linked_list.h>
33 #include <crypto/crypters/crypter.h>
34 #include <crypto/signers/signer.h>
35
36
37 typedef struct message_t message_t;
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 * @warning ike_sa_id gets cloned internaly and
124 * so can be destroyed afterwards.
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 * @warning The returned ike_sa_id is a clone of the internal one.
135 * So it has to be destroyed by the caller.
136 *
137 * @param this message_t object
138 * @param ike_sa_id pointer to ike_sa_id pointer which will be set
139 * @return
140 * - SUCCESS
141 * - FAILED if no ike_sa_id is set
142 */
143 status_t (*get_ike_sa_id) (message_t *this,ike_sa_id_t **ike_sa_id);
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 header could be parsed
223 * - NOT_SUPPORTED if ciritcal unknown payloads found
224 * - FAILED if message type is not suppported!
225 * - PARSE_ERROR if corrupted/invalid data found
226 * - VERIFY_ERROR if verification of some payload failed
227 * - INVALID_STATE if crypter/signer not supplied, but needed
228 */
229 status_t (*parse_body) (message_t *this, crypter_t *crypter, signer_t *signer);
230
231 /**
232 * @brief Generates the UDP packet of specific message.
233 *
234 * Payloads which must be encrypted are generated first and added to
235 * an encryption payload. This encryption payload will get encrypted via
236 * the supplied crypter. Then all other payloads and the header get generated.
237 * After that, the checksum is added to the encryption payload over the full
238 * message.
239 * Crypter/signer can be omitted (by passing NULL) when no encryption
240 * payload is expected.
241 *
242 * @param this message_t object
243 * @param crypter crypter to use when a payload must be encrypted
244 * @param signer signer to build a mac
245 * @return
246 * - SUCCESS if packet could be generated
247 * - INVALID_STATE if exchange type is currently not set
248 * - NOT_FOUND if no rules found for message generation
249 * - INVALID_STATE if crypter/signer not supplied but needed.
250 */
251 status_t (*generate) (message_t *this, crypter_t *crypter, signer_t *signer, packet_t **packet);
252
253 /**
254 * @brief Gets the source host informations.
255 *
256 * @warning Returned host_t object is not getting cloned,
257 * do not destroy nor modify.
258 *
259 * @param this message_t object
260 * @return host_t object representing source host
261 */
262 host_t * (*get_source) (message_t *this);
263
264 /**
265 * @brief Sets the source host informations.
266 *
267 * @warning host_t object is not getting cloned and gets destroyed by
268 * message_t.destroy or next call of message_t.set_source.
269 *
270 * @param this message_t object
271 * @param host host_t object representing source host
272 */
273 void (*set_source) (message_t *this, host_t *host);
274
275 /**
276 * @brief Gets the destination 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 destination host
283 */
284 host_t * (*get_destination) (message_t *this);
285
286 /**
287 * @brief Sets the destination 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_destination.
291 *
292 * @param this message_t object
293 * @param host host_t object representing destination host
294 */
295 void (*set_destination) (message_t *this, host_t *host);
296
297 /**
298 * @brief Returns an iterator on all stored payloads.
299 *
300 * @warning Don't insert payloads over this iterator.
301 * Use add_payload() instead.
302 *
303 * @param this message_t object
304 * @return iterator_t object which has to get destroyd by the caller
305 */
306 iterator_t * (*get_payload_iterator) (message_t *this);
307
308 /**
309 * @brief Returns a clone of the internal stored packet_t object.
310 *
311 * @param this message_t object
312 * @return packet_t object as clone of internal one
313 */
314 packet_t * (*get_packet) (message_t *this);
315
316 /**
317 * @brief Returns a clone of the internal stored packet_t data.
318 *
319 * @param this message_t object
320 * @return clone of the internal stored packet_t data.
321 */
322 chunk_t (*get_packet_data) (message_t *this);
323
324 /**
325 * @brief Check if a message is encoded.
326 *
327 * Check if the packet is in a generated (and encrypted) form available
328 * and can be passed down to the socket. If not, it has to be generated
329 * first.
330 *
331 * @param this message_t object
332 * @return TRUE if encoded, FALSE if not
333 */
334 bool (*is_encoded) (message_t *this);
335
336
337 /**
338 * @brief Destroys a message and all including objects.
339 *
340 * @param this message_t object
341 */
342 void (*destroy) (message_t *this);
343 };
344
345 /**
346 * @brief Creates an message_t object from a incoming UDP Packet.
347 *
348 * @warning the given packet_t object is not copied and gets
349 * destroyed in message_t's destroy call.
350 *
351 * @warning Packet is not parsed in here!
352 *
353 * - exchange_type is set to NOT_SET
354 * - original_initiator is set to TRUE
355 * - is_request is set to TRUE
356 * Call message_t.parse_header afterwards.
357 *
358 * @param packet packet_t object which is assigned to message
359 * @return message_t object
360 *
361 * @ingroup encoding
362 */
363 message_t * message_create_from_packet(packet_t *packet);
364
365
366 /**
367 * @brief Creates an empty message_t object.
368 *
369 * - exchange_type is set to NOT_SET
370 * - original_initiator is set to TRUE
371 * - is_request is set to TRUE
372 *
373 * @return message_t object
374 *
375 * @ingroup encoding
376 */
377 message_t * message_create(void);
378
379 #endif /*MESSAGE_H_*/