lib/silccore/silcmessage.h

   1 /*
   2
   3   silcmessage.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 -2002 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.
  26  *
  27  * This interface defines also the SILC_MESSAGE_FLAG_SIGNED Payload,
  28  * which defines how channel messages and private messages can be digitally
  29  * signed.  This interface provides the payload parsing, encoding,
  30  * signature computing and signature verification routines.
  31  *
  32  ***/
  33
  34 #ifndef SILCMESSAGE_H
  35 #define SILCMESSAGE_H
  36
  37 /****s* silccore/SilcMessageAPI/SilcMessagePayload
  38  *
  39  * NAME
  40  *
  41  *    typedef struct SilcMessagePayloadStruct *SilcMessagePayload;
  42  *
  43  *
  44  * DESCRIPTION
  45  *
  46  *    This context is the actual Message Payload and is allocated
  47  *    by silc_message_payload_parse and given as argument usually
  48  *    to all silc_message_* functions.  It is freed by the
  49  *    silc_message_payload_free function.
  50  *
  51  ***/
  52 typedef struct SilcMessagePayloadStruct *SilcMessagePayload;
  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_RESERVED    0x0200      /* to 0x0800 */
  81 #define SILC_MESSAGE_FLAG_PRIVATE     0x1000      /* to 0x8000 */
  82 /***/
  83
  84 /****f* silccore/SilcMessageAPI/silc_message_payload_decrypt
  85  *
  86  * SYNOPSIS
  87  *
  88  *    bool silc_message_payload_decrypt(unsigned char *data,
  89  *                                      size_t data_len,
  90  *                                      bool private_message,
  91  *                                      bool static_key,
  92  *                                      SilcCipher cipher,
  93  *                                      SilcHmac hmac,
  94  *                                      bool check_mac);
  95  *
  96  * DESCRIPTION
  97  *
  98  *    Decrypt Message Payload indicated by `data'.  If the payload is
  99  *    channel message then `private_message' is FALSE, and if it is
 100  *    private message it is TRUE.  If the private message key is static
 101  *    (pre-shared key) then protocol dictates that the IV is present
 102  *    and `static_key' must be set to TRUE.  If the key is not static
 103  *    (Key Agreement was done for the key) then it MUST be FALSE.  For
 104  *    channel messages the `static_key' is ignored.
 105  *
 106  *    This is usually used by the Message Payload interface itself but can
 107  *    be called by the appliation if separate decryption process is required.
 108  *    For example server might need to call this directly in some
 109  *    circumstances. The `cipher' is used to decrypt the payload.  If
 110  *    `check_mac' is FALSE then MAC is not verified.
 111  *
 112  ***/
 113 bool silc_message_payload_decrypt(unsigned char *data,
 114                                   size_t data_len,
 115                                   bool private_message,
 116                                   bool static_key,
 117                                   SilcCipher cipher,
 118                                   SilcHmac hmac,
 119                                   bool check_mac);
 120
 121 /****f* silccore/SilcMessageAPI/silc_message_payload_parse
 122  *
 123  * SYNOPSIS
 124  *
 125  *    SilcMessagePayload
 126  *    silc_message_payload_parse(unsigned char *payload,
 127  *                               SilcUInt32 payload_len,
 128  *                               bool private_message,
 129  *                               bool static_key,
 130  *                               SilcCipher cipher,
 131  *                               SilcHmac hmac);
 132  *
 133  * DESCRIPTION
 134  *
 135  *    Parses Message Payload returning new payload structure.  This also
 136  *    decrypts the payload and checks the MAC.  If the payload is
 137  *    channel message then `private_message' is FALSE, and if it is
 138  *    private message it is TRUE.  If the private message key is static
 139  *    (pre-shared key) then protocol dictates that the IV is present
 140  *    and `static_key' must be set to TRUE.  If the key is not static
 141  *    (Key Agreement was done for the key) then it MUST be FALSE.  For
 142  *    channel messages the `static_key' is ignored.
 143  *
 144  *    If the `hmac' is no provided then the MAC of the channel message is
 145  *    not verified.  If the message is private message and `cipher' is NULL
 146  *    then this assumes that the packet was decrypted with session keys
 147  *    (no private message key) and this merely decodes the payload.
 148  *
 149  ***/
 150 SilcMessagePayload
 151 silc_message_payload_parse(unsigned char *payload,
 152                            SilcUInt32 payload_len,
 153                            bool private_message,
 154                            bool static_key,
 155                            SilcCipher cipher,
 156                            SilcHmac hmac);
 157
 158 /****f* silccore/SilcMessageAPI/silc_message_payload_encrypt
 159  *
 160  * SYNOPSIS
 161  *
 162  *    bool silc_message_payload_encrypt(unsigned char *data,
 163  *                                      SilcUInt32 data_len,
 164  *                                      unsigned char *iv,
 165  *                                      SilcUInt32 iv_len,
 166  *                                      SilcCipher cipher,
 167  *                                      SilcHmac hmac);
 168  *
 169  * DESCRIPTION
 170  *
 171  *    This function is used to encrypt the Messsage Payload which is
 172  *    the `data' and `data_len'.  The `data_len' is the data length which
 173  *    is used to create MAC out of.  The `data' MUST have additional space
 174  *    after `data_len' bytes for the MAC which is appended to the data.
 175  *
 176  *    This is usually used by the Message Payload interface itself but can
 177  *    be called by the appliation if separate encryption process is required.
 178  *    For example server might need to call this directly in some
 179  *    circumstances. The `cipher' is used to encrypt the payload and `hmac'
 180  *    to compute the MAC for the payload.
 181  *
 182  ***/
 183 bool silc_message_payload_encrypt(unsigned char *data,
 184                                   SilcUInt32 data_len,
 185                                   unsigned char *iv,
 186                                   SilcUInt32 iv_len,
 187                                   SilcCipher cipher,
 188                                   SilcHmac hmac);
 189
 190 /****f* silccore/SilcMessageAPI/silc_message_payload_encode
 191  *
 192  * SYNOPSIS
 193  *
 194  *    SilcBuffer silc_message_payload_encode(SilcMessageFlags flags,
 195  *                                           const unsigned char *data,
 196  *                                           SilcUInt32 data_len,
 197  *                                           bool generate_iv,
 198  *                                           bool private_message,
 199  *                                           SilcCipher cipher,
 200  *                                           SilcHmac hmac,
 201  *                                           SilcRng rng);
 202  *
 203  * DESCRIPTION
 204  *
 205  *    Encodes a Message Payload into a buffer and returns it.  This is
 206  *    used to encode channel messages and private messages into a packet.
 207  *    If `private_message' is FALSE then this encodes channel message, if
 208  *    it is TRUE this encodes private message.  If `private_message' is
 209  *    TRUE then `generate_iv' MUST be FALSE if the private message key
 210  *    `cipher' is not static key (pre-shared key).  If it is static key
 211  *    then protocol dictates that IV must be present in the Message Payload
 212  *    and `generate_iv' must be TRUE.  The caller must know whether the key
 213  *    is static or not for private messages.  If the key was generated with
 214  *    Key Agreement protocol then `generate_iv' is always FALSE.  For
 215  *    channel messages `generate_iv' is always set to TRUE value.
 216  *
 217  *    The `cipher' is the cipher used to encrypt the message and `hmac'
 218  *    is used to compute the MAC for the payload.  If encoding private
 219  *    message that will be encrypted with session keys (no private message
 220  *    key) then `cipher' and `hmac' is NULL and this merely encodes the
 221  *    payload buffer, and the caller must encrypt the packet later.
 222  *
 223  *    If `rng' is NULL then global RNG is used, if non-NULL then the
 224  *    `rng' is used (for IV and padding generation).
 225  *
 226  ***/
 227 SilcBuffer silc_message_payload_encode(SilcMessageFlags flags,
 228                                        const unsigned char *data,
 229                                        SilcUInt32 data_len,
 230                                        bool generate_iv,
 231                                        bool private_message,
 232                                        SilcCipher cipher,
 233                                        SilcHmac hmac,
 234                                        SilcRng rng);
 235
 236 /****f* silccore/SilcMessageAPI/silc_message_payload_free
 237  *
 238  * SYNOPSIS
 239  *
 240  *    void silc_message_payload_free(SilcMessagePayload payload);
 241  *
 242  * DESCRIPTION
 243  *
 244  *    Free's Message Payload and all data in it.
 245  *
 246  ***/
 247 void silc_message_payload_free(SilcMessagePayload payload);
 248
 249 /****f* silccore/SilcMessageAPI/silc_message_get_flags
 250  *
 251  * SYNOPSIS
 252  *
 253  *    SilcMessageFlags silc_message_get_flags(SilcMessagePayload payload);
 254  *
 255  * DESCRIPTION
 256  *
 257  *    Returns the message flags from the payload.
 258  *
 259  ***/
 260 SilcMessageFlags silc_message_get_flags(SilcMessagePayload payload);
 261
 262 /****f* silccore/SilcMessageAPI/silc_message_get_data
 263  *
 264  * SYNOPSIS
 265  *
 266  *    unsigned char *
 267  *    silc_message_get_data(SilcMessagePayload payload,
 268  *                                  SilcUInt32 *data_len);
 269  *
 270  * DESCRIPTION
 271  *
 272  *    Return the data in the payload, that is, the actual message data.
 273  *    The caller must not free it.
 274  *
 275  ***/
 276 unsigned char *silc_message_get_data(SilcMessagePayload payload,
 277                                      SilcUInt32 *data_len);
 278
 279 /****f* silccore/SilcMessageAPI/silc_message_get_mac
 280  *
 281  * SYNOPSIS
 282  *
 283  *    unsigned char *
 284  *    silc_message_get_mac(SilcMessagePayload payload);
 285  *
 286  * DESCRIPTION
 287  *
 288  *    Return the MAC of the payload. The caller must already know the
 289  *    length of the MAC. The caller must not free the MAC.
 290  *
 291  ***/
 292 unsigned char *silc_message_get_mac(SilcMessagePayload payload);
 293
 294 /****f* silccore/SilcMessageAPI/silc_message_get_iv
 295  *
 296  * SYNOPSIS
 297  *
 298  *    unsigned char *
 299  *    silc_message_get_iv(SilcMessagePayload payload);
 300  *
 301  * DESCRIPTION
 302  *
 303  *    Return the IV of the payload. The caller must already know the
 304  *    length of the IV. The caller must not free the IV.
 305  *
 306  ***/
 307 unsigned char *silc_message_get_iv(SilcMessagePayload payload);
 308
 309 /****s* silccore/SilcMessageAPI/SilcMessageSignedPayload
 310  *
 311  * NAME
 312  *
 313  *    typedef struct SilcMessageSignedPayloadStruct *SilcMessageSignedPayload;
 314  *
 315  *
 316  * DESCRIPTION
 317  *
 318  *    This context represents the SILC_MESSAGE_FLAG_SIGNED Payload which
 319  *    is used with channel messages and private messages to indicate that
 320  *    the message is digitally signed.  This payload may include the
 321  *    message sender's public key and it includes the digital signature.
 322  *    This payload MUST NOT be used in any other context except with
 323  *    channel and private message sending and reception.
 324  *
 325  ***/
 326 typedef struct SilcMessageSignedPayloadStruct *SilcMessageSignedPayload;
 327
 328 /****f* silccore/SilcMessageAPI/silc_message_signed_payload_parse
 329  *
 330  * SYNOPSIS
 331  *
 332  *    SilcMessageSignedPayload
 333  *    silc_message_signed_payload_parse(const unsigned char *data,
 334  *                                      SilcUInt32 data_len);
 335  *
 336  * DESCRIPTION
 337  *
 338  *    Parses the SILC_MESSAGE_FLAG_SIGNED Payload from the `data' of
 339  *    length of `data_len' bytes.  The `data' must be payload without
 340  *    the actual message payload.  Returns the parsed payload or NULL
 341  *    on error.  Caller must free the returned payload.
 342  *
 343  ***/
 344 SilcMessageSignedPayload
 345 silc_message_signed_payload_parse(const unsigned char *data,
 346                                   SilcUInt32 data_len);
 347
 348 /****f* silccore/SilcMessageAPI/silc_message_signed_payload_encode
 349  *
 350  * SYNOPSIS
 351  *
 352  *    SilcBuffer
 353  *    silc_message_signed_payload_encode(const unsigned char *message_payload,
 354  *                                       SilcUInt32 message_payload_len,
 355  *                                       SilcPublicKey public_key,
 356  *                                       SilcPrivateKey private_key,
 357  *                                       bool include_public_key);
 358  *
 359  * DESCRIPTION
 360  *
 361  *    Encodes the SILC_MESSAGE_FLAG_SIGNED Payload and computes the
 362  *    digital signature.  The `message_payload' is the message data that
 363  *    is used in the signature computation.  The encoding of the buffer
 364  *    is specified in the SILC protocol.  If `include_public_key' is
 365  *    TRUE then the public key included in the payload.  The `private_key'
 366  *    is used to produce the signature.  This function returns the encoded
 367  *    payload with the signature or NULL on error.  Caller must free the
 368  *    returned buffer.
 369  *
 370  ***/
 371 SilcBuffer
 372 silc_message_signed_payload_encode(const unsigned char *message_payload,
 373                                    SilcUInt32 message_payload_len,
 374                                    SilcPublicKey public_key,
 375                                    SilcPrivateKey private_key,
 376                                    SilcHash hash,
 377                                    bool include_public_key);
 378
 379 /****f* silccore/SilcMessageAPI/silc_message_signed_payload_free
 380  *
 381  * SYNOPSIS
 382  *
 383  *    void silc_message_signed_payload_free(SilcMessageSignedPayload sig);
 384  *
 385  * DESCRIPTION
 386  *
 387  *    Frees the SILC_MESSAGE_FLAG_SIGNED Payload.
 388  *
 389  ***/
 390 void silc_message_signed_payload_free(SilcMessageSignedPayload sig);
 391
 392 /****f* silccore/SilcMessageAPI/silc_message_signed_verify
 393  *
 394  * SYNOPSIS
 395  *
 396  *    int silc_message_signed_verify(SilcMessageSignedPayload sig,
 397  *                                   SilcMessagePayload message,
 398  *                                   SilcPublicKey remote_public_key,
 399  *                                   SilcHash hash);
 400  *
 401  * DESCRIPTION
 402  *
 403  *    This routine can be used to verify the signature found in
 404  *    SILC_MESSAGE_FLAG_SIGNED Payload.  This returns SILC_AUTH_OK if the
 405  *    signature verification was successful.
 406  *
 407  ***/
 408 int silc_message_signed_verify(SilcMessageSignedPayload sig,
 409                                SilcMessagePayload message,
 410                                SilcPublicKey remote_public_key,
 411                                SilcHash hash);
 412
 413 /****f* silccore/SilcMessageAPI/silc_message_signed_get_public_key
 414  *
 415  * SYNOPSIS
 416  *
 417  *    SilcPublicKey
 418  *    silc_message_signed_get_public_key(SilcMessageSignedPayload sig);
 419  *
 420  * DESCRIPTION
 421  *
 422  *    Returns the public key from the SILC_MESSAGE_FLAG_SIGNED Payload
 423  *    or NULL if it does not include public key.  The caller must free
 424  *    the returned public key.
 425  *
 426  ***/
 427 SilcPublicKey
 428 silc_message_signed_get_public_key(SilcMessageSignedPayload sig);
 429
 430 #endif /* SILCMESSAGE_H */