lib/silccore/silcchannel.h

   1 /****h* silccore/silcchannel.h
   2  *
   3  * NAME
   4  *
   5  * silcchannel.h
   6  *
   7  * COPYRIGHT
   8  *
   9  * Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
  10  *
  11  * Copyright (C) 1997 - 2001 Pekka Riikonen
  12  *
  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.
  17  *
  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.
  22  *
  23  * DESCRIPTION
  24  *
  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.
  33  *
  34  ***/
  35
  36 #ifndef SILCCHANNEL_H
  37 #define SILCCHANNEL_H
  38
  39 #include "silcdlist.h"
  40
  41 /****s* silccore/SilcChannelAPI/SilcChannelPayload
  42  *
  43  * NAME
  44  *
  45  *    typedef struct SilcChannelPayloadStruct *SilcChannelPayload;
  46  *
  47  * DESCRIPTION
  48  *
  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.
  53  *
  54  ***/
  55 typedef struct SilcChannelPayloadStruct *SilcChannelPayload;
  56
  57 /****s* silccore/SilcChannelAPI/SilcChannelMessagePayload
  58  *
  59  * NAME
  60  *
  61  *    typedef struct
  62  *    SilcChannelMessagePayloadStruct *SilcChannelMessagePayload;
  63  *
  64  * DESCRIPTION
  65  *
  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.
  70  *
  71  ***/
  72 typedef struct SilcChannelMessagePayloadStruct *SilcChannelMessagePayload;
  73
  74 /****s* silccore/SilcChannelAPI/SilcChannelKeyPayload
  75  *
  76  * NAME
  77  *
  78  *    typedef struct SilcChannelKeyPayloadStruct *SilcChannelKeyPayload;
  79  *
  80  * DESCRIPTION
  81  *
  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.
  86  *
  87  ***/
  88 typedef struct SilcChannelKeyPayloadStruct *SilcChannelKeyPayload;
  89
  90 /****d* silccore/SilcChannelAPI/SilcMessageFlags
  91  *
  92  * NAME
  93  *
  94  *    typedef uint16 SilcMessageFlags;
  95  *
  96  * DESCRIPTION
  97  *
  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.
 101  *
 102  * SOURCE
 103  */
 104 typedef uint16 SilcMessageFlags;
 105
 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_SIGNED      0x0020
 114 #define SILC_MESSAGE_FLAG_RESERVED    0x0040 /* to 0x0200 */
 115 #define SILC_MESSAGE_FLAG_PRIVATE     0x0400 /* to 0x8000 */
 116 /***/
 117
 118 /* Prototypes */
 119
 120 /****f* silccore/SilcChannelAPI/silc_channel_payload_parse
 121  *
 122  * SYNOPSIS
 123  *
 124  *    SilcChannelPayload silc_channel_payload_parse(SilcBuffer buffer);
 125  *
 126  * DESCRIPTION
 127  *
 128  *    Parses channel payload returning new channel payload structure. The
 129  *    `buffer' is the raw payload buffer.
 130  *
 131  ***/
 132 SilcChannelPayload silc_channel_payload_parse(SilcBuffer buffer);
 133
 134 /****f* silccore/SilcChannelAPI/silc_channel_payload_parse_list
 135  *
 136  * SYNOPSIS
 137  *
 138  *    SilcDList silc_channel_payload_parse_list(SilcBuffer buffer);
 139  *
 140  * DESCRIPTION
 141  *
 142  *    Parses list of channel payloads returning list of payloads. This
 143  *    is equivalent to the silc_channel_payload_parse except that the `buffer'
 144  *    now includes multiple Channel Payloads one after the other.
 145  *
 146  ***/
 147 SilcDList silc_channel_payload_parse_list(SilcBuffer buffer);
 148
 149 /****f* silccore/SilcChannelAPI/silc_channel_payload_encode
 150  *
 151  * SYNOPSIS
 152  *
 153  *    SilcBuffer silc_channel_payload_encode(unsigned char *channel_name,
 154  *                                           uint16 channel_name_len,
 155  *                                           unsigned char *channel_id,
 156  *                                           uint32 channel_id_len,
 157  *                                           uint32 mode);
 158  *
 159  * DESCRIPTION
 160  *
 161  *    Encode new channel payload and returns it as buffer.
 162  *
 163  ***/
 164 SilcBuffer silc_channel_payload_encode(unsigned char *channel_name,
 165                                        uint16 channel_name_len,
 166                                        unsigned char *channel_id,
 167                                        uint32 channel_id_len,
 168                                        uint32 mode);
 169
 170 /****f* silccore/SilcChannelAPI/silc_channel_payload_free
 171  *
 172  * SYNOPSIS
 173  *
 174  *    void silc_channel_payload_free(SilcChannelPayload payload);
 175  *
 176  * DESCRIPTION
 177  *
 178  *    Frees Channel Payload and all data in it.
 179  *
 180  ***/
 181 void silc_channel_payload_free(SilcChannelPayload payload);
 182
 183 /****f* silccore/SilcChannelAPI/silc_channel_payload_list_free
 184  *
 185  * SYNOPSIS
 186  *
 187  *    void silc_channel_payload_list_free(SilcDList list);
 188  *
 189  * DESCRIPTION
 190  *
 191  *    Frees list of Channel Payloads and all data in them.
 192  *
 193  ***/
 194 void silc_channel_payload_list_free(SilcDList list);
 195
 196 /****f* silccore/SilcChannelAPI/silc_channel_get_name
 197  *
 198  * SYNOPSIS
 199  *
 200  *    unsigned char *silc_channel_get_name(SilcChannelPayload payload,
 201  *                                         uint32 *channel_name_len);
 202  *
 203  * DESCRIPTION
 204  *
 205  *    Return the channel name from the payload. The caller must not free it.
 206  *
 207  ***/
 208 unsigned char *silc_channel_get_name(SilcChannelPayload payload,
 209                                      uint32 *channel_name_len);
 210
 211 /****f* silccore/SilcChannelAPI/silc_channel_get_id
 212  *
 213  * SYNOPSIS
 214  *
 215  *    unsigned char *silc_channel_get_id(SilcChannelPayload payload,
 216  *                                       uint32 *channel_id_len);
 217  *
 218  * DESCRIPTION
 219  *
 220  *    Return the Channel ID data from the payload. The caller must not free it.
 221  *
 222  ***/
 223 unsigned char *silc_channel_get_id(SilcChannelPayload payload,
 224                                    uint32 *channel_id_len);
 225
 226 /****f* silccore/SilcChannelAPI/silc_channel_get_id_parse
 227  *
 228  * SYNOPSIS
 229  *
 230  *    SilcChannelID *silc_channel_get_id_parse(SilcChannelPayload payload);
 231  *
 232  * DESCRIPTION
 233  *
 234  *    Return the Channel ID as parsed ID. This is equivalent to the
 235  *    silc_channel_get_id execpt that the ID is already parsed. The caller
 236  *    must free the parsed Channel ID.
 237  *
 238  ***/
 239 SilcChannelID *silc_channel_get_id_parse(SilcChannelPayload payload);
 240
 241 /****f* silccore/SilcChannelAPI/silc_channel_get_mode
 242  *
 243  * SYNOPSIS
 244  *
 245  *    uint32 silc_channel_get_mode(SilcChannelPayload payload);
 246  *
 247  * DESCRIPTION
 248  *
 249  *    Return the mode. The mode is arbitrary. It can be the mode of the
 250  *    channel or perhaps the mode of the client on the channel.  The protocol
 251  *    dictates what the usage of the mode is in different circumstances.
 252  *
 253  ***/
 254 uint32 silc_channel_get_mode(SilcChannelPayload payload);
 255
 256 /****f* silccore/SilcChannelAPI/silc_channel_message_payload_decrypt
 257  *
 258  * SYNOPSIS
 259  *
 260  *    int silc_channel_message_payload_decrypt(unsigned char *data,
 261  *                                             size_t data_len,
 262  *                                             SilcCipher cipher,
 263  *                                             SilcHmac hmac);
 264  *
 265  * DESCRIPTION
 266  *
 267  *    Decrypt the channel message. First push the IV out of the packet `data'.
 268  *    The IV is used in the decryption process. Then decrypt the message.
 269  *    After decryption, take the MAC from the decrypted packet, compute MAC
 270  *    and compare the MACs.  If they match, the decryption was successful
 271  *    and we have the channel message ready to be displayed.
 272  *
 273  *    This is usually used by the Channel Message interface itself but can
 274  *    be called by the appliation if separate decryption process is required.
 275  *    For example server might need to call this directly in some
 276  *    circumstances. The `cipher' is used to decrypt the payload.
 277  *
 278  *    If the `hmac' is no provided then the MAC of the channel message is
 279  *    not verified.
 280  *
 281  ***/
 282 int silc_channel_message_payload_decrypt(unsigned char *data,
 283                                          size_t data_len,
 284                                          SilcCipher cipher,
 285                                          SilcHmac hmac);
 286
 287 /****f* silccore/SilcChannelAPI/silc_channel_message_payload_parse
 288  *
 289  * SYNOPSIS
 290  *
 291  *    SilcChannelMessagePayload
 292  *    silc_channel_message_payload_parse(SilcBuffer buffer,
 293  *                                       SilcCipher cipher,
 294  *                                       SilcHmac hmac);
 295  *
 296  * DESCRIPTION
 297  *
 298  *    Parses channel message payload returning new channel payload structure.
 299  *    This also decrypts it and checks the MAC. The `cipher's is used to
 300  *    decrypt the payload.
 301  *
 302  *    If the `hmac' is no provided then the MAC of the channel message is
 303  *    not verified.
 304  *
 305  ***/
 306 SilcChannelMessagePayload
 307 silc_channel_message_payload_parse(SilcBuffer buffer,
 308                                    SilcCipher cipher,
 309                                    SilcHmac hmac);
 310
 311 /****f* silccore/SilcChannelAPI/silc_channel_message_payload_encode
 312  *
 313  * SYNOPSIS
 314  *
 315  *    SilcBuffer silc_channel_message_payload_encode(uint16 flags,
 316  *                                                   uint16 data_len,
 317  *                                                   unsigned char *data,
 318  *                                                   uint16 iv_len,
 319  *                                                   unsigned char *iv,
 320  *                                                   SilcCipher cipher,
 321  *                                                   SilcHmac hmac);
 322  *
 323  * DESCRIPTION
 324  *
 325  *    Encodes channel message payload into a buffer and returns it. This
 326  *    is used to add channel message payload into a packet. As the channel
 327  *    payload is encrypted separately from other parts of the packet padding
 328  *    must be applied to the payload. The function generates the padding
 329  *    automatically from random data.  The `cipher' is the cipher used
 330  *    encrypt the payload and `hmac' is used to compute the MAC for the
 331  *    payload.
 332  *
 333  ***/
 334 SilcBuffer silc_channel_message_payload_encode(uint16 flags,
 335                                                uint16 data_len,
 336                                                unsigned char *data,
 337                                                uint16 iv_len,
 338                                                unsigned char *iv,
 339                                                SilcCipher cipher,
 340                                                SilcHmac hmac);
 341
 342 /****f* silccore/SilcChannelAPI/silc_channel_message_payload_free
 343  *
 344  * SYNOPSIS
 345  *
 346  *    void
 347  *    silc_channel_message_payload_free(SilcChannelMessagePayload payload);
 348  *
 349  * DESCRIPTION
 350  *
 351  *    Free's Channel Message Payload and all data in it.
 352  *
 353  ***/
 354 void silc_channel_message_payload_free(SilcChannelMessagePayload payload);
 355
 356 /****f* silccore/SilcChannelAPI/silc_channel_message_get_flags
 357  *
 358  * SYNOPSIS
 359  *
 360  *    SilcMessageFlags
 361  *    silc_channel_message_get_flags(SilcChannelMessagePayload payload);
 362  *
 363  * DESCRIPTION
 364  *
 365  *    Returns the message flags from the payload.
 366  *
 367  ***/
 368 SilcMessageFlags
 369 silc_channel_message_get_flags(SilcChannelMessagePayload payload);
 370
 371 /****f* silccore/SilcChannelAPI/silc_channel_message_get_data
 372  *
 373  * SYNOPSIS
 374  *
 375  *    unsigned char *
 376  *    silc_channel_message_get_data(SilcChannelMessagePayload payload,
 377  *                                  uint32 *data_len);
 378  *
 379  * DESCRIPTION
 380  *
 381  *    Return the data in the payload, that is, the actual channel message.
 382  *    The caller must not free it.
 383  *
 384  ***/
 385 unsigned char *silc_channel_message_get_data(SilcChannelMessagePayload payload,
 386                                      uint32 *data_len);
 387
 388 /****f* silccore/SilcChannelAPI/silc_channel_message_get_mac
 389  *
 390  * SYNOPSIS
 391  *
 392  *    unsigned char *
 393  *    silc_channel_message_get_mac(SilcChannelMessagePayload payload);
 394  *
 395  * DESCRIPTION
 396  *
 397  *    Return the MAC of the payload. The caller must already know the
 398  *    length of the MAC. The caller must not free the MAC.
 399  *
 400  ***/
 401 unsigned char *silc_channel_message_get_mac(SilcChannelMessagePayload payload);
 402
 403 /****f* silccore/SilcChannelAPI/silc_channel_message_get_iv
 404  *
 405  * SYNOPSIS
 406  *
 407  *    unsigned char *
 408  *    silc_channel_message_get_iv(SilcChannelMessagePayload payload);
 409  *
 410  * DESCRIPTION
 411  *
 412  *    Return the IV of the payload. The caller must already know the
 413  *    length of the IV. The caller must not free the IV.
 414  *
 415  ***/
 416 unsigned char *silc_channel_message_get_iv(SilcChannelMessagePayload payload);
 417
 418 /****f* silccore/SilcChannelAPI/silc_channel_key_payload_parse
 419  *
 420  * SYNOPSIS
 421  *
 422  *    SilcChannelKeyPayload silc_channel_key_payload_parse(SilcBuffer buffer);
 423  *
 424  * DESCRIPTION
 425  *
 426  *     Parses channel key payload returning new channel key payload
 427  *     structure.
 428  *
 429  ***/
 430 SilcChannelKeyPayload silc_channel_key_payload_parse(SilcBuffer buffer);
 431
 432 /****f* silccore/SilcChannelAPI/silc_channel_key_payload_encode
 433  *
 434  * SYNOPSIS
 435  *
 436  *    SilcBuffer silc_channel_key_payload_encode(uint16 id_len,
 437  *                                               unsigned char *id,
 438  *                                               uint16 cipher_len,
 439  *                                               unsigned char *cipher,
 440  *                                               uint16 key_len,
 441  *                                               unsigned char *key);
 442  *
 443  * DESCRIPTION
 444  *
 445  *    Encodes channel key payload into a buffer and returns it. This is used
 446  *    to add channel key payload into a packet.
 447  *
 448  ***/
 449 SilcBuffer silc_channel_key_payload_encode(uint16 id_len,
 450                                            unsigned char *id,
 451                                            uint16 cipher_len,
 452                                            unsigned char *cipher,
 453                                            uint16 key_len,
 454                                            unsigned char *key);
 455
 456 /****f* silccore/SilcChannelAPI/silc_channel_key_payload_free
 457  *
 458  * SYNOPSIS
 459  *
 460  *    void silc_channel_key_payload_free(SilcChannelKeyPayload payload);
 461  *
 462  * DESCRIPTION
 463  *
 464  *    Frees the Channel Key Payload and all data in it.
 465  *
 466  ***/
 467 void silc_channel_key_payload_free(SilcChannelKeyPayload payload);
 468
 469 /****f* silccore/SilcChannelAPI/silc_channel_key_get_id
 470  *
 471  * SYNOPSIS
 472  *
 473  *    unsigned char *silc_channel_key_get_id(SilcChannelKeyPayload payload,
 474  *                                           uint32 *id_len);
 475  *
 476  * DESCRIPTION
 477  *
 478  *    Return the Channel ID data from the payload. The caller must not
 479  *    free it.
 480  *
 481  ***/
 482 unsigned char *silc_channel_key_get_id(SilcChannelKeyPayload payload,
 483                                        uint32 *id_len);
 484
 485 /****f* silccore/SilcChannelAPI/silc_channel_key_get_cipher
 486  *
 487  * SYNOPSIS
 488  *
 489  *    unsigned char *silc_channel_key_get_cipher(SilcChannelKeyPayload payload,
 490  *                                               uint32 *cipher_len);
 491  *
 492  * DESCRIPTION
 493  *
 494  *    Return the name of the cipher from the payload. The caller must not
 495  *    free it.
 496  *
 497  ***/
 498 unsigned char *silc_channel_key_get_cipher(SilcChannelKeyPayload payload,
 499                                            uint32 *cipher_len);
 500
 501 /****f* silccore/SilcChannelAPI/silc_channel_key_get_key
 502  *
 503  * SYNOPSIS
 504  *
 505  *    unsigned char *silc_channel_key_get_key(SilcChannelKeyPayload payload,
 506  *                                            uint32 *key_len);
 507  *
 508  * DESCRIPTION
 509  *
 510  *    Return the raw key material from the payload. The caller must not
 511  *    free it.
 512  *
 513  ***/
 514 unsigned char *silc_channel_key_get_key(SilcChannelKeyPayload payload,
 515                                         uint32 *key_len);
 516
 517 #endif