1 /*
2
3 silcmessage.h
4
5 Author: Pekka Riikonen <priikone@silcnet.org>
6
7 Copyright (C) 1997 - 2007 Pekka Riikonen
8
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; version 2 of the License.
12
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
17
18 */
19
20 /****h* silccore/SILC Message Interface
21 *
22 * DESCRIPTION
23 *
24 * This interface includes the implementation of the Message Payload that
25 * is used to send private messages and channel messages. The interface
26 * is also able to automatically provide digital signature in the messages
27 * if it is requested. Message digital signatures may also be verified with
28 * this interface.
29 *
30 ***/
31
32 #ifndef SILCMESSAGE_H
33 #define SILCMESSAGE_H
34
35 /****s* silccore/SilcMessageAPI/SilcMessagePayload
36 *
37 * NAME
38 *
39 * typedef struct SilcMessagePayloadObject
40 * *SilcMessagePayload, SilcMessagePayloadStruct;
41 *
42 *
43 * DESCRIPTION
44 *
45 * This context is the actual Message Payload and is allocated
46 * by silc_message_payload_parse and given as argument usually
47 * to all silc_message_* functions. It is freed by the
48 * silc_message_payload_free function.
49 *
50 ***/
51 typedef struct SilcMessagePayloadObject
52 *SilcMessagePayload, SilcMessagePayloadStruct;
53
54 /****d* silccore/SilcMessageAPI/SilcMessageFlags
55 *
56 * NAME
57 *
58 * typedef SilcUInt16 SilcMessageFlags;
59 *
60 * DESCRIPTION
61 *
62 * The message flags type definition and the message flags. The
63 * message flags are used to indicate some status of the message.
64 *
65 * SOURCE
66 */
67 typedef SilcUInt16 SilcMessageFlags;
68
69 /* The message flags */
70 #define SILC_MESSAGE_FLAG_NONE 0x0000 /* No flags */
71 #define SILC_MESSAGE_FLAG_AUTOREPLY 0x0001 /* Automatically replied */
72 #define SILC_MESSAGE_FLAG_NOREPLY 0x0002 /* Send no reply to this */
73 #define SILC_MESSAGE_FLAG_ACTION 0x0004 /* Action message */
74 #define SILC_MESSAGE_FLAG_NOTICE 0x0008 /* Notice message */
75 #define SILC_MESSAGE_FLAG_REQUEST 0x0010 /* A request */
76 #define SILC_MESSAGE_FLAG_SIGNED 0x0020 /* Message is signed */
77 #define SILC_MESSAGE_FLAG_REPLY 0x0040 /* A reply */
78 #define SILC_MESSAGE_FLAG_DATA 0x0080 /* MIME object */
79 #define SILC_MESSAGE_FLAG_UTF8 0x0100 /* UTF-8 string */
80 #define SILC_MESSAGE_FLAG_ACK 0x0200 /* ACK messages */
81 #define SILC_MESSAGE_FLAG_STOP 0x0400 /* Stop indication */
82 #define SILC_MESSAGE_FLAG_RESERVED 0x0800 /* to 0x1000 */
83 #define SILC_MESSAGE_FLAG_PRIVATE 0x2000 /* to 0x8000 */
84 /***/
85
86 /****f* silccore/SilcMessageAPI/silc_message_payload_decrypt
87 *
88 * SYNOPSIS
89 *
90 * SilcBool silc_message_payload_decrypt(unsigned char *data,
91 * size_t data_len,
92 * SilcBool private_message,
93 * SilcBool static_key,
94 * SilcCipher cipher,
95 * SilcHmac hmac,
96 * unsigned char *sender_id,
97 * SilcUInt32 sender_id_len,
98 * unsigned char *receiver_id,
99 * SilcUInt32 receiver_id_len,
100 * SilcBool check_mac);
101 *
102 * DESCRIPTION
103 *
104 * Decrypt Message Payload indicated by `data'. If the payload is
105 * channel message then `private_message' is FALSE, and if it is
106 * private message it is TRUE. If the private message key is static
107 * (pre-shared key) then protocol dictates that the IV is present
108 * and `static_key' must be set to TRUE. If the key is not static
109 * (Key Agreement was done for the key) then it MUST be FALSE. For
110 * channel messages the `static_key' is ignored.
111 *
112 * The `sender_id' and `receiver_id' are the IDs from the packet header
113 * of the packet where this message payload was received.
114 *
115 * This is usually used by the Message Payload interface itself but can
116 * be called by the appliation if separate decryption process is required.
117 * For example server might need to call this directly in some
118 * circumstances. The `cipher' is used to decrypt the payload. If
119 * `check_mac' is FALSE then MAC is not verified.
120 *
121 ***/
122 SilcBool silc_message_payload_decrypt(unsigned char *data,
123 size_t data_len,
124 SilcBool private_message,
125 SilcBool static_key,
126 SilcCipher cipher,
127 SilcHmac hmac,
128 unsigned char *sender_id,
129 SilcUInt32 sender_id_len,
130 unsigned char *receiver_id,
131 SilcUInt32 receiver_id_len,
132 SilcBool check_mac);
133
134 /****f* silccore/SilcMessageAPI/silc_message_payload_parse
135 *
136 * SYNOPSIS
137 *
138 * SilcMessagePayload
139 * silc_message_payload_parse(unsigned char *payload,
140 * SilcUInt32 payload_len,
141 * SilcBool private_message,
142 * SilcBool static_key,
143 * SilcCipher cipher,
144 * SilcHmac hmac,
145 * unsigned char *sender_id,
146 * SilcUInt32 sender_id_len,
147 * unsigned char *receiver_id,
148 * SilcUInt32 receiver_id_len,
149 * SilcStack stack,
150 * SilcBool no_allocation,
151 * SilcMessagePayload message);
152 *
153 * DESCRIPTION
154 *
155 * Parses Message Payload returning new payload structure. This also
156 * decrypts the payload and checks the MAC. If the payload is
157 * channel message then `private_message' is FALSE, and if it is
158 * private message it is TRUE. If the private message key is static
159 * (pre-shared key) then protocol dictates that the IV is present
160 * and `static_key' must be set to TRUE. If the key is not static
161 * (Key Agreement was done for the key) then it MUST be FALSE. For
162 * channel messages the `static_key' is ignored.
163 *
164 * If the `hmac' is no provided then the MAC of the channel message is
165 * not verified. If the message is private message and `cipher' is NULL
166 * then this assumes that the packet was decrypted with session keys
167 * (no private message key) and this merely decodes the payload.
168 *
169 * The `sender_id' and `receiver_id' are the IDs from the packet header
170 * of the packet where this message payload was received.
171 *
172 * If the `message' is non-NULL then that pre-allocated context is
173 * used in parsing. Same context is returned. Otherwise new context
174 * is allocated and returned. If the `stack' is non-NULL then memory
175 * is allocated from that stack. If `no_allocation' is TRUE then the
176 * `message' must be provided and data is merely parsed and referenced
177 * from `payload' and will become invalid when `payload' invalidates.
178 * If `no_allocation' is TRUE the routine does not do any allocations.
179 *
180 ***/
181 SilcMessagePayload
182 silc_message_payload_parse(unsigned char *payload,
183 SilcUInt32 payload_len,
184 SilcBool private_message,
185 SilcBool static_key,
186 SilcCipher cipher,
187 SilcHmac hmac,
188 unsigned char *sender_id,
189 SilcUInt32 sender_id_len,
190 unsigned char *receiver_id,
191 SilcUInt32 receiver_id_len,
192 SilcStack stack,
193 SilcBool no_allocation,
194 SilcMessagePayload message);
195
196 /****f* silccore/SilcMessageAPI/silc_message_payload_encrypt
197 *
198 * SYNOPSIS
199 *
200 * SilcBool silc_message_payload_encrypt(unsigned char *data,
201 * SilcUInt32 data_len,
202 * SilcUInt32 true_len,
203 * unsigned char *iv,
204 * SilcID *sender_id,
205 * SilcID *receiver_id,
206 * SilcCipher cipher,
207 * SilcHmac hmac);
208 *
209 * DESCRIPTION
210 *
211 * This function is used to encrypt the Messsage Payload which is
212 * the `data' and `data_len'. The `data_len' is the data length which
213 * is used to create MAC out of. The `data' MUST have additional space
214 * after `true_len' bytes for the MAC which is appended to the data.
215 * The `sender_id' is the ID message sender and `receiver_id' is ID of
216 * message receiver.
217 *
218 * This is usually used by the Message Payload interface itself but can
219 * be called by the appliation if separate encryption process is required.
220 * For example server might need to call this directly in some
221 * circumstances. The `cipher' is used to encrypt the payload and `hmac'
222 * to compute the MAC for the payload.
223 *
224 ***/
225 SilcBool silc_message_payload_encrypt(unsigned char *data,
226 SilcUInt32 data_len,
227 SilcUInt32 true_len,
228 unsigned char *iv,
229 SilcID *sender_id,
230 SilcID *receiver_id,
231 SilcCipher cipher,
232 SilcHmac hmac);
233
234 /****f* silccore/SilcMessageAPI/SilcMessagePayloadEncoded
235 *
236 * SYNOPSIS
237 *
238 * typedef void (*SilcMessagePayloadEncoded)(const SilcBuffer message,
239 * void *context);
240 *
241 * DESCRIPTION
242 *
243 * This callback is given as arugment to silc_message_payload_encode
244 * and will be called when the message payload has been encoded. If
245 * `message' is NULL, encoding failed.
246 *
247 ***/
248 typedef void (*SilcMessagePayloadEncoded)(SilcBuffer message,
249 void *context);
250
251 /****f* silccore/SilcMessageAPI/silc_message_payload_encode
252 *
253 * SYNOPSIS
254 *
255 * SilcAsyncOperation
256 * silc_message_payload_encode(SilcMessageFlags flags,
257 * const unsigned char *data,
258 * SilcUInt32 data_len,
259 * SilcBool generate_iv,
260 * SilcBool private_message,
261 * SilcCipher cipher,
262 * SilcHmac hmac,
263 * SilcRng rng,
264 * SilcPublicKey public_key,
265 * SilcPrivateKey private_key,
266 * SilcHash hash,
267 * SilcID *sender_id,
268 * SilcID *receiver_id,
269 * SilcStack stack,
270 * SilcMessagePayloadEncoded encoded,
271 * void *context);
272 *
273 * DESCRIPTION
274 *
275 * Encodes a Message Payload into a buffer and returns it to the `encoded'
276 * callback. This is used to encode channel messages and private messages
277 * into a packet. If `private_message' is FALSE then this encodes channel
278 * message, if it is TRUE this encodes private message. If
279 * `private_message' is TRUE then `generate_iv' MUST be FALSE if the private
280 * message key `cipher' is not static key (pre-shared key). If it is static
281 * key then protocol dictates that IV must be present in the Message Payload
282 * and `generate_iv' must be TRUE. The caller must know whether the key
283 * is static or not for private messages. If the key was generated with
284 * Key Agreement protocol then `generate_iv' is always FALSE. For
285 * channel messages `generate_iv' is always set to TRUE value.
286 *
287 * The `cipher' is the cipher used to encrypt the message and `hmac'
288 * is used to compute the MAC for the payload. If encoding private
289 * message that will be encrypted with session keys (no private message
290 * key) then `cipher' and `hmac' is NULL and this merely encodes the
291 * payload buffer, and the caller must encrypt the packet later.
292 * If `rng' is NULL then global RNG is used, if non-NULL then the
293 * `rng' is used (for IV and padding generation).
294 *
295 * The `public_key', `private_key' and `hash' are provided only if the
296 * flags includes SILC_MESSAGE_FLAG_SIGNED, in which case the message
297 * will be digitally signed. If `public_key' is non-NULL then it will
298 * be included in the message. The `private_message' and `hash' MUST
299 * be provided. The `hash' SHOULD be SHA1.
300 *
301 * The `sender_id' is the ID message sender and `receiver_id' is ID of
302 * message receiver.
303 *
304 * If `stack' is non-NULL the message payload is allocated from stack.
305 * The memory will be returned back to `stack' after the `encoded' has
306 * been called.
307 *
308 ***/
309 SilcAsyncOperation
310 silc_message_payload_encode(SilcMessageFlags flags,
311 const unsigned char *data,
312 SilcUInt32 data_len,
313 SilcBool generate_iv,
314 SilcBool private_message,
315 SilcCipher cipher,
316 SilcHmac hmac,
317 SilcRng rng,
318 SilcPublicKey public_key,
319 SilcPrivateKey private_key,
320 SilcHash hash,
321 SilcID *sender_id,
322 SilcID *receiver_id,
323 SilcStack stack,
324 SilcMessagePayloadEncoded encoded,
325 void *context);
326
327 /****f* silccore/SilcMessageAPI/silc_message_payload_free
328 *
329 * SYNOPSIS
330 *
331 * void silc_message_payload_free(SilcMessagePayload payload);
332 *
333 * DESCRIPTION
334 *
335 * Free's Message Payload and all data in it.
336 *
337 ***/
338 void silc_message_payload_free(SilcMessagePayload payload);
339
340 /****f* silccore/SilcMessageAPI/silc_message_get_flags
341 *
342 * SYNOPSIS
343 *
344 * SilcMessageFlags silc_message_get_flags(SilcMessagePayload payload);
345 *
346 * DESCRIPTION
347 *
348 * Returns the message flags from the payload.
349 *
350 ***/
351 SilcMessageFlags silc_message_get_flags(SilcMessagePayload payload);
352
353 /****f* silccore/SilcMessageAPI/silc_message_get_data
354 *
355 * SYNOPSIS
356 *
357 * unsigned char *
358 * silc_message_get_data(SilcMessagePayload payload,
359 * SilcUInt32 *data_len);
360 *
361 * DESCRIPTION
362 *
363 * Return the data in the payload, that is, the actual message data.
364 * The caller must not free it.
365 *
366 ***/
367 unsigned char *silc_message_get_data(SilcMessagePayload payload,
368 SilcUInt32 *data_len);
369
370 /****f* silccore/SilcMessageAPI/silc_message_get_mac
371 *
372 * SYNOPSIS
373 *
374 * unsigned char *
375 * silc_message_get_mac(SilcMessagePayload payload);
376 *
377 * DESCRIPTION
378 *
379 * Return the MAC of the payload. The caller must already know the
380 * length of the MAC. The caller must not free the MAC.
381 *
382 ***/
383 unsigned char *silc_message_get_mac(SilcMessagePayload payload);
384
385 /****f* silccore/SilcMessageAPI/silc_message_signed_verify
386 *
387 * SYNOPSIS
388 *
389 * SilcAsyncOperation
390 * silc_message_signed_verify(SilcMessagePayload message,
391 * SilcPublicKey remote_public_key,
392 * SilcHash hash,
393 * SilcAuthResultCb result,
394 * void *context);
395 *
396 *
397 * DESCRIPTION
398 *
399 * This routine can be used to verify the digital signature from the
400 * message indicated by `message'. The signature is present only if
401 * the SILC_MESSAGE_FLAG_SIGNED is set in the message flags. The
402 * result of the verification is returned to `result' callback.
403 *
404 ***/
405 SilcAsyncOperation silc_message_signed_verify(SilcMessagePayload message,
406 SilcPublicKey remote_public_key,
407 SilcHash hash,
408 SilcAuthResultCb result,
409 void *context);
410
411 /****f* silccore/SilcMessageAPI/silc_message_signed_get_public_key
412 *
413 * SYNOPSIS
414 *
415 * SilcPublicKey
416 * silc_message_signed_get_public_key(SilcMessagePayload payload,
417 * const unsigned char **pk_data,
418 * SilcUInt32 *pk_data_len);
419 *
420 * DESCRIPTION
421 *
422 * Returns the decoded SilcPublicKey from the message payload or NULL
423 * if it does not include public key. The caller must free the returned
424 * public key pointer. This also returns the raw public key (before
425 * decoding) into `pk_data' and `pk_data_len' if they are provided. The
426 * caller must not free these pointers.
427 *
428 ***/
429 SilcPublicKey
430 silc_message_signed_get_public_key(SilcMessagePayload payload,
431 const unsigned char **pk_data,
432 SilcUInt32 *pk_data_len);
433
434 #include "silcmessage_i.h"
435
436 #endif /* SILCMESSAGE_H */
437
This page was automatically generated by the LXR engine.
Free-text search provided by Glimpse