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      /* 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 */
 119 /***/
 120
 121 /* Prototypes */
 122
 123 /****f* silccore/SilcChannelAPI/silc_channel_payload_parse
 124  *
 125  * SYNOPSIS
 126  *
 127  *    SilcChannelPayload
 128  *    silc_channel_payload_parse(const unsigned char *payload,
 129  *                               SilcUInt32 payload_len);
 130  *
 131  * DESCRIPTION
 132  *
 133  *    Parses channel payload returning new channel payload structure. The
 134  *    `buffer' is the raw payload buffer.
 135  *
 136  ***/
 137 SilcChannelPayload silc_channel_payload_parse(const unsigned char *payload,
 138                                               SilcUInt32 payload_len);
 139
 140 /****f* silccore/SilcChannelAPI/silc_channel_payload_parse_list
 141  *
 142  * SYNOPSIS
 143  *
 144  *    SilcDList
 145  *    silc_channel_payload_parse_list(const unsigned char *payload,
 146  *                                    SilcUInt32 payload_len);
 147  *
 148  * DESCRIPTION
 149  *
 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.
 153  *
 154  ***/
 155 SilcDList silc_channel_payload_parse_list(const unsigned char *payload,
 156                                           SilcUInt32 payload_len);
 157
 158 /****f* silccore/SilcChannelAPI/silc_channel_payload_encode
 159  *
 160  * SYNOPSIS
 161  *
 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,
 166  *                                           SilcUInt32 mode);
 167  *
 168  * DESCRIPTION
 169  *
 170  *    Encode new channel payload and returns it as buffer.
 171  *
 172  ***/
 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,
 177                                        SilcUInt32 mode);
 178
 179 /****f* silccore/SilcChannelAPI/silc_channel_payload_free
 180  *
 181  * SYNOPSIS
 182  *
 183  *    void silc_channel_payload_free(SilcChannelPayload payload);
 184  *
 185  * DESCRIPTION
 186  *
 187  *    Frees Channel Payload and all data in it.
 188  *
 189  ***/
 190 void silc_channel_payload_free(SilcChannelPayload payload);
 191
 192 /****f* silccore/SilcChannelAPI/silc_channel_payload_list_free
 193  *
 194  * SYNOPSIS
 195  *
 196  *    void silc_channel_payload_list_free(SilcDList list);
 197  *
 198  * DESCRIPTION
 199  *
 200  *    Frees list of Channel Payloads and all data in them.
 201  *
 202  ***/
 203 void silc_channel_payload_list_free(SilcDList list);
 204
 205 /****f* silccore/SilcChannelAPI/silc_channel_get_name
 206  *
 207  * SYNOPSIS
 208  *
 209  *    unsigned char *silc_channel_get_name(SilcChannelPayload payload,
 210  *                                         SilcUInt32 *channel_name_len);
 211  *
 212  * DESCRIPTION
 213  *
 214  *    Return the channel name from the payload. The caller must not free it.
 215  *
 216  ***/
 217 unsigned char *silc_channel_get_name(SilcChannelPayload payload,
 218                                      SilcUInt32 *channel_name_len);
 219
 220 /****f* silccore/SilcChannelAPI/silc_channel_get_id
 221  *
 222  * SYNOPSIS
 223  *
 224  *    unsigned char *silc_channel_get_id(SilcChannelPayload payload,
 225  *                                       SilcUInt32 *channel_id_len);
 226  *
 227  * DESCRIPTION
 228  *
 229  *    Return the Channel ID data from the payload. The caller must not free it.
 230  *
 231  ***/
 232 unsigned char *silc_channel_get_id(SilcChannelPayload payload,
 233                                    SilcUInt32 *channel_id_len);
 234
 235 /****f* silccore/SilcChannelAPI/silc_channel_get_id_parse
 236  *
 237  * SYNOPSIS
 238  *
 239  *    SilcChannelID *silc_channel_get_id_parse(SilcChannelPayload payload);
 240  *
 241  * DESCRIPTION
 242  *
 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.
 246  *
 247  ***/
 248 SilcChannelID *silc_channel_get_id_parse(SilcChannelPayload payload);
 249
 250 /****f* silccore/SilcChannelAPI/silc_channel_get_mode
 251  *
 252  * SYNOPSIS
 253  *
 254  *    SilcUInt32 silc_channel_get_mode(SilcChannelPayload payload);
 255  *
 256  * DESCRIPTION
 257  *
 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.
 261  *
 262  ***/
 263 SilcUInt32 silc_channel_get_mode(SilcChannelPayload payload);
 264
 265 /****f* silccore/SilcChannelAPI/silc_channel_message_payload_decrypt
 266  *
 267  * SYNOPSIS
 268  *
 269  *    bool silc_channel_message_payload_decrypt(unsigned char *data,
 270  *                                              size_t data_len,
 271  *                                              SilcCipher cipher,
 272  *                                              SilcHmac hmac);
 273  *
 274  * DESCRIPTION
 275  *
 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.
 281  *
 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.
 286  *
 287  *    If the `hmac' is no provided then the MAC of the channel message is
 288  *    not verified.
 289  *
 290  ***/
 291 bool silc_channel_message_payload_decrypt(unsigned char *data,
 292                                           size_t data_len,
 293                                           SilcCipher cipher,
 294                                           SilcHmac hmac);
 295
 296 /****f* silccore/SilcChannelAPI/silc_channel_message_payload_parse
 297  *
 298  * SYNOPSIS
 299  *
 300  *    SilcChannelMessagePayload
 301  *    silc_channel_message_payload_parse(const unsigned char *payload,
 302  *                                       SilcUInt32 payload_len,
 303  *                                       SilcCipher cipher,
 304  *                                       SilcHmac hmac);
 305  *
 306  * DESCRIPTION
 307  *
 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.
 311  *
 312  *    If the `hmac' is no provided then the MAC of the channel message is
 313  *    not verified.
 314  *
 315  ***/
 316 SilcChannelMessagePayload
 317 silc_channel_message_payload_parse(unsigned char *payload,
 318                                    SilcUInt32 payload_len,
 319                                    SilcCipher cipher,
 320                                    SilcHmac hmac);
 321
 322 /****f* silccore/SilcChannelAPI/silc_channel_message_payload_encrypt
 323  *
 324  * SYNOPSIS
 325  *
 326  *    bool silc_channel_message_payload_encrypt(unsigned char *data,
 327  *                                              SilcUInt32 data_len,
 328  *                                              SilcUInt32 true_len,
 329  *                                              unsigned char *iv,
 330  *                                              SilcUInt32 iv_len,
 331  *                                              SilcCipher cipher,
 332  *                                              SilcHmac hmac);
 333  *
 334  * DESCRIPTION
 335  *
 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.
 341  *
 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.
 346  *
 347  ***/
 348 bool silc_channel_message_payload_encrypt(unsigned char *data,
 349                                           SilcUInt32 data_len,
 350                                           SilcUInt32 true_len,
 351                                           unsigned char *iv,
 352                                           SilcUInt32 iv_len,
 353                                           SilcCipher cipher,
 354                                           SilcHmac hmac);
 355
 356 /****f* silccore/SilcChannelAPI/silc_channel_message_payload_encode
 357  *
 358  * SYNOPSIS
 359  *
 360  *    SilcBuffer silc_channel_message_payload_encode(SilcUInt16 flags,
 361  *                                                   SilcUInt16 data_len,
 362  *                                                   const unsigned char *data,
 363  *                                                   SilcUInt16 iv_len,
 364  *                                                   unsigned char *iv,
 365  *                                                   SilcCipher cipher,
 366  *                                                   SilcHmac hmac.
 367  *                                                   SilcRng rng);
 368  *
 369  * DESCRIPTION
 370  *
 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
 378  *    the `rng' is used.
 379  *
 380  ***/
 381 SilcBuffer silc_channel_message_payload_encode(SilcUInt16 flags,
 382                                                SilcUInt16 data_len,
 383                                                const unsigned char *data,
 384                                                SilcUInt16 iv_len,
 385                                                unsigned char *iv,
 386                                                SilcCipher cipher,
 387                                                SilcHmac hmac,
 388                                                SilcRng rng);
 389
 390 /****f* silccore/SilcChannelAPI/silc_channel_message_payload_free
 391  *
 392  * SYNOPSIS
 393  *
 394  *    void
 395  *    silc_channel_message_payload_free(SilcChannelMessagePayload payload);
 396  *
 397  * DESCRIPTION
 398  *
 399  *    Free's Channel Message Payload and all data in it.
 400  *
 401  ***/
 402 void silc_channel_message_payload_free(SilcChannelMessagePayload payload);
 403
 404 /****f* silccore/SilcChannelAPI/silc_channel_message_get_flags
 405  *
 406  * SYNOPSIS
 407  *
 408  *    SilcMessageFlags
 409  *    silc_channel_message_get_flags(SilcChannelMessagePayload payload);
 410  *
 411  * DESCRIPTION
 412  *
 413  *    Returns the message flags from the payload.
 414  *
 415  ***/
 416 SilcMessageFlags
 417 silc_channel_message_get_flags(SilcChannelMessagePayload payload);
 418
 419 /****f* silccore/SilcChannelAPI/silc_channel_message_get_data
 420  *
 421  * SYNOPSIS
 422  *
 423  *    unsigned char *
 424  *    silc_channel_message_get_data(SilcChannelMessagePayload payload,
 425  *                                  SilcUInt32 *data_len);
 426  *
 427  * DESCRIPTION
 428  *
 429  *    Return the data in the payload, that is, the actual channel message.
 430  *    The caller must not free it.
 431  *
 432  ***/
 433 unsigned char *silc_channel_message_get_data(SilcChannelMessagePayload payload,
 434                                              SilcUInt32 *data_len);
 435
 436 /****f* silccore/SilcChannelAPI/silc_channel_message_get_mac
 437  *
 438  * SYNOPSIS
 439  *
 440  *    unsigned char *
 441  *    silc_channel_message_get_mac(SilcChannelMessagePayload payload);
 442  *
 443  * DESCRIPTION
 444  *
 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.
 447  *
 448  ***/
 449 unsigned char *silc_channel_message_get_mac(SilcChannelMessagePayload payload);
 450
 451 /****f* silccore/SilcChannelAPI/silc_channel_message_get_iv
 452  *
 453  * SYNOPSIS
 454  *
 455  *    unsigned char *
 456  *    silc_channel_message_get_iv(SilcChannelMessagePayload payload);
 457  *
 458  * DESCRIPTION
 459  *
 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.
 462  *
 463  ***/
 464 unsigned char *silc_channel_message_get_iv(SilcChannelMessagePayload payload);
 465
 466 /****f* silccore/SilcChannelAPI/silc_channel_key_payload_parse
 467  *
 468  * SYNOPSIS
 469  *
 470  *    SilcChannelKeyPayload
 471  *    silc_channel_key_payload_parse(const unsigned char *payload,
 472  *                                   uin32 payload_len);
 473  *
 474  * DESCRIPTION
 475  *
 476  *     Parses channel key payload returning new channel key payload
 477  *     structure.
 478  *
 479  ***/
 480 SilcChannelKeyPayload
 481 silc_channel_key_payload_parse(const unsigned char *payload,
 482                                SilcUInt32 payload_len);
 483
 484 /****f* silccore/SilcChannelAPI/silc_channel_key_payload_encode
 485  *
 486  * SYNOPSIS
 487  *
 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);
 494  *
 495  * DESCRIPTION
 496  *
 497  *    Encodes channel key payload into a buffer and returns it. This is used
 498  *    to add channel key payload into a packet.
 499  *
 500  ***/
 501 SilcBuffer silc_channel_key_payload_encode(SilcUInt16 id_len,
 502                                            const unsigned char *id,
 503                                            SilcUInt16 cipher_len,
 504                                            const unsigned char *cipher,
 505                                            SilcUInt16 key_len,
 506                                            const unsigned char *key);
 507
 508 /****f* silccore/SilcChannelAPI/silc_channel_key_payload_free
 509  *
 510  * SYNOPSIS
 511  *
 512  *    void silc_channel_key_payload_free(SilcChannelKeyPayload payload);
 513  *
 514  * DESCRIPTION
 515  *
 516  *    Frees the Channel Key Payload and all data in it.
 517  *
 518  ***/
 519 void silc_channel_key_payload_free(SilcChannelKeyPayload payload);
 520
 521 /****f* silccore/SilcChannelAPI/silc_channel_key_get_id
 522  *
 523  * SYNOPSIS
 524  *
 525  *    unsigned char *silc_channel_key_get_id(SilcChannelKeyPayload payload,
 526  *                                           SilcUInt32 *id_len);
 527  *
 528  * DESCRIPTION
 529  *
 530  *    Return the Channel ID data from the payload. The caller must not
 531  *    free it.
 532  *
 533  ***/
 534 unsigned char *silc_channel_key_get_id(SilcChannelKeyPayload payload,
 535                                        SilcUInt32 *id_len);
 536
 537 /****f* silccore/SilcChannelAPI/silc_channel_key_get_cipher
 538  *
 539  * SYNOPSIS
 540  *
 541  *    unsigned char *silc_channel_key_get_cipher(SilcChannelKeyPayload payload,
 542  *                                               SilcUInt32 *cipher_len);
 543  *
 544  * DESCRIPTION
 545  *
 546  *    Return the name of the cipher from the payload. The caller must not
 547  *    free it.
 548  *
 549  ***/
 550 unsigned char *silc_channel_key_get_cipher(SilcChannelKeyPayload payload,
 551                                            SilcUInt32 *cipher_len);
 552
 553 /****f* silccore/SilcChannelAPI/silc_channel_key_get_key
 554  *
 555  * SYNOPSIS
 556  *
 557  *    unsigned char *silc_channel_key_get_key(SilcChannelKeyPayload payload,
 558  *                                            SilcUInt32 *key_len);
 559  *
 560  * DESCRIPTION
 561  *
 562  *    Return the raw key material from the payload. The caller must not
 563  *    free it.
 564  *
 565  ***/
 566 unsigned char *silc_channel_key_get_key(SilcChannelKeyPayload payload,
 567                                         SilcUInt32 *key_len);
 568
 569 #endif