1 /****h* silccore/silcchannel.h
9 * Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
11 * Copyright (C) 1997 - 2001 Pekka Riikonen
13 * This program is free software; you can redistribute it and/or modify
14 * it under the terms of the GNU General Public License as published by
15 * the Free Software Foundation; either version 2 of the License, or
16 * (at your option) any later version.
18 * This program is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 * GNU General Public License for more details.
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 uint16 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 uint16 SilcMessageFlags;
106 /* The message flags (shared by both channel and private messages) */
107 #define SILC_MESSAGE_FLAG_NONE 0x0000
108 #define SILC_MESSAGE_FLAG_AUTOREPLY 0x0001
109 #define SILC_MESSAGE_FLAG_NOREPLY 0x0002
110 #define SILC_MESSAGE_FLAG_ACTION 0x0004
111 #define SILC_MESSAGE_FLAG_NOTICE 0x0008
112 #define SILC_MESSAGE_FLAG_REQUEST 0x0010
113 #define SILC_MESSAGE_FLAG_RESERVED 0x0020 /* to 0x0200 */
114 #define SILC_MESSAGE_FLAG_PRIVATE 0x0400 /* to 0x8000 */
119 /****f* silccore/SilcChannelAPI/silc_channel_payload_parse
123 * SilcChannelPayload silc_channel_payload_parse(SilcBuffer buffer);
127 * Parses channel payload returning new channel payload structure. The
128 * `buffer' is the raw payload buffer.
131 SilcChannelPayload silc_channel_payload_parse(SilcBuffer buffer);
133 /****f* silccore/SilcChannelAPI/silc_channel_payload_parse_list
137 * SilcDList silc_channel_payload_parse_list(SilcBuffer buffer);
141 * Parses list of channel payloads returning list of payloads. This
142 * is equivalent to the silc_channel_payload_parse except that the `buffer'
143 * now includes multiple Channel Payloads one after the other.
146 SilcDList silc_channel_payload_parse_list(SilcBuffer buffer);
148 /****f* silccore/SilcChannelAPI/silc_channel_payload_encode
152 * SilcBuffer silc_channel_payload_encode(unsigned char *channel_name,
153 * uint16 channel_name_len,
154 * unsigned char *channel_id,
155 * uint32 channel_id_len,
160 * Encode new channel payload and returns it as buffer.
163 SilcBuffer silc_channel_payload_encode(unsigned char *channel_name,
164 uint16 channel_name_len,
165 unsigned char *channel_id,
166 uint32 channel_id_len,
169 /****f* silccore/SilcChannelAPI/silc_channel_payload_free
173 * void silc_channel_payload_free(SilcChannelPayload payload);
177 * Frees Channel Payload and all data in it.
180 void silc_channel_payload_free(SilcChannelPayload payload);
182 /****f* silccore/SilcChannelAPI/silc_channel_payload_list_free
186 * void silc_channel_payload_list_free(SilcDList list);
190 * Frees list of Channel Payloads and all data in them.
193 void silc_channel_payload_list_free(SilcDList list);
195 /****f* silccore/SilcChannelAPI/silc_channel_get_name
199 * unsigned char *silc_channel_get_name(SilcChannelPayload payload,
200 * uint32 *channel_name_len);
204 * Return the channel name from the payload. The caller must not free it.
207 unsigned char *silc_channel_get_name(SilcChannelPayload payload,
208 uint32 *channel_name_len);
210 /****f* silccore/SilcChannelAPI/silc_channel_get_id
214 * unsigned char *silc_channel_get_id(SilcChannelPayload payload,
215 * uint32 *channel_id_len);
219 * Return the Channel ID data from the payload. The caller must not free it.
222 unsigned char *silc_channel_get_id(SilcChannelPayload payload,
223 uint32 *channel_id_len);
225 /****f* silccore/SilcChannelAPI/silc_channel_get_id_parse
229 * SilcChannelID *silc_channel_get_id_parse(SilcChannelPayload payload);
233 * Return the Channel ID as parsed ID. This is equivalent to the
234 * silc_channel_get_id execpt that the ID is already parsed. The caller
235 * must free the parsed Channel ID.
238 SilcChannelID *silc_channel_get_id_parse(SilcChannelPayload payload);
240 /****f* silccore/SilcChannelAPI/silc_channel_get_mode
244 * uint32 silc_channel_get_mode(SilcChannelPayload payload);
248 * Return the mode. The mode is arbitrary. It can be the mode of the
249 * channel or perhaps the mode of the client on the channel. The protocol
250 * dictates what the usage of the mode is in different circumstances.
253 uint32 silc_channel_get_mode(SilcChannelPayload payload);
255 /****f* silccore/SilcChannelAPI/silc_channel_message_payload_decrypt
259 * int silc_channel_message_payload_decrypt(unsigned char *data,
266 * Decrypt the channel message. First push the IV out of the packet `data'.
267 * The IV is used in the decryption process. Then decrypt the message.
268 * After decryption, take the MAC from the decrypted packet, compute MAC
269 * and compare the MACs. If they match, the decryption was successful
270 * and we have the channel message ready to be displayed.
272 * This is usually used by the Channel Message interface itself but can
273 * be called by the appliation if separate decryption process is required.
274 * For example server might need to call this directly in some
275 * circumstances. The `cipher' is used to decrypt the payload.
277 * If the `hmac' is no provided then the MAC of the channel message is
281 int silc_channel_message_payload_decrypt(unsigned char *data,
286 /****f* silccore/SilcChannelAPI/silc_channel_message_payload_parse
290 * SilcChannelMessagePayload
291 * silc_channel_message_payload_parse(SilcBuffer buffer,
297 * Parses channel message payload returning new channel payload structure.
298 * This also decrypts it and checks the MAC. The `cipher's is used to
299 * decrypt the payload.
301 * If the `hmac' is no provided then the MAC of the channel message is
305 SilcChannelMessagePayload
306 silc_channel_message_payload_parse(SilcBuffer buffer,
310 /****f* silccore/SilcChannelAPI/silc_channel_message_payload_encode
314 * SilcBuffer silc_channel_message_payload_encode(uint16 flags,
316 * unsigned char *data,
324 * Encodes channel message payload into a buffer and returns it. This
325 * is used to add channel message payload into a packet. As the channel
326 * payload is encrypted separately from other parts of the packet padding
327 * must be applied to the payload. The function generates the padding
328 * automatically from random data. The `cipher' is the cipher used
329 * encrypt the payload and `hmac' is used to compute the MAC for the
333 SilcBuffer silc_channel_message_payload_encode(uint16 flags,
341 /****f* silccore/SilcChannelAPI/silc_channel_message_payload_free
346 * silc_channel_message_payload_free(SilcChannelMessagePayload payload);
350 * Free's Channel Message Payload and all data in it.
353 void silc_channel_message_payload_free(SilcChannelMessagePayload payload);
355 /****f* silccore/SilcChannelAPI/silc_channel_message_get_flags
360 * silc_channel_message_get_flags(SilcChannelMessagePayload payload);
364 * Returns the message flags from the payload.
368 silc_channel_message_get_flags(SilcChannelMessagePayload payload);
370 /****f* silccore/SilcChannelAPI/silc_channel_message_get_data
375 * silc_channel_message_get_data(SilcChannelMessagePayload payload,
380 * Return the data in the payload, that is, the actual channel message.
381 * The caller must not free it.
384 unsigned char *silc_channel_message_get_data(SilcChannelMessagePayload payload,
387 /****f* silccore/SilcChannelAPI/silc_channel_message_get_mac
392 * silc_channel_message_get_mac(SilcChannelMessagePayload payload);
396 * Return the MAC of the payload. The caller must already know the
397 * length of the MAC. The caller must not free the MAC.
400 unsigned char *silc_channel_message_get_mac(SilcChannelMessagePayload payload);
402 /****f* silccore/SilcChannelAPI/silc_channel_message_get_iv
407 * silc_channel_message_get_iv(SilcChannelMessagePayload payload);
411 * Return the IV of the payload. The caller must already know the
412 * length of the IV. The caller must not free the IV.
415 unsigned char *silc_channel_message_get_iv(SilcChannelMessagePayload payload);
417 /****f* silccore/SilcChannelAPI/silc_channel_key_payload_parse
421 * SilcChannelKeyPayload silc_channel_key_payload_parse(SilcBuffer buffer);
425 * Parses channel key payload returning new channel key payload
429 SilcChannelKeyPayload silc_channel_key_payload_parse(SilcBuffer buffer);
431 /****f* silccore/SilcChannelAPI/silc_channel_key_payload_encode
435 * SilcBuffer silc_channel_key_payload_encode(uint16 id_len,
438 * unsigned char *cipher,
440 * unsigned char *key);
444 * Encodes channel key payload into a buffer and returns it. This is used
445 * to add channel key payload into a packet.
448 SilcBuffer silc_channel_key_payload_encode(uint16 id_len,
451 unsigned char *cipher,
455 /****f* silccore/SilcChannelAPI/silc_channel_key_payload_free
459 * void silc_channel_key_payload_free(SilcChannelKeyPayload payload);
463 * Frees the Channel Key Payload and all data in it.
466 void silc_channel_key_payload_free(SilcChannelKeyPayload payload);
468 /****f* silccore/SilcChannelAPI/silc_channel_key_get_id
472 * unsigned char *silc_channel_key_get_id(SilcChannelKeyPayload payload,
477 * Return the Channel ID data from the payload. The caller must not
481 unsigned char *silc_channel_key_get_id(SilcChannelKeyPayload payload,
484 /****f* silccore/SilcChannelAPI/silc_channel_key_get_cipher
488 * unsigned char *silc_channel_key_get_cipher(SilcChannelKeyPayload payload,
489 * uint32 *cipher_len);
493 * Return the name of the cipher from the payload. The caller must not
497 unsigned char *silc_channel_key_get_cipher(SilcChannelKeyPayload payload,
500 /****f* silccore/SilcChannelAPI/silc_channel_key_get_key
504 * unsigned char *silc_channel_key_get_key(SilcChannelKeyPayload payload,
509 * Return the raw key material from the payload. The caller must not
513 unsigned char *silc_channel_key_get_key(SilcChannelKeyPayload payload,