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