lib/silccore/silcmessage.h

   1 /*
   2
   3   silcmessage.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 2006 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 /****s* silccore/SilcMessageAPI/SilcMessageSignedPayload
  55  *
  56  * NAME
  57  *
  58  *    typedef struct SilcMessageSignedPayloadStruct *SilcMessageSignedPayload;
  59  *
  60  *
  61  * DESCRIPTION
  62  *
  63  *    This context represents the SILC_MESSAGE_FLAG_SIGNED Payload which
  64  *    is used with channel messages and private messages to indicate that
  65  *    the message is digitally signed.  This payload may include the
  66  *    message sender's public key and it includes the digital signature.
  67  *    This payload MUST NOT be used in any other context except with
  68  *    channel and private message sending and reception.
  69  *
  70  ***/
  71 typedef struct SilcMessageSignedPayloadStruct *SilcMessageSignedPayload;
  72
  73 /****d* silccore/SilcMessageAPI/SilcMessageFlags
  74  *
  75  * NAME
  76  *
  77  *    typedef SilcUInt16 SilcMessageFlags;
  78  *
  79  * DESCRIPTION
  80  *
  81  *    The message flags type definition and the message flags.  The
  82  *    message flags are used to indicate some status of the message.
  83  *
  84  * SOURCE
  85  */
  86 typedef SilcUInt16 SilcMessageFlags;
  87
  88 /* The message flags */
  89 #define SILC_MESSAGE_FLAG_NONE        0x0000      /* No flags */
  90 #define SILC_MESSAGE_FLAG_AUTOREPLY   0x0001      /* Automatically replied */
  91 #define SILC_MESSAGE_FLAG_NOREPLY     0x0002      /* Send no reply to this */
  92 #define SILC_MESSAGE_FLAG_ACTION      0x0004      /* Action message */
  93 #define SILC_MESSAGE_FLAG_NOTICE      0x0008      /* Notice message */
  94 #define SILC_MESSAGE_FLAG_REQUEST     0x0010      /* A request */
  95 #define SILC_MESSAGE_FLAG_SIGNED      0x0020      /* Message is signed */
  96 #define SILC_MESSAGE_FLAG_REPLY       0x0040      /* A reply */
  97 #define SILC_MESSAGE_FLAG_DATA        0x0080      /* MIME object */
  98 #define SILC_MESSAGE_FLAG_UTF8        0x0100      /* UTF-8 string */
  99 #define SILC_MESSAGE_FLAG_ACK         0x0200      /* ACK messages */
 100 #define SILC_MESSAGE_FLAG_STOP        0x0400      /* Stop indication */
 101 #define SILC_MESSAGE_FLAG_RESERVED    0x0800      /* to 0x1000 */
 102 #define SILC_MESSAGE_FLAG_PRIVATE     0x2000      /* to 0x8000 */
 103 /***/
 104
 105 /****f* silccore/SilcMessageAPI/silc_message_payload_decrypt
 106  *
 107  * SYNOPSIS
 108  *
 109  *    SilcBool silc_message_payload_decrypt(unsigned char *data,
 110  *                                          size_t data_len,
 111  *                                          SilcBool private_message,
 112  *                                          SilcBool static_key,
 113  *                                          SilcCipher cipher,
 114  *                                          SilcHmac hmac,
 115  *                                          SilcBool check_mac);
 116  *
 117  * DESCRIPTION
 118  *
 119  *    Decrypt Message Payload indicated by `data'.  If the payload is
 120  *    channel message then `private_message' is FALSE, and if it is
 121  *    private message it is TRUE.  If the private message key is static
 122  *    (pre-shared key) then protocol dictates that the IV is present
 123  *    and `static_key' must be set to TRUE.  If the key is not static
 124  *    (Key Agreement was done for the key) then it MUST be FALSE.  For
 125  *    channel messages the `static_key' is ignored.
 126  *
 127  *    This is usually used by the Message Payload interface itself but can
 128  *    be called by the appliation if separate decryption process is required.
 129  *    For example server might need to call this directly in some
 130  *    circumstances. The `cipher' is used to decrypt the payload.  If
 131  *    `check_mac' is FALSE then MAC is not verified.
 132  *
 133  ***/
 134 SilcBool silc_message_payload_decrypt(unsigned char *data,
 135                                       size_t data_len,
 136                                       SilcBool private_message,
 137                                       SilcBool static_key,
 138                                       SilcCipher cipher,
 139                                       SilcHmac hmac,
 140                                       SilcBool check_mac);
 141
 142 /****f* silccore/SilcMessageAPI/silc_message_payload_parse
 143  *
 144  * SYNOPSIS
 145  *
 146  *    SilcMessagePayload
 147  *    silc_message_payload_parse(unsigned char *payload,
 148  *                               SilcUInt32 payload_len,
 149  *                               SilcBool private_message,
 150  *                               SilcBool static_key,
 151  *                               SilcCipher cipher,
 152  *                               SilcHmac hmac);
 153  *
 154  * DESCRIPTION
 155  *
 156  *    Parses Message Payload returning new payload structure.  This also
 157  *    decrypts the payload and checks the MAC.  If the payload is
 158  *    channel message then `private_message' is FALSE, and if it is
 159  *    private message it is TRUE.  If the private message key is static
 160  *    (pre-shared key) then protocol dictates that the IV is present
 161  *    and `static_key' must be set to TRUE.  If the key is not static
 162  *    (Key Agreement was done for the key) then it MUST be FALSE.  For
 163  *    channel messages the `static_key' is ignored.
 164  *
 165  *    If the `hmac' is no provided then the MAC of the channel message is
 166  *    not verified.  If the message is private message and `cipher' is NULL
 167  *    then this assumes that the packet was decrypted with session keys
 168  *    (no private message key) and this merely decodes the payload.
 169  *
 170  ***/
 171 SilcMessagePayload
 172 silc_message_payload_parse(unsigned char *payload,
 173                            SilcUInt32 payload_len,
 174                            SilcBool private_message,
 175                            SilcBool static_key,
 176                            SilcCipher cipher,
 177                            SilcHmac hmac);
 178
 179 /****f* silccore/SilcMessageAPI/silc_message_payload_encrypt
 180  *
 181  * SYNOPSIS
 182  *
 183  *    SilcBool silc_message_payload_encrypt(unsigned char *data,
 184  *                                          SilcUInt32 data_len,
 185  *                                          SilcUInt32 true_len,
 186  *                                          unsigned char *iv,
 187  *                                          SilcCipher cipher,
 188  *                                          SilcHmac hmac);
 189  *
 190  * DESCRIPTION
 191  *
 192  *    This function is used to encrypt the Messsage Payload which is
 193  *    the `data' and `data_len'.  The `data_len' is the data length which
 194  *    is used to create MAC out of.  The `data' MUST have additional space
 195  *    after `true_len' bytes for the MAC which is appended to the data.
 196  *
 197  *    This is usually used by the Message Payload interface itself but can
 198  *    be called by the appliation if separate encryption process is required.
 199  *    For example server might need to call this directly in some
 200  *    circumstances. The `cipher' is used to encrypt the payload and `hmac'
 201  *    to compute the MAC for the payload.
 202  *
 203  ***/
 204 SilcBool silc_message_payload_encrypt(unsigned char *data,
 205                                       SilcUInt32 data_len,
 206                                       SilcUInt32 true_len,
 207                                       unsigned char *iv,
 208                                       SilcCipher cipher,
 209                                       SilcHmac hmac);
 210
 211 /****f* silccore/SilcMessageAPI/silc_message_payload_encode
 212  *
 213  * SYNOPSIS
 214  *
 215  *    SilcBuffer silc_message_payload_encode(SilcMessageFlags flags,
 216  *                                           const unsigned char *data,
 217  *                                           SilcUInt32 data_len,
 218  *                                           SilcBool generate_iv,
 219  *                                           SilcBool private_message,
 220  *                                           SilcCipher cipher,
 221  *                                           SilcHmac hmac,
 222  *                                           SilcRng rng,
 223  *                                           SilcPublicKey public_key,
 224  *                                           SilcPrivateKey private_key,
 225  *                                           SilcHash hash,
 226  *                                           SilcBuffer buffer);
 227  *
 228  * DESCRIPTION
 229  *
 230  *    Encodes a Message Payload into a buffer and returns it.  This is
 231  *    used to encode channel messages and private messages into a packet.
 232  *    If `private_message' is FALSE then this encodes channel message, if
 233  *    it is TRUE this encodes private message.  If `private_message' is
 234  *    TRUE then `generate_iv' MUST be FALSE if the private message key
 235  *    `cipher' is not static key (pre-shared key).  If it is static key
 236  *    then protocol dictates that IV must be present in the Message Payload
 237  *    and `generate_iv' must be TRUE.  The caller must know whether the key
 238  *    is static or not for private messages.  If the key was generated with
 239  *    Key Agreement protocol then `generate_iv' is always FALSE.  For
 240  *    channel messages `generate_iv' is always set to TRUE value.
 241  *
 242  *    The `cipher' is the cipher used to encrypt the message and `hmac'
 243  *    is used to compute the MAC for the payload.  If encoding private
 244  *    message that will be encrypted with session keys (no private message
 245  *    key) then `cipher' and `hmac' is NULL and this merely encodes the
 246  *    payload buffer, and the caller must encrypt the packet later.
 247  *    If `rng' is NULL then global RNG is used, if non-NULL then the
 248  *    `rng' is used (for IV and padding generation).
 249  *
 250  *    The `public_key', `private_key' and `hash' are provided only if the
 251  *    flags includes SILC_MESSAGE_FLAG_SIGNED, in which case the message
 252  *    will be digitally signed.  If `public_key' is non-NULL then it will
 253  *    be included in the message.  The `private_message' and `hash' MUST
 254  *    be provided.  The `hash' SHOULD be SHA1.
 255  *
 256  *    If the `buffer' is non-NULL then the payload will be encoded into
 257  *    that buffer.  The same buffer is returned.  Otherwise new buffer is
 258  *    allocated and returned.  The `buffer' will be automatically enlarged
 259  *    if the payload does not fit to it.
 260  *
 261  ***/
 262 SilcBuffer silc_message_payload_encode(SilcMessageFlags flags,
 263                                        const unsigned char *data,
 264                                        SilcUInt32 data_len,
 265                                        SilcBool generate_iv,
 266                                        SilcBool private_message,
 267                                        SilcCipher cipher,
 268                                        SilcHmac hmac,
 269                                        SilcRng rng,
 270                                        SilcPublicKey public_key,
 271                                        SilcPrivateKey private_key,
 272                                        SilcHash hash,
 273                                        SilcBuffer buffer);
 274
 275 /****f* silccore/SilcMessageAPI/silc_message_payload_free
 276  *
 277  * SYNOPSIS
 278  *
 279  *    void silc_message_payload_free(SilcMessagePayload payload);
 280  *
 281  * DESCRIPTION
 282  *
 283  *    Free's Message Payload and all data in it.
 284  *
 285  ***/
 286 void silc_message_payload_free(SilcMessagePayload payload);
 287
 288 /****f* silccore/SilcMessageAPI/silc_message_get_flags
 289  *
 290  * SYNOPSIS
 291  *
 292  *    SilcMessageFlags silc_message_get_flags(SilcMessagePayload payload);
 293  *
 294  * DESCRIPTION
 295  *
 296  *    Returns the message flags from the payload.
 297  *
 298  ***/
 299 SilcMessageFlags silc_message_get_flags(SilcMessagePayload payload);
 300
 301 /****f* silccore/SilcMessageAPI/silc_message_get_data
 302  *
 303  * SYNOPSIS
 304  *
 305  *    unsigned char *
 306  *    silc_message_get_data(SilcMessagePayload payload,
 307  *                                  SilcUInt32 *data_len);
 308  *
 309  * DESCRIPTION
 310  *
 311  *    Return the data in the payload, that is, the actual message data.
 312  *    The caller must not free it.
 313  *
 314  ***/
 315 unsigned char *silc_message_get_data(SilcMessagePayload payload,
 316                                      SilcUInt32 *data_len);
 317
 318 /****f* silccore/SilcMessageAPI/silc_message_get_mac
 319  *
 320  * SYNOPSIS
 321  *
 322  *    unsigned char *
 323  *    silc_message_get_mac(SilcMessagePayload payload);
 324  *
 325  * DESCRIPTION
 326  *
 327  *    Return the MAC of the payload. The caller must already know the
 328  *    length of the MAC. The caller must not free the MAC.
 329  *
 330  ***/
 331 unsigned char *silc_message_get_mac(SilcMessagePayload payload);
 332
 333 /****f* silccore/SilcMessageAPI/silc_message_get_iv
 334  *
 335  * SYNOPSIS
 336  *
 337  *    unsigned char *
 338  *    silc_message_get_iv(SilcMessagePayload payload);
 339  *
 340  * DESCRIPTION
 341  *
 342  *    Return the IV of the payload. The caller must already know the
 343  *    length of the IV. The caller must not free the IV.
 344  *
 345  ***/
 346 unsigned char *silc_message_get_iv(SilcMessagePayload payload);
 347
 348 /****f* silccore/SilcMessageAPI/silc_message_get_signature
 349  *
 350  * SYNOPSIS
 351  *
 352  *    SilcMessageSignedPayload
 353  *    silc_message_get_signature(SilcMessagePayload payload);
 354  *
 355  * DESCRIPTION
 356  *
 357  *    Returns the pointer to the signature of the message if the
 358  *    SILC_MESSAGE_FLAG_SIGNED was set.  If the flag is set and this
 359  *    function returns NULL then error had occurred and the signature
 360  *    could not be retrieved from the message.
 361  *
 362  *    The caller SHOULD verify the signature by calling the
 363  *    silc_message_signed_verify function.  Caller must not free the
 364  *    returned payload pointer.
 365  *
 366  ***/
 367 SilcMessageSignedPayload
 368 silc_message_get_signature(SilcMessagePayload payload);
 369
 370 /****f* silccore/SilcMessageAPI/silc_message_signed_payload_parse
 371  *
 372  * SYNOPSIS
 373  *
 374  *    SilcMessageSignedPayload
 375  *    silc_message_signed_payload_parse(const unsigned char *data,
 376  *                                      SilcUInt32 data_len);
 377  *
 378  * DESCRIPTION
 379  *
 380  *    Parses the SilcMessageSignedPayload Payload from the `data' of
 381  *    length of `data_len' bytes.  The `data' must be payload without
 382  *    the actual message payload.  Returns the parsed payload or NULL
 383  *    on error.  Caller must free the returned payload.  Application
 384  *    usually does not need to call this since the function
 385  *    silc_message_payload_parse calls this automatically for signed
 386  *    messages.
 387  *
 388  ***/
 389 SilcMessageSignedPayload
 390 silc_message_signed_payload_parse(const unsigned char *data,
 391                                   SilcUInt32 data_len);
 392
 393 /****f* silccore/SilcMessageAPI/silc_message_signed_payload_encode
 394  *
 395  * SYNOPSIS
 396  *
 397  *    SilcBuffer
 398  *    silc_message_signed_payload_encode(const unsigned char *message_payload,
 399  *                                       SilcUInt32 message_payload_len,
 400  *                                       SilcPublicKey public_key,
 401  *                                       SilcPrivateKey private_key,
 402  *                                       SilcHash hash);
 403  *
 404  * DESCRIPTION
 405  *
 406  *    Encodes the SilcMessageSignedPayload Payload and computes the
 407  *    digital signature.  The `message_payload' is the message data that
 408  *    is used in the signature computation.  The encoding of the buffer
 409  *    is specified in the SILC protocol.  If `public_key' is provided
 410  *    then the public key included in the payload.  The `private_key'
 411  *    is used to produce the signature.  This function returns the encoded
 412  *    payload with the signature or NULL on error.  Caller must free the
 413  *    returned buffer.  The `hash' SHOULD be SHA-1 hash function.
 414  *
 415  *    Application usually does not need to call this since the function
 416  *    silc_message_payload_encode calls this automatically if the caller
 417  *    wants to sign the message.
 418  *
 419  ***/
 420 SilcBuffer
 421 silc_message_signed_payload_encode(const unsigned char *message_payload,
 422                                    SilcUInt32 message_payload_len,
 423                                    SilcPublicKey public_key,
 424                                    SilcPrivateKey private_key,
 425                                    SilcHash hash);
 426
 427 /****f* silccore/SilcMessageAPI/silc_message_signed_payload_free
 428  *
 429  * SYNOPSIS
 430  *
 431  *    void silc_message_signed_payload_free(SilcMessageSignedPayload sig);
 432  *
 433  * DESCRIPTION
 434  *
 435  *    Frees the SilcMessageSignedPayload Payload.
 436  *
 437  ***/
 438 void silc_message_signed_payload_free(SilcMessageSignedPayload sig);
 439
 440 /****f* silccore/SilcMessageAPI/silc_message_signed_verify
 441  *
 442  * SYNOPSIS
 443  *
 444  *    int silc_message_signed_verify(SilcMessageSignedPayload sig,
 445  *                                   SilcMessagePayload message,
 446  *                                   SilcPublicKey remote_public_key,
 447  *                                   SilcHash hash);
 448  *
 449  * DESCRIPTION
 450  *
 451  *    This routine can be used to verify the signature found in
 452  *    SilcMessageSignedPayload Payload.  This returns SILC_AUTH_OK if the
 453  *    signature verification was successful.
 454  *
 455  ***/
 456 int silc_message_signed_verify(SilcMessageSignedPayload sig,
 457                                SilcMessagePayload message,
 458                                SilcPublicKey remote_public_key,
 459                                SilcHash hash);
 460
 461 /****f* silccore/SilcMessageAPI/silc_message_signed_get_public_key
 462  *
 463  * SYNOPSIS
 464  *
 465  *    SilcPublicKey
 466  *    silc_message_signed_get_public_key(SilcMessageSignedPayload sig,
 467  *                                       const unsigned char **pk_data,
 468  *                                       SilcUInt32 *pk_data_len);
 469  *
 470  * DESCRIPTION
 471  *
 472  *    Returns the decoded SilcPublicKey from the SilcMessageSignedPayload
 473  *    Payload or NULL if it does not include public key.  The caller must
 474  *    free the returned public key pointer.  This also returns the raw
 475  *    public key (before decoding) into `pk_data' and `pk_data_len' if
 476  *    they are provided.  The caller must not free these pointers.
 477  *
 478  ***/
 479 SilcPublicKey
 480 silc_message_signed_get_public_key(SilcMessageSignedPayload sig,
 481                                    const unsigned char **pk_data,
 482                                    SilcUInt32 *pk_data_len);
 483
 484 #endif /* SILCMESSAGE_H */