lib/silccore/silcchannel.h

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