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