lib/silccore/silcprivate.h

   1 /*
   2
   3   silcprivate.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 Private Message Interface
  22  *
  23  * DESCRIPTION
  24  *
  25  * Implementation of the SILC Private Message Payload that is used to
  26  * deliver private messages.
  27  *
  28  ***/
  29
  30 #ifndef SILCPRIVATE_H
  31 #define SILCPRIVATE_H
  32
  33 /****s* silccore/SilcPrivateAPI/SilcPrivateMessagePayload
  34  *
  35  * NAME
  36  *
  37  *    typedef struct SilcPrivateMessagePayloadStruct
  38  *                     *SilcPrivateMessagePayload;
  39  *
  40  *
  41  * DESCRIPTION
  42  *
  43  *    This context is the actual Private Message Payload and is allocated
  44  *    by silc_private_message_payload_parse and given as argument usually
  45  *    to all silc_private_message_* functions.  It is freed by the
  46  *    silc_private_message_payload_free function.
  47  *
  48  ***/
  49 typedef struct SilcPrivateMessagePayloadStruct *SilcPrivateMessagePayload;
  50
  51 /* Prototypes */
  52
  53 /****f* silccore/SilcPrivateAPI/silc_private_message_payload_parse
  54  *
  55  * SYNOPSIS
  56  *
  57  *    SilcPrivateMessagePayload
  58  *    silc_private_message_payload_parse(unsigned char *payload,
  59  *                                       SilcUInt32 payload_len,
  60  *                                       SilcCipher cipher,
  61  *                                       SilcHmac hmac);
  62  *
  63  * DESCRIPTION
  64  *
  65  *    Parses private message payload returning new private mesage payload
  66  *    structure. This also decrypts the message if the `cipher' is provided.
  67  *    The data integrity is checked with `hmac'.
  68  *
  69  ***/
  70 SilcPrivateMessagePayload
  71 silc_private_message_payload_parse(unsigned char *payload,
  72                                    SilcUInt32 payload_len,
  73                                    SilcCipher cipher,
  74                                    SilcHmac hmac);
  75
  76 /****f* silccore/SilcPrivateAPI/silc_private_message_payload_encode
  77  *
  78  * SYNOPSIS
  79  *
  80  *    SilcBuffer silc_private_message_payload_encode(SilcUInt16 flags,
  81  *                                                   SilcUInt16 data_len,
  82  *                                                   const unsigned char *data,
  83  *                                                   SilcCipher cipher,
  84  *                                                   SilcHmac hmac,
  85  *                                                   SilcRng rng);
  86  *
  87  * DESCRIPTION
  88  *
  89  *    Encodes private message payload into a buffer and returns it.  If
  90  *    the `cipher' is provided the packet is also encrypted here.  It is
  91  *    provided if the private message private keys are used.  If the `rng'
  92  *    is NULL then global RNG is used, if non-NULL then `rng' is used.
  93  *    The MAC for the message is computed with `hmac'.
  94  *
  95  ***/
  96 SilcBuffer silc_private_message_payload_encode(SilcUInt16 flags,
  97                                                SilcUInt16 data_len,
  98                                                const unsigned char *data,
  99                                                SilcCipher cipher,
 100                                                SilcHmac hmac,
 101                                                SilcRng rng);
 102
 103 /****f* silccore/SilcPrivateAPI/silc_private_message_payload_free
 104  *
 105  * SYNOPSIS
 106  *
 107  *    void
 108  *    silc_private_message_payload_free(SilcPrivateMessagePayload payload);
 109  *
 110  * DESCRIPTION
 111  *
 112  *    Frees Private Message Payload
 113  *
 114  ***/
 115 void silc_private_message_payload_free(SilcPrivateMessagePayload payload);
 116
 117 /****f* silccore/SilcPrivateAPI/silc_private_message_get_flags
 118  *
 119  * SYNOPSIS
 120  *
 121  *    SilcUInt16
 122  *    silc_private_message_get_flags(SilcPrivateMessagePayload payload);
 123  *
 124  * DESCRIPTION
 125  *
 126  *    Returns flags from the payload. Message flags may indicate some
 127  *    status of the message. Private message flags are equivalent to the
 128  *    channel message flags.
 129  *
 130  ***/
 131 SilcUInt16
 132 silc_private_message_get_flags(SilcPrivateMessagePayload payload);
 133
 134 /****f* silccore/SilcPrivateAPI/silc_private_message_get_message
 135  *
 136  * SYNOPSIS
 137  *
 138  *    unsigned char *
 139  *    silc_private_message_get_message(SilcPrivateMessagePayload payload,
 140  *                                     SilcUInt32 *message_len);
 141  *
 142  * DESCRIPTION
 143  *
 144  *    Returns the actual private message. The caller must not free it.
 145  *
 146  ***/
 147 unsigned char *
 148 silc_private_message_get_message(SilcPrivateMessagePayload payload,
 149                                  SilcUInt32 *message_len);
 150
 151 /****f* silccore/SilcPrivateAPI/silc_private_message_get_mac
 152  *
 153  * SYNOPSIS
 154  *
 155  *    unsigned char *
 156  *    silc_private_message_get_mac(SilcPrivateMessagePayload payload);
 157  *
 158  * DESCRIPTION
 159  *
 160  *    Returns the MAC from the payload.  The caller knows its length.
 161  *    The caller must not free it.
 162  *
 163  ***/
 164 unsigned char *
 165 silc_private_message_get_mac(SilcPrivateMessagePayload payload);
 166
 167 #endif