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