-/*
-
- silcchannel.h
-
- Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
-
- Copyright (C) 1997 - 2001 Pekka Riikonen
-
- This program is free software; you can redistribute it and/or modify
- it under the terms of the GNU General Public License as published by
- the Free Software Foundation; either version 2 of the License, or
- (at your option) any later version.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
-
-*/
+/****h* silccore/silcchannel.h
+ *
+ * NAME
+ *
+ * silcchannel.h
+ *
+ * COPYRIGHT
+ *
+ * Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
+ *
+ * Copyright (C) 1997 - 2001 Pekka Riikonen
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * DESCRIPTION
+ *
+ * Implementations of the Channel Payload, Channel Message Payload and
+ * Channel Key Payload. The Channel Payload represents new channel and
+ * is used to distribute the information of the new channel. The Channel
+ * Message Payload is used to deliver messages to the channel. The routines
+ * for Channel Message Payload also handles the encryption and decryption
+ * of the payload. Last, the Channel Key Payload is used to distribute
+ * a new key to the channel. It is done for example every time someone
+ * joins a channel or the old key expires.
+ *
+ ***/
#ifndef SILCCHANNEL_H
#define SILCCHANNEL_H
#include "silcdlist.h"
-/* Forward declaration for Channel Payload parsed from packet. The
- actual structure is defined in source file and is private data. */
+/****s* silccore/SilcChannelAPI/SilcChannelPayload
+ *
+ * NAME
+ *
+ * typedef struct SilcChannelPayloadStruct *SilcChannelPayload;
+ *
+ * DESCRIPTION
+ *
+ * This context is the actual Channel Payload and is allocated
+ * by silc_channel_payload_parse and given as argument usually to
+ * all silc_channel_payload_* functions. It is freed by the
+ * silc_channel_payload_free function.
+ *
+ ***/
typedef struct SilcChannelPayloadStruct *SilcChannelPayload;
-/* Forward declaration for Channel Message Payload parsed from packet. The
- actual structure is defined in source file and is private data. */
+/****s* silccore/SilcChannelAPI/SilcChannelMessagePayload
+ *
+ * NAME
+ *
+ * typedef struct
+ * SilcChannelMessagePayloadStruct *SilcChannelMessagePayload;
+ *
+ * DESCRIPTION
+ *
+ * This context is the actual Channel Message Payload and is allocated
+ * by silc_channel_message_payload_parse and given as argument usually to
+ * all silc_channel_message_payload_* functions. It is freed by the
+ * silc_channel_message_payload_free function.
+ *
+ ***/
typedef struct SilcChannelMessagePayloadStruct *SilcChannelMessagePayload;
-/* Forward declaration for Channel Key Payload parsed from packet. The
- actual structure is defined in source file and is private data. */
+/****s* silccore/SilcChannelAPI/SilcChannelKeyPayload
+ *
+ * NAME
+ *
+ * typedef struct SilcChannelKeyPayloadStruct *SilcChannelKeyPayload;
+ *
+ * DESCRIPTION
+ *
+ * This context is the actual Channel Key Payload and is allocated
+ * by silc_channel_key_payload_parse and given as argument usually to
+ * all silc_channel_key_payload_* functions. It is freed by the
+ * silc_channel_key_payload_free function.
+ *
+ ***/
typedef struct SilcChannelKeyPayloadStruct *SilcChannelKeyPayload;
-/* The Message flag type */
+/****d* silccore/SilcChannelAPI/SilcMessageFlags
+ *
+ * NAME
+ *
+ * typedef uint16 SilcMessageFlags;
+ *
+ * DESCRIPTION
+ *
+ * The message flags type definition and the message flags. The
+ * message flags are used to indicate some status of the message.
+ * These flags are also used by the private message interfaces.
+ *
+ * SOURCE
+ */
typedef uint16 SilcMessageFlags;
/* The message flags (shared by both channel and private messages) */
#define SILC_MESSAGE_FLAG_REQUEST 0x0010
#define SILC_MESSAGE_FLAG_RESERVED 0x0020 /* to 0x0200 */
#define SILC_MESSAGE_FLAG_PRIVATE 0x0400 /* to 0x8000 */
+/***/
/* Prototypes */
+
+/****f* silccore/SilcChannelAPI/silc_channel_payload_parse
+ *
+ * SYNOPSIS
+ *
+ * SilcChannelPayload silc_channel_payload_parse(SilcBuffer buffer);
+ *
+ * DESCRIPTION
+ *
+ * Parses channel payload returning new channel payload structure. The
+ * `buffer' is the raw payload buffer.
+ *
+ ***/
SilcChannelPayload silc_channel_payload_parse(SilcBuffer buffer);
+
+/****f* silccore/SilcChannelAPI/silc_channel_payload_parse_list
+ *
+ * SYNOPSIS
+ *
+ * SilcDList silc_channel_payload_parse_list(SilcBuffer buffer);
+ *
+ * DESCRIPTION
+ *
+ * Parses list of channel payloads returning list of payloads. This
+ * is equivalent to the silc_channel_payload_parse except that the `buffer'
+ * now includes multiple Channel Payloads one after the other.
+ *
+ ***/
SilcDList silc_channel_payload_parse_list(SilcBuffer buffer);
+
+/****f* silccore/SilcChannelAPI/silc_channel_payload_encode
+ *
+ * SYNOPSIS
+ *
+ * SilcBuffer silc_channel_payload_encode(unsigned char *channel_name,
+ * uint16 channel_name_len,
+ * unsigned char *channel_id,
+ * uint32 channel_id_len,
+ * uint32 mode);
+ *
+ * DESCRIPTION
+ *
+ * Encode new channel payload and returns it as buffer.
+ *
+ ***/
SilcBuffer silc_channel_payload_encode(unsigned char *channel_name,
uint16 channel_name_len,
unsigned char *channel_id,
uint32 channel_id_len,
uint32 mode);
+
+/****f* silccore/SilcChannelAPI/silc_channel_payload_free
+ *
+ * SYNOPSIS
+ *
+ * void silc_channel_payload_free(SilcChannelPayload payload);
+ *
+ * DESCRIPTION
+ *
+ * Frees Channel Payload and all data in it.
+ *
+ ***/
void silc_channel_payload_free(SilcChannelPayload payload);
+
+/****f* silccore/SilcChannelAPI/silc_channel_payload_list_free
+ *
+ * SYNOPSIS
+ *
+ * void silc_channel_payload_list_free(SilcDList list);
+ *
+ * DESCRIPTION
+ *
+ * Frees list of Channel Payloads and all data in them.
+ *
+ ***/
void silc_channel_payload_list_free(SilcDList list);
+
+/****f* silccore/SilcChannelAPI/silc_channel_get_name
+ *
+ * SYNOPSIS
+ *
+ * unsigned char *silc_channel_get_name(SilcChannelPayload payload,
+ * uint32 *channel_name_len);
+ *
+ * DESCRIPTION
+ *
+ * Return the channel name from the payload. The caller must not free it.
+ *
+ ***/
unsigned char *silc_channel_get_name(SilcChannelPayload payload,
uint32 *channel_name_len);
+
+/****f* silccore/SilcChannelAPI/silc_channel_get_id
+ *
+ * SYNOPSIS
+ *
+ * unsigned char *silc_channel_get_id(SilcChannelPayload payload,
+ * uint32 *channel_id_len);
+ *
+ * DESCRIPTION
+ *
+ * Return the Channel ID data from the payload. The caller must not free it.
+ *
+ ***/
unsigned char *silc_channel_get_id(SilcChannelPayload payload,
uint32 *channel_id_len);
+
+/****f* silccore/SilcChannelAPI/silc_channel_get_id_parse
+ *
+ * SYNOPSIS
+ *
+ * SilcChannelID *silc_channel_get_id_parse(SilcChannelPayload payload);
+ *
+ * DESCRIPTION
+ *
+ * Return the Channel ID as parsed ID. This is equivalent to the
+ * silc_channel_get_id execpt that the ID is already parsed. The caller
+ * must free the parsed Channel ID.
+ *
+ ***/
SilcChannelID *silc_channel_get_id_parse(SilcChannelPayload payload);
+
+/****f* silccore/SilcChannelAPI/silc_channel_get_mode
+ *
+ * SYNOPSIS
+ *
+ * uint32 silc_channel_get_mode(SilcChannelPayload payload);
+ *
+ * DESCRIPTION
+ *
+ * Return the mode. The mode is arbitrary. It can be the mode of the
+ * channel or perhaps the mode of the client on the channel. The protocol
+ * dictates what the usage of the mode is in different circumstances.
+ *
+ ***/
uint32 silc_channel_get_mode(SilcChannelPayload payload);
+
+/****f* silccore/SilcChannelAPI/silc_channel_message_payload_decrypt
+ *
+ * SYNOPSIS
+ *
+ * int silc_channel_message_payload_decrypt(unsigned char *data,
+ * size_t data_len,
+ * SilcCipher cipher,
+ * SilcHmac hmac);
+ *
+ * DESCRIPTION
+ *
+ * Decrypt the channel message. First push the IV out of the packet `data'.
+ * The IV is used in the decryption process. Then decrypt the message.
+ * After decryption, take the MAC from the decrypted packet, compute MAC
+ * and compare the MACs. If they match, the decryption was successful
+ * and we have the channel message ready to be displayed.
+ *
+ * This is usually used by the Channel Message interface itself but can
+ * be called by the appliation if separate decryption process is required.
+ * For example server might need to call this directly in some
+ * circumstances. The `cipher' is used to decrypt the payload.
+ *
+ * If the `hmac' is no provided then the MAC of the channel message is
+ * not verified.
+ *
+ ***/
int silc_channel_message_payload_decrypt(unsigned char *data,
size_t data_len,
SilcCipher cipher,
SilcHmac hmac);
+
+/****f* silccore/SilcChannelAPI/silc_channel_message_payload_parse
+ *
+ * SYNOPSIS
+ *
+ * SilcChannelMessagePayload
+ * silc_channel_message_payload_parse(SilcBuffer buffer,
+ * SilcCipher cipher,
+ * SilcHmac hmac);
+ *
+ * DESCRIPTION
+ *
+ * Parses channel message payload returning new channel payload structure.
+ * This also decrypts it and checks the MAC. The `cipher's is used to
+ * decrypt the payload.
+ *
+ * If the `hmac' is no provided then the MAC of the channel message is
+ * not verified.
+ *
+ ***/
SilcChannelMessagePayload
silc_channel_message_payload_parse(SilcBuffer buffer,
SilcCipher cipher,
SilcHmac hmac);
+
+/****f* silccore/SilcChannelAPI/silc_channel_message_payload_encode
+ *
+ * SYNOPSIS
+ *
+ * SilcBuffer silc_channel_message_payload_encode(uint16 flags,
+ * uint16 data_len,
+ * unsigned char *data,
+ * uint16 iv_len,
+ * unsigned char *iv,
+ * SilcCipher cipher,
+ * SilcHmac hmac);
+ *
+ * DESCRIPTION
+ *
+ * Encodes channel message payload into a buffer and returns it. This
+ * is used to add channel message payload into a packet. As the channel
+ * payload is encrypted separately from other parts of the packet padding
+ * must be applied to the payload. The function generates the padding
+ * automatically from random data. The `cipher' is the cipher used
+ * encrypt the payload and `hmac' is used to compute the MAC for the
+ * payload.
+ *
+ ***/
SilcBuffer silc_channel_message_payload_encode(uint16 flags,
uint16 data_len,
unsigned char *data,
unsigned char *iv,
SilcCipher cipher,
SilcHmac hmac);
+
+/****f* silccore/SilcChannelAPI/silc_channel_message_payload_free
+ *
+ * SYNOPSIS
+ *
+ * void
+ * silc_channel_message_payload_free(SilcChannelMessagePayload payload);
+ *
+ * DESCRIPTION
+ *
+ * Free's Channel Message Payload and all data in it.
+ *
+ ***/
void silc_channel_message_payload_free(SilcChannelMessagePayload payload);
-uint16
+
+/****f* silccore/SilcChannelAPI/silc_channel_message_get_flags
+ *
+ * SYNOPSIS
+ *
+ * SilcMessageFlags
+ * silc_channel_message_get_flags(SilcChannelMessagePayload payload);
+ *
+ * DESCRIPTION
+ *
+ * Returns the message flags from the payload.
+ *
+ ***/
+SilcMessageFlags
silc_channel_message_get_flags(SilcChannelMessagePayload payload);
+
+/****f* silccore/SilcChannelAPI/silc_channel_message_get_data
+ *
+ * SYNOPSIS
+ *
+ * unsigned char *
+ * silc_channel_message_get_data(SilcChannelMessagePayload payload,
+ * uint32 *data_len);
+ *
+ * DESCRIPTION
+ *
+ * Return the data in the payload, that is, the actual channel message.
+ * The caller must not free it.
+ *
+ ***/
unsigned char *silc_channel_message_get_data(SilcChannelMessagePayload payload,
uint32 *data_len);
+
+/****f* silccore/SilcChannelAPI/silc_channel_message_get_mac
+ *
+ * SYNOPSIS
+ *
+ * unsigned char *
+ * silc_channel_message_get_mac(SilcChannelMessagePayload payload);
+ *
+ * DESCRIPTION
+ *
+ * Return the MAC of the payload. The caller must already know the
+ * length of the MAC. The caller must not free the MAC.
+ *
+ ***/
unsigned char *silc_channel_message_get_mac(SilcChannelMessagePayload payload);
+
+/****f* silccore/SilcChannelAPI/silc_channel_message_get_iv
+ *
+ * SYNOPSIS
+ *
+ * unsigned char *
+ * silc_channel_message_get_iv(SilcChannelMessagePayload payload);
+ *
+ * DESCRIPTION
+ *
+ * Return the IV of the payload. The caller must already know the
+ * length of the IV. The caller must not free the IV.
+ *
+ ***/
unsigned char *silc_channel_message_get_iv(SilcChannelMessagePayload payload);
+
+/****f* silccore/SilcChannelAPI/silc_channel_key_payload_parse
+ *
+ * SYNOPSIS
+ *
+ * SilcChannelKeyPayload silc_channel_key_payload_parse(SilcBuffer buffer);
+ *
+ * DESCRIPTION
+ *
+ * Parses channel key payload returning new channel key payload
+ * structure.
+ *
+ ***/
SilcChannelKeyPayload silc_channel_key_payload_parse(SilcBuffer buffer);
+
+/****f* silccore/SilcChannelAPI/silc_channel_key_payload_encode
+ *
+ * SYNOPSIS
+ *
+ * SilcBuffer silc_channel_key_payload_encode(uint16 id_len,
+ * unsigned char *id,
+ * uint16 cipher_len,
+ * unsigned char *cipher,
+ * uint16 key_len,
+ * unsigned char *key);
+ *
+ * DESCRIPTION
+ *
+ * Encodes channel key payload into a buffer and returns it. This is used
+ * to add channel key payload into a packet.
+ *
+ ***/
SilcBuffer silc_channel_key_payload_encode(uint16 id_len,
unsigned char *id,
uint16 cipher_len,
unsigned char *cipher,
uint16 key_len,
unsigned char *key);
+
+/****f* silccore/SilcChannelAPI/silc_channel_key_payload_free
+ *
+ * SYNOPSIS
+ *
+ * void silc_channel_key_payload_free(SilcChannelKeyPayload payload);
+ *
+ * DESCRIPTION
+ *
+ * Frees the Channel Key Payload and all data in it.
+ *
+ ***/
void silc_channel_key_payload_free(SilcChannelKeyPayload payload);
+
+/****f* silccore/SilcChannelAPI/silc_channel_key_get_id
+ *
+ * SYNOPSIS
+ *
+ * unsigned char *silc_channel_key_get_id(SilcChannelKeyPayload payload,
+ * uint32 *id_len);
+ *
+ * DESCRIPTION
+ *
+ * Return the Channel ID data from the payload. The caller must not
+ * free it.
+ *
+ ***/
unsigned char *silc_channel_key_get_id(SilcChannelKeyPayload payload,
uint32 *id_len);
+
+/****f* silccore/SilcChannelAPI/silc_channel_key_get_cipher
+ *
+ * SYNOPSIS
+ *
+ * unsigned char *silc_channel_key_get_cipher(SilcChannelKeyPayload payload,
+ * uint32 *cipher_len);
+ *
+ * DESCRIPTION
+ *
+ * Return the name of the cipher from the payload. The caller must not
+ * free it.
+ *
+ ***/
unsigned char *silc_channel_key_get_cipher(SilcChannelKeyPayload payload,
uint32 *cipher_len);
+
+/****f* silccore/SilcChannelAPI/silc_channel_key_get_key
+ *
+ * SYNOPSIS
+ *
+ * unsigned char *silc_channel_key_get_key(SilcChannelKeyPayload payload,
+ * uint32 *key_len);
+ *
+ * DESCRIPTION
+ *
+ * Return the raw key material from the payload. The caller must not
+ * free it.
+ *
+ ***/
unsigned char *silc_channel_key_get_key(SilcChannelKeyPayload payload,
uint32 *key_len);
projects / silc.git / blobdiff