lib/silccore/silcmessage.h

   1 /*
   2
   3   silcmessage.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 2007 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; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silccore/SILC Message Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * This interface includes the implementation of the Message Payload that
  25  * is used to send private messages and channel messages.  The interface
  26  * is also able to automatically provide digital signature in the messages
  27  * if it is requested.  Message digital signatures may also be verified with
  28  * this interface.
  29  *
  30  ***/
  31
  32 #ifndef SILCMESSAGE_H
  33 #define SILCMESSAGE_H
  34
  35 /****s* silccore/SilcMessageAPI/SilcMessagePayload
  36  *
  37  * NAME
  38  *
  39  *    typedef struct SilcMessagePayloadObject
  40  *      *SilcMessagePayload, SilcMessagePayloadStruct;
  41  *
  42  *
  43  * DESCRIPTION
  44  *
  45  *    This context is the actual Message Payload and is allocated
  46  *    by silc_message_payload_parse and given as argument usually
  47  *    to all silc_message_* functions.  It is freed by the
  48  *    silc_message_payload_free function.
  49  *
  50  ***/
  51 typedef struct SilcMessagePayloadObject
  52   *SilcMessagePayload, SilcMessagePayloadStruct;
  53
  54 /****d* silccore/SilcMessageAPI/SilcMessageFlags
  55  *
  56  * NAME
  57  *
  58  *    typedef SilcUInt16 SilcMessageFlags;
  59  *
  60  * DESCRIPTION
  61  *
  62  *    The message flags type definition and the message flags.  The
  63  *    message flags are used to indicate some status of the message.
  64  *
  65  * SOURCE
  66  */
  67 typedef SilcUInt16 SilcMessageFlags;
  68
  69 /* The message flags */
  70 #define SILC_MESSAGE_FLAG_NONE        0x0000      /* No flags */
  71 #define SILC_MESSAGE_FLAG_AUTOREPLY   0x0001      /* Automatically replied */
  72 #define SILC_MESSAGE_FLAG_NOREPLY     0x0002      /* Send no reply to this */
  73 #define SILC_MESSAGE_FLAG_ACTION      0x0004      /* Action message */
  74 #define SILC_MESSAGE_FLAG_NOTICE      0x0008      /* Notice message */
  75 #define SILC_MESSAGE_FLAG_REQUEST     0x0010      /* A request */
  76 #define SILC_MESSAGE_FLAG_SIGNED      0x0020      /* Message is signed */
  77 #define SILC_MESSAGE_FLAG_REPLY       0x0040      /* A reply */
  78 #define SILC_MESSAGE_FLAG_DATA        0x0080      /* MIME object */
  79 #define SILC_MESSAGE_FLAG_UTF8        0x0100      /* UTF-8 string */
  80 #define SILC_MESSAGE_FLAG_ACK         0x0200      /* ACK messages */
  81 #define SILC_MESSAGE_FLAG_STOP        0x0400      /* Stop indication */
  82 #define SILC_MESSAGE_FLAG_RESERVED    0x0800      /* to 0x1000 */
  83 #define SILC_MESSAGE_FLAG_PRIVATE     0x2000      /* to 0x8000 */
  84 /***/
  85
  86 /****f* silccore/SilcMessageAPI/silc_message_payload_decrypt
  87  *
  88  * SYNOPSIS
  89  *
  90  *    SilcBool silc_message_payload_decrypt(unsigned char *data,
  91  *                                          size_t data_len,
  92  *                                          SilcBool private_message,
  93  *                                          SilcBool static_key,
  94  *                                          SilcCipher cipher,
  95  *                                          SilcHmac hmac,
  96  *                                          unsigned char *sender_id,
  97  *                                          SilcUInt32 sender_id_len,
  98  *                                          unsigned char *receiver_id,
  99  *                                          SilcUInt32 receiver_id_len,
 100  *                                          SilcBool check_mac);
 101  *
 102  * DESCRIPTION
 103  *
 104  *    Decrypt Message Payload indicated by `data'.  If the payload is
 105  *    channel message then `private_message' is FALSE, and if it is
 106  *    private message it is TRUE.  If the private message key is static
 107  *    (pre-shared key) then protocol dictates that the IV is present
 108  *    and `static_key' must be set to TRUE.  If the key is not static
 109  *    (Key Agreement was done for the key) then it MUST be FALSE.  For
 110  *    channel messages the `static_key' is ignored.
 111  *
 112  *    The `sender_id' and `receiver_id' are the IDs from the packet header
 113  *    of the packet where this message payload was received.
 114  *
 115  *    This is usually used by the Message Payload interface itself but can
 116  *    be called by the appliation if separate decryption process is required.
 117  *    For example server might need to call this directly in some
 118  *    circumstances. The `cipher' is used to decrypt the payload.  If
 119  *    `check_mac' is FALSE then MAC is not verified.
 120  *
 121  ***/
 122 SilcBool silc_message_payload_decrypt(unsigned char *data,
 123                                       size_t data_len,
 124                                       SilcBool private_message,
 125                                       SilcBool static_key,
 126                                       SilcCipher cipher,
 127                                       SilcHmac hmac,
 128                                       unsigned char *sender_id,
 129                                       SilcUInt32 sender_id_len,
 130                                       unsigned char *receiver_id,
 131                                       SilcUInt32 receiver_id_len,
 132                                       SilcBool check_mac);
 133
 134 /****f* silccore/SilcMessageAPI/silc_message_payload_parse
 135  *
 136  * SYNOPSIS
 137  *
 138  *    SilcMessagePayload
 139  *    silc_message_payload_parse(unsigned char *payload,
 140  *                               SilcUInt32 payload_len,
 141  *                               SilcBool private_message,
 142  *                               SilcBool static_key,
 143  *                               SilcCipher cipher,
 144  *                               SilcHmac hmac,
 145  *                               unsigned char *sender_id,
 146  *                               SilcUInt32 sender_id_len,
 147  *                               unsigned char *receiver_id,
 148  *                               SilcUInt32 receiver_id_len,
 149  *                               SilcStack stack,
 150  *                               SilcBool no_allocation,
 151  *                               SilcMessagePayload message);
 152  *
 153  * DESCRIPTION
 154  *
 155  *    Parses Message Payload returning new payload structure.  This also
 156  *    decrypts the payload and checks the MAC.  If the payload is
 157  *    channel message then `private_message' is FALSE, and if it is
 158  *    private message it is TRUE.  If the private message key is static
 159  *    (pre-shared key) then protocol dictates that the IV is present
 160  *    and `static_key' must be set to TRUE.  If the key is not static
 161  *    (Key Agreement was done for the key) then it MUST be FALSE.  For
 162  *    channel messages the `static_key' is ignored.
 163  *
 164  *    If the `hmac' is no provided then the MAC of the channel message is
 165  *    not verified.  If the message is private message and `cipher' is NULL
 166  *    then this assumes that the packet was decrypted with session keys
 167  *    (no private message key) and this merely decodes the payload.
 168  *
 169  *    The `sender_id' and `receiver_id' are the IDs from the packet header
 170  *    of the packet where this message payload was received.
 171  *
 172  *    If the `message' is non-NULL then that pre-allocated context is
 173  *    used in parsing.  Same context is returned.  Otherwise new context
 174  *    is allocated and returned.  If the `stack' is non-NULL then memory
 175  *    is allocated from that stack.  If `no_allocation' is TRUE then the
 176  *    `message' must be provided and data is merely parsed and referenced
 177  *    from `payload' and will become invalid when `payload' invalidates.
 178  *    If `no_allocation' is TRUE the routine does not do any allocations.
 179  *
 180  ***/
 181 SilcMessagePayload
 182 silc_message_payload_parse(unsigned char *payload,
 183                            SilcUInt32 payload_len,
 184                            SilcBool private_message,
 185                            SilcBool static_key,
 186                            SilcCipher cipher,
 187                            SilcHmac hmac,
 188                            unsigned char *sender_id,
 189                            SilcUInt32 sender_id_len,
 190                            unsigned char *receiver_id,
 191                            SilcUInt32 receiver_id_len,
 192                            SilcStack stack,
 193                            SilcBool no_allocation,
 194                            SilcMessagePayload message);
 195
 196 /****f* silccore/SilcMessageAPI/silc_message_payload_encrypt
 197  *
 198  * SYNOPSIS
 199  *
 200  *    SilcBool silc_message_payload_encrypt(unsigned char *data,
 201  *                                          SilcUInt32 data_len,
 202  *                                          SilcUInt32 true_len,
 203  *                                          unsigned char *iv,
 204  *                                          SilcID *sender_id,
 205  *                                          SilcID *receiver_id,
 206  *                                          SilcCipher cipher,
 207  *                                          SilcHmac hmac);
 208  *
 209  * DESCRIPTION
 210  *
 211  *    This function is used to encrypt the Messsage Payload which is
 212  *    the `data' and `data_len'.  The `data_len' is the data length which
 213  *    is used to create MAC out of.  The `data' MUST have additional space
 214  *    after `true_len' bytes for the MAC which is appended to the data.
 215  *    The `sender_id' is the ID message sender and `receiver_id' is ID of
 216  *    message receiver.
 217  *
 218  *    This is usually used by the Message Payload interface itself but can
 219  *    be called by the appliation if separate encryption process is required.
 220  *    For example server might need to call this directly in some
 221  *    circumstances. The `cipher' is used to encrypt the payload and `hmac'
 222  *    to compute the MAC for the payload.
 223  *
 224  ***/
 225 SilcBool silc_message_payload_encrypt(unsigned char *data,
 226                                       SilcUInt32 data_len,
 227                                       SilcUInt32 true_len,
 228                                       unsigned char *iv,
 229                                       SilcID *sender_id,
 230                                       SilcID *receiver_id,
 231                                       SilcCipher cipher,
 232                                       SilcHmac hmac);
 233
 234 /****f* silccore/SilcMessageAPI/SilcMessagePayloadEncoded
 235  *
 236  * SYNOPSIS
 237  *
 238  *    typedef void (*SilcMessagePayloadEncoded)(const SilcBuffer message,
 239  *                                              void *context);
 240  *
 241  * DESCRIPTION
 242  *
 243  *    This callback is given as arugment to silc_message_payload_encode
 244  *    and will be called when the message payload has been encoded.  If
 245  *    `message' is NULL, encoding failed.
 246  *
 247  ***/
 248 typedef void (*SilcMessagePayloadEncoded)(SilcBuffer message,
 249                                           void *context);
 250
 251 /****f* silccore/SilcMessageAPI/silc_message_payload_encode
 252  *
 253  * SYNOPSIS
 254  *
 255  *    SilcAsyncOperation
 256  *    silc_message_payload_encode(SilcMessageFlags flags,
 257  *                                const unsigned char *data,
 258  *                                SilcUInt32 data_len,
 259  *                                SilcBool generate_iv,
 260  *                                SilcBool private_message,
 261  *                                SilcCipher cipher,
 262  *                                SilcHmac hmac,
 263  *                                SilcRng rng,
 264  *                                SilcPublicKey public_key,
 265  *                                SilcPrivateKey private_key,
 266  *                                SilcHash hash,
 267  *                                SilcID *sender_id,
 268  *                                SilcID *receiver_id,
 269  *                                SilcStack stack,
 270  *                                SilcMessagePayloadEncoded encoded,
 271  *                                void *context);
 272  *
 273  * DESCRIPTION
 274  *
 275  *    Encodes a Message Payload into a buffer and returns it to the `encoded'
 276  *    callback.  This is used to encode channel messages and private messages
 277  *    into a packet.  If `private_message' is FALSE then this encodes channel
 278  *    message, if it is TRUE this encodes private message.  If
 279  *    `private_message' is TRUE then `generate_iv' MUST be FALSE if the private
 280  *    message key `cipher' is not static key (pre-shared key).  If it is static
 281  *    key then protocol dictates that IV must be present in the Message Payload
 282  *    and `generate_iv' must be TRUE.  The caller must know whether the key
 283  *    is static or not for private messages.  If the key was generated with
 284  *    Key Agreement protocol then `generate_iv' is always FALSE.  For
 285  *    channel messages `generate_iv' is always set to TRUE value.
 286  *
 287  *    The `cipher' is the cipher used to encrypt the message and `hmac'
 288  *    is used to compute the MAC for the payload.  If encoding private
 289  *    message that will be encrypted with session keys (no private message
 290  *    key) then `cipher' and `hmac' is NULL and this merely encodes the
 291  *    payload buffer, and the caller must encrypt the packet later.
 292  *    If `rng' is NULL then global RNG is used, if non-NULL then the
 293  *    `rng' is used (for IV and padding generation).
 294  *
 295  *    The `public_key', `private_key' and `hash' are provided only if the
 296  *    flags includes SILC_MESSAGE_FLAG_SIGNED, in which case the message
 297  *    will be digitally signed.  If `public_key' is non-NULL then it will
 298  *    be included in the message.  The `private_message' and `hash' MUST
 299  *    be provided.  The `hash' SHOULD be SHA1.
 300  *
 301  *    The `sender_id' is the ID message sender and `receiver_id' is ID of
 302  *    message receiver.
 303  *
 304  *    If `stack' is non-NULL the message payload is allocated from stack.
 305  *    The memory will be returned back to `stack' after the `encoded' has
 306  *    been called.
 307  *
 308  ***/
 309 SilcAsyncOperation
 310 silc_message_payload_encode(SilcMessageFlags flags,
 311                             const unsigned char *data,
 312                             SilcUInt32 data_len,
 313                             SilcBool generate_iv,
 314                             SilcBool private_message,
 315                             SilcCipher cipher,
 316                             SilcHmac hmac,
 317                             SilcRng rng,
 318                             SilcPublicKey public_key,
 319                             SilcPrivateKey private_key,
 320                             SilcHash hash,
 321                             SilcID *sender_id,
 322                             SilcID *receiver_id,
 323                             SilcStack stack,
 324                             SilcMessagePayloadEncoded encoded,
 325                             void *context);
 326
 327 /****f* silccore/SilcMessageAPI/silc_message_payload_free
 328  *
 329  * SYNOPSIS
 330  *
 331  *    void silc_message_payload_free(SilcMessagePayload payload);
 332  *
 333  * DESCRIPTION
 334  *
 335  *    Free's Message Payload and all data in it.
 336  *
 337  ***/
 338 void silc_message_payload_free(SilcMessagePayload payload);
 339
 340 /****f* silccore/SilcMessageAPI/silc_message_get_flags
 341  *
 342  * SYNOPSIS
 343  *
 344  *    SilcMessageFlags silc_message_get_flags(SilcMessagePayload payload);
 345  *
 346  * DESCRIPTION
 347  *
 348  *    Returns the message flags from the payload.
 349  *
 350  ***/
 351 SilcMessageFlags silc_message_get_flags(SilcMessagePayload payload);
 352
 353 /****f* silccore/SilcMessageAPI/silc_message_get_data
 354  *
 355  * SYNOPSIS
 356  *
 357  *    unsigned char *
 358  *    silc_message_get_data(SilcMessagePayload payload,
 359  *                                  SilcUInt32 *data_len);
 360  *
 361  * DESCRIPTION
 362  *
 363  *    Return the data in the payload, that is, the actual message data.
 364  *    The caller must not free it.
 365  *
 366  ***/
 367 unsigned char *silc_message_get_data(SilcMessagePayload payload,
 368                                      SilcUInt32 *data_len);
 369
 370 /****f* silccore/SilcMessageAPI/silc_message_get_mac
 371  *
 372  * SYNOPSIS
 373  *
 374  *    unsigned char *
 375  *    silc_message_get_mac(SilcMessagePayload payload);
 376  *
 377  * DESCRIPTION
 378  *
 379  *    Return the MAC of the payload. The caller must already know the
 380  *    length of the MAC. The caller must not free the MAC.
 381  *
 382  ***/
 383 unsigned char *silc_message_get_mac(SilcMessagePayload payload);
 384
 385 /****f* silccore/SilcMessageAPI/silc_message_signed_verify
 386  *
 387  * SYNOPSIS
 388  *
 389  *    SilcAsyncOperation
 390  *    silc_message_signed_verify(SilcMessagePayload message,
 391  *                               SilcPublicKey remote_public_key,
 392  *                               SilcHash hash,
 393  *                               SilcAuthResultCb result,
 394  *                               void *context);
 395  *
 396  *
 397  * DESCRIPTION
 398  *
 399  *    This routine can be used to verify the digital signature from the
 400  *    message indicated by `message'.  The signature is present only if
 401  *    the SILC_MESSAGE_FLAG_SIGNED is set in the message flags.  The
 402  *    result of the verification is returned to `result' callback.
 403  *
 404  ***/
 405 SilcAsyncOperation silc_message_signed_verify(SilcMessagePayload message,
 406                                               SilcPublicKey remote_public_key,
 407                                               SilcHash hash,
 408                                               SilcAuthResultCb result,
 409                                               void *context);
 410
 411 /****f* silccore/SilcMessageAPI/silc_message_signed_get_public_key
 412  *
 413  * SYNOPSIS
 414  *
 415  *    SilcPublicKey
 416  *    silc_message_signed_get_public_key(SilcMessagePayload payload,
 417  *                                       const unsigned char **pk_data,
 418  *                                       SilcUInt32 *pk_data_len);
 419  *
 420  * DESCRIPTION
 421  *
 422  *    Returns the decoded SilcPublicKey from the message payload or NULL
 423  *    if it does not include public key.  The caller must free the returned
 424  *    public key pointer.  This also returns the raw public key (before
 425  *    decoding) into `pk_data' and `pk_data_len' if they are provided.  The
 426  *    caller must not free these pointers.
 427  *
 428  ***/
 429 SilcPublicKey
 430 silc_message_signed_get_public_key(SilcMessagePayload payload,
 431                                    const unsigned char **pk_data,
 432                                    SilcUInt32 *pk_data_len);
 433
 434 #include "silcmessage_i.h"
 435
 436 #endif /* SILCMESSAGE_H */