5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1997 - 2001 Pekka Riikonen
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; either version 2 of the License, or
12 (at your option) any later version.
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License for more details.
21 /****h* silccore/SILC Channel Interface
25 * Implementations of the Channel Payload, Channel Message Payload and
26 * Channel Key Payload. The Channel Payload represents new channel and
27 * is used to distribute the information of the new channel. The Channel
28 * Message Payload is used to deliver messages to the channel. The routines
29 * for Channel Message Payload also handles the encryption and decryption
30 * of the payload. Last, the Channel Key Payload is used to distribute
31 * a new key to the channel. It is done for example every time someone
32 * joins a channel or the old key expires.
39 #include "silcdlist.h"
41 /****s* silccore/SilcChannelAPI/SilcChannelPayload
45 * typedef struct SilcChannelPayloadStruct *SilcChannelPayload;
49 * This context is the actual Channel Payload and is allocated
50 * by silc_channel_payload_parse and given as argument usually to
51 * all silc_channel_payload_* functions. It is freed by the
52 * silc_channel_payload_free function.
55 typedef struct SilcChannelPayloadStruct *SilcChannelPayload;
57 /****s* silccore/SilcChannelAPI/SilcChannelMessagePayload
62 * SilcChannelMessagePayloadStruct *SilcChannelMessagePayload;
66 * This context is the actual Channel Message Payload and is allocated
67 * by silc_channel_message_payload_parse and given as argument usually to
68 * all silc_channel_message_payload_* functions. It is freed by the
69 * silc_channel_message_payload_free function.
72 typedef struct SilcChannelMessagePayloadStruct *SilcChannelMessagePayload;
74 /****s* silccore/SilcChannelAPI/SilcChannelKeyPayload
78 * typedef struct SilcChannelKeyPayloadStruct *SilcChannelKeyPayload;
82 * This context is the actual Channel Key Payload and is allocated
83 * by silc_channel_key_payload_parse and given as argument usually to
84 * all silc_channel_key_payload_* functions. It is freed by the
85 * silc_channel_key_payload_free function.
88 typedef struct SilcChannelKeyPayloadStruct *SilcChannelKeyPayload;
90 /****d* silccore/SilcChannelAPI/SilcMessageFlags
94 * typedef SilcUInt16 SilcMessageFlags;
98 * The message flags type definition and the message flags. The
99 * message flags are used to indicate some status of the message.
100 * These flags are also used by the private message interfaces.
104 typedef SilcUInt16 SilcMessageFlags;
106 /* The message flags (shared by both channel and private messages) */
107 #define SILC_MESSAGE_FLAG_NONE 0x0000 /* No flags */
108 #define SILC_MESSAGE_FLAG_AUTOREPLY 0x0001 /* Automatically replied */
109 #define SILC_MESSAGE_FLAG_NOREPLY 0x0002 /* Send no reply to this */
110 #define SILC_MESSAGE_FLAG_ACTION 0x0004 /* Action message */
111 #define SILC_MESSAGE_FLAG_NOTICE 0x0008 /* Notice message */
112 #define SILC_MESSAGE_FLAG_REQUEST 0x0010 /* A request */
113 #define SILC_MESSAGE_FLAG_SIGNED 0x0020 /* Message is signed */
114 #define SILC_MESSAGE_FLAG_REPLY 0x0040 /* A reply */
115 #define SILC_MESSAGE_FLAG_DATA 0x0080 /* MIME object */
116 #define SILC_MESSAGE_FLAG_UTF8 0x0100 /* UTF-8 string */
117 #define SILC_MESSAGE_FLAG_RESERVED 0x0200 /* to 0x0800 */
118 #define SILC_MESSAGE_FLAG_PRIVATE 0x1000 /* to 0x8000 */
123 /****f* silccore/SilcChannelAPI/silc_channel_payload_parse
128 * silc_channel_payload_parse(const unsigned char *payload,
129 * SilcUInt32 payload_len);
133 * Parses channel payload returning new channel payload structure. The
134 * `buffer' is the raw payload buffer.
137 SilcChannelPayload silc_channel_payload_parse(const unsigned char *payload,
138 SilcUInt32 payload_len);
140 /****f* silccore/SilcChannelAPI/silc_channel_payload_parse_list
145 * silc_channel_payload_parse_list(const unsigned char *payload,
146 * SilcUInt32 payload_len);
150 * Parses list of channel payloads returning list of payloads. This
151 * is equivalent to the silc_channel_payload_parse except that the `buffer'
152 * now includes multiple Channel Payloads one after the other.
155 SilcDList silc_channel_payload_parse_list(const unsigned char *payload,
156 SilcUInt32 payload_len);
158 /****f* silccore/SilcChannelAPI/silc_channel_payload_encode
162 * SilcBuffer silc_channel_payload_encode(const unsigned char *channel_name,
163 * SilcUInt16 channel_name_len,
164 * const unsigned char *channel_id,
165 * SilcUInt32 channel_id_len,
170 * Encode new channel payload and returns it as buffer.
173 SilcBuffer silc_channel_payload_encode(const unsigned char *channel_name,
174 SilcUInt16 channel_name_len,
175 const unsigned char *channel_id,
176 SilcUInt32 channel_id_len,
179 /****f* silccore/SilcChannelAPI/silc_channel_payload_free
183 * void silc_channel_payload_free(SilcChannelPayload payload);
187 * Frees Channel Payload and all data in it.
190 void silc_channel_payload_free(SilcChannelPayload payload);
192 /****f* silccore/SilcChannelAPI/silc_channel_payload_list_free
196 * void silc_channel_payload_list_free(SilcDList list);
200 * Frees list of Channel Payloads and all data in them.
203 void silc_channel_payload_list_free(SilcDList list);
205 /****f* silccore/SilcChannelAPI/silc_channel_get_name
209 * unsigned char *silc_channel_get_name(SilcChannelPayload payload,
210 * SilcUInt32 *channel_name_len);
214 * Return the channel name from the payload. The caller must not free it.
217 unsigned char *silc_channel_get_name(SilcChannelPayload payload,
218 SilcUInt32 *channel_name_len);
220 /****f* silccore/SilcChannelAPI/silc_channel_get_id
224 * unsigned char *silc_channel_get_id(SilcChannelPayload payload,
225 * SilcUInt32 *channel_id_len);
229 * Return the Channel ID data from the payload. The caller must not free it.
232 unsigned char *silc_channel_get_id(SilcChannelPayload payload,
233 SilcUInt32 *channel_id_len);
235 /****f* silccore/SilcChannelAPI/silc_channel_get_id_parse
239 * SilcChannelID *silc_channel_get_id_parse(SilcChannelPayload payload);
243 * Return the Channel ID as parsed ID. This is equivalent to the
244 * silc_channel_get_id execpt that the ID is already parsed. The caller
245 * must free the parsed Channel ID.
248 SilcChannelID *silc_channel_get_id_parse(SilcChannelPayload payload);
250 /****f* silccore/SilcChannelAPI/silc_channel_get_mode
254 * SilcUInt32 silc_channel_get_mode(SilcChannelPayload payload);
258 * Return the mode. The mode is arbitrary. It can be the mode of the
259 * channel or perhaps the mode of the client on the channel. The protocol
260 * dictates what the usage of the mode is in different circumstances.
263 SilcUInt32 silc_channel_get_mode(SilcChannelPayload payload);
265 /****f* silccore/SilcChannelAPI/silc_channel_message_payload_decrypt
269 * bool silc_channel_message_payload_decrypt(unsigned char *data,
276 * Decrypt the channel message. First push the IV out of the packet `data'.
277 * The IV is used in the decryption process. Then decrypt the message.
278 * After decryption, take the MAC from the decrypted packet, compute MAC
279 * and compare the MACs. If they match, the decryption was successful
280 * and we have the channel message ready to be displayed.
282 * This is usually used by the Channel Message interface itself but can
283 * be called by the appliation if separate decryption process is required.
284 * For example server might need to call this directly in some
285 * circumstances. The `cipher' is used to decrypt the payload.
287 * If the `hmac' is no provided then the MAC of the channel message is
291 bool silc_channel_message_payload_decrypt(unsigned char *data,
296 /****f* silccore/SilcChannelAPI/silc_channel_message_payload_parse
300 * SilcChannelMessagePayload
301 * silc_channel_message_payload_parse(const unsigned char *payload,
302 * SilcUInt32 payload_len,
308 * Parses channel message payload returning new channel payload structure.
309 * This also decrypts it and checks the MAC. The `cipher's is used to
310 * decrypt the payload.
312 * If the `hmac' is no provided then the MAC of the channel message is
316 SilcChannelMessagePayload
317 silc_channel_message_payload_parse(unsigned char *payload,
318 SilcUInt32 payload_len,
322 /****f* silccore/SilcChannelAPI/silc_channel_message_payload_encrypt
326 * bool silc_channel_message_payload_encrypt(unsigned char *data,
327 * SilcUInt32 data_len,
328 * SilcUInt32 true_len,
336 * This function is used to encrypt the Channel Messsage Payload which is
337 * the `data' and `data_len'. The `data_len' is the data length which is
338 * used to create MAC out of. The `true_len' is the true length of `data'
339 * message payload and is used assemble rest of the packet after MAC
340 * creation. The `true_len' length packet will then be encrypted.
342 * This is usually used by the Channel Message interface itself but can
343 * be called by the appliation if separate encryption process is required.
344 * For example server might need to call this directly in some
345 * circumstances. The `cipher' is used to encrypt the payload.
348 bool silc_channel_message_payload_encrypt(unsigned char *data,
356 /****f* silccore/SilcChannelAPI/silc_channel_message_payload_encode
360 * SilcBuffer silc_channel_message_payload_encode(SilcUInt16 flags,
361 * SilcUInt16 data_len,
362 * const unsigned char *data,
371 * Encodes channel message payload into a buffer and returns it. This
372 * is used to add channel message payload into a packet. As the channel
373 * payload is encrypted separately from other parts of the packet padding
374 * must be applied to the payload. The function generates the padding
375 * automatically from random data. The `cipher' is the cipher used
376 * encrypt the payload and `hmac' is used to compute the MAC for the
377 * payload. If `rng' is NULL then global RNG is used, if non-NULL then
381 SilcBuffer silc_channel_message_payload_encode(SilcUInt16 flags,
383 const unsigned char *data,
390 /****f* silccore/SilcChannelAPI/silc_channel_message_payload_free
395 * silc_channel_message_payload_free(SilcChannelMessagePayload payload);
399 * Free's Channel Message Payload and all data in it.
402 void silc_channel_message_payload_free(SilcChannelMessagePayload payload);
404 /****f* silccore/SilcChannelAPI/silc_channel_message_get_flags
409 * silc_channel_message_get_flags(SilcChannelMessagePayload payload);
413 * Returns the message flags from the payload.
417 silc_channel_message_get_flags(SilcChannelMessagePayload payload);
419 /****f* silccore/SilcChannelAPI/silc_channel_message_get_data
424 * silc_channel_message_get_data(SilcChannelMessagePayload payload,
425 * SilcUInt32 *data_len);
429 * Return the data in the payload, that is, the actual channel message.
430 * The caller must not free it.
433 unsigned char *silc_channel_message_get_data(SilcChannelMessagePayload payload,
434 SilcUInt32 *data_len);
436 /****f* silccore/SilcChannelAPI/silc_channel_message_get_mac
441 * silc_channel_message_get_mac(SilcChannelMessagePayload payload);
445 * Return the MAC of the payload. The caller must already know the
446 * length of the MAC. The caller must not free the MAC.
449 unsigned char *silc_channel_message_get_mac(SilcChannelMessagePayload payload);
451 /****f* silccore/SilcChannelAPI/silc_channel_message_get_iv
456 * silc_channel_message_get_iv(SilcChannelMessagePayload payload);
460 * Return the IV of the payload. The caller must already know the
461 * length of the IV. The caller must not free the IV.
464 unsigned char *silc_channel_message_get_iv(SilcChannelMessagePayload payload);
466 /****f* silccore/SilcChannelAPI/silc_channel_key_payload_parse
470 * SilcChannelKeyPayload
471 * silc_channel_key_payload_parse(const unsigned char *payload,
472 * uin32 payload_len);
476 * Parses channel key payload returning new channel key payload
480 SilcChannelKeyPayload
481 silc_channel_key_payload_parse(const unsigned char *payload,
482 SilcUInt32 payload_len);
484 /****f* silccore/SilcChannelAPI/silc_channel_key_payload_encode
488 * SilcBuffer silc_channel_key_payload_encode(SilcUInt16 id_len,
489 * const unsigned char *id,
490 * SilcUInt16 cipher_len,
491 * const unsigned char *cipher,
492 * SilcUInt16 key_len,
493 * const unsigned char *key);
497 * Encodes channel key payload into a buffer and returns it. This is used
498 * to add channel key payload into a packet.
501 SilcBuffer silc_channel_key_payload_encode(SilcUInt16 id_len,
502 const unsigned char *id,
503 SilcUInt16 cipher_len,
504 const unsigned char *cipher,
506 const unsigned char *key);
508 /****f* silccore/SilcChannelAPI/silc_channel_key_payload_free
512 * void silc_channel_key_payload_free(SilcChannelKeyPayload payload);
516 * Frees the Channel Key Payload and all data in it.
519 void silc_channel_key_payload_free(SilcChannelKeyPayload payload);
521 /****f* silccore/SilcChannelAPI/silc_channel_key_get_id
525 * unsigned char *silc_channel_key_get_id(SilcChannelKeyPayload payload,
526 * SilcUInt32 *id_len);
530 * Return the Channel ID data from the payload. The caller must not
534 unsigned char *silc_channel_key_get_id(SilcChannelKeyPayload payload,
537 /****f* silccore/SilcChannelAPI/silc_channel_key_get_cipher
541 * unsigned char *silc_channel_key_get_cipher(SilcChannelKeyPayload payload,
542 * SilcUInt32 *cipher_len);
546 * Return the name of the cipher from the payload. The caller must not
550 unsigned char *silc_channel_key_get_cipher(SilcChannelKeyPayload payload,
551 SilcUInt32 *cipher_len);
553 /****f* silccore/SilcChannelAPI/silc_channel_key_get_key
557 * unsigned char *silc_channel_key_get_key(SilcChannelKeyPayload payload,
558 * SilcUInt32 *key_len);
562 * Return the raw key material from the payload. The caller must not
566 unsigned char *silc_channel_key_get_key(SilcChannelKeyPayload payload,
567 SilcUInt32 *key_len);