5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1997 - 2014 Pekka Riikonen
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.
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.
20 /****h* silccore/SILC Message Interface
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
35 /****s* silccore/SilcMessageAPI/SilcMessagePayload
39 * typedef struct SilcMessagePayloadObject
40 * *SilcMessagePayload, SilcMessagePayloadStruct;
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.
51 typedef struct SilcMessagePayloadObject
52 *SilcMessagePayload, SilcMessagePayloadStruct;
54 /****d* silccore/SilcMessageAPI/SilcMessageFlags
58 * typedef SilcUInt16 SilcMessageFlags;
62 * The message flags type definition and the message flags. The
63 * message flags are used to indicate some status of the message.
67 typedef SilcUInt16 SilcMessageFlags;
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_PACKET 0x0800 /* Contains SILC packet */
83 #define SILC_MESSAGE_FLAG_RESERVED 0x1000 /* to 0x1000 */
84 #define SILC_MESSAGE_FLAG_PRIVATE 0x2000 /* to 0x8000 */
87 /****f* silccore/SilcMessageAPI/silc_message_payload_decrypt
91 * SilcBool silc_message_payload_decrypt(unsigned char *data,
93 * SilcBool private_message,
94 * SilcBool static_key,
97 * unsigned char *sender_id,
98 * SilcUInt32 sender_id_len,
99 * unsigned char *receiver_id,
100 * SilcUInt32 receiver_id_len,
101 * SilcBool check_mac);
105 * Decrypt Message Payload indicated by `data'. If the payload is
106 * channel message then `private_message' is FALSE, and if it is
107 * private message it is TRUE. If the private message key is static
108 * (pre-shared key) then protocol dictates that the IV is present
109 * and `static_key' must be set to TRUE. If the key is not static
110 * (Key Agreement was done for the key) then it MUST be FALSE. For
111 * channel messages the `static_key' is ignored.
113 * The `sender_id' and `receiver_id' are the IDs from the packet header
114 * of the packet where this message payload was received.
116 * This is usually used by the Message Payload interface itself but can
117 * be called by the appliation if separate decryption process is required.
118 * For example server might need to call this directly in some
119 * circumstances. The `cipher' is used to decrypt the payload. If
120 * `check_mac' is FALSE then MAC is not verified.
123 SilcBool silc_message_payload_decrypt(unsigned char *data,
125 SilcBool private_message,
129 unsigned char *sender_id,
130 SilcUInt32 sender_id_len,
131 unsigned char *receiver_id,
132 SilcUInt32 receiver_id_len,
135 /****f* silccore/SilcMessageAPI/silc_message_payload_parse
140 * silc_message_payload_parse(unsigned char *payload,
141 * SilcUInt32 payload_len,
142 * SilcBool private_message,
143 * SilcBool static_key,
146 * unsigned char *sender_id,
147 * SilcUInt32 sender_id_len,
148 * unsigned char *receiver_id,
149 * SilcUInt32 receiver_id_len,
151 * SilcBool no_allocation,
152 * SilcMessagePayload message);
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.
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.
170 * The `sender_id' and `receiver_id' are the IDs from the packet header
171 * of the packet where this message payload was received.
173 * If the `message' is non-NULL then that pre-allocated context is
174 * used in parsing. Same context is returned. Otherwise new context
175 * is allocated and returned. If the `stack' is non-NULL then memory
176 * is allocated from that stack. If `no_allocation' is TRUE then the
177 * `message' must be provided and data is merely parsed and referenced
178 * from `payload' and will become invalid when `payload' invalidates.
179 * If `no_allocation' is TRUE the routine does not do any allocations.
183 silc_message_payload_parse(unsigned char *payload,
184 SilcUInt32 payload_len,
185 SilcBool private_message,
189 unsigned char *sender_id,
190 SilcUInt32 sender_id_len,
191 unsigned char *receiver_id,
192 SilcUInt32 receiver_id_len,
194 SilcBool no_allocation,
195 SilcMessagePayload message);
197 /****f* silccore/SilcMessageAPI/silc_message_payload_encrypt
201 * SilcBool silc_message_payload_encrypt(unsigned char *data,
202 * SilcUInt32 data_len,
203 * SilcUInt32 true_len,
206 * SilcID *receiver_id,
212 * This function is used to encrypt the Messsage Payload which is
213 * the `data' and `data_len'. The `data_len' is the data length which
214 * is used to create MAC out of. The `data' MUST have additional space
215 * after `true_len' bytes for the MAC which is appended to the data.
216 * The `sender_id' is the ID message sender and `receiver_id' is ID of
219 * This is usually used by the Message Payload interface itself but can
220 * be called by the appliation if separate encryption process is required.
221 * For example server might need to call this directly in some
222 * circumstances. The `cipher' is used to encrypt the payload and `hmac'
223 * to compute the MAC for the payload.
226 SilcBool silc_message_payload_encrypt(unsigned char *data,
235 /****f* silccore/SilcMessageAPI/silc_message_payload_encode
239 * SilcBuffer silc_message_payload_encode(SilcMessageFlags flags,
240 * const unsigned char *data,
241 * SilcUInt32 data_len,
242 * SilcBool generate_iv,
243 * SilcBool private_message,
247 * SilcPublicKey public_key,
248 * SilcPrivateKey private_key,
251 * SilcID *receiver_id,
252 * SilcBuffer buffer);
256 * Encodes a Message Payload into a buffer and returns it. This is
257 * used to encode channel messages and private messages into a packet.
258 * If `private_message' is FALSE then this encodes channel message, if
259 * it is TRUE this encodes private message. If `private_message' is
260 * TRUE then `generate_iv' MUST be FALSE if the private message key
261 * `cipher' is not static key (pre-shared key). If it is static key
262 * then protocol dictates that IV must be present in the Message Payload
263 * and `generate_iv' must be TRUE. The caller must know whether the key
264 * is static or not for private messages. If the key was generated with
265 * Key Agreement protocol then `generate_iv' is always FALSE. For
266 * channel messages `generate_iv' is always set to TRUE value.
268 * The `cipher' is the cipher used to encrypt the message and `hmac'
269 * is used to compute the MAC for the payload. If encoding private
270 * message that will be encrypted with session keys (no private message
271 * key) then `cipher' and `hmac' is NULL and this merely encodes the
272 * payload buffer, and the caller must encrypt the packet later.
273 * If `rng' is NULL then global RNG is used, if non-NULL then the
274 * `rng' is used (for IV and padding generation).
276 * The `public_key', `private_key' and `hash' are provided only if the
277 * flags includes SILC_MESSAGE_FLAG_SIGNED, in which case the message
278 * will be digitally signed. If `public_key' is non-NULL then it will
279 * be included in the message. The `private_message' and `hash' MUST
280 * be provided. The `hash' SHOULD be SHA1.
282 * The `sender_id' is the ID message sender and `receiver_id' is ID of
285 * If the `buffer' is non-NULL then the payload will be encoded into
286 * that buffer. The same buffer is returned. Otherwise new buffer is
287 * allocated and returned. The `buffer' will be automatically enlarged
288 * if the payload does not fit to it.
291 SilcBuffer silc_message_payload_encode(SilcMessageFlags flags,
292 const unsigned char *data,
294 SilcBool generate_iv,
295 SilcBool private_message,
299 SilcPublicKey public_key,
300 SilcPrivateKey private_key,
306 /****f* silccore/SilcMessageAPI/silc_message_payload_free
310 * void silc_message_payload_free(SilcMessagePayload payload);
314 * Free's Message Payload and all data in it.
317 void silc_message_payload_free(SilcMessagePayload payload);
319 /****f* silccore/SilcMessageAPI/silc_message_get_flags
323 * SilcMessageFlags silc_message_get_flags(SilcMessagePayload payload);
327 * Returns the message flags from the payload.
330 SilcMessageFlags silc_message_get_flags(SilcMessagePayload payload);
332 /****f* silccore/SilcMessageAPI/silc_message_get_data
337 * silc_message_get_data(SilcMessagePayload payload,
338 * SilcUInt32 *data_len);
342 * Return the data in the payload, that is, the actual message data.
343 * The caller must not free it.
346 unsigned char *silc_message_get_data(SilcMessagePayload payload,
347 SilcUInt32 *data_len);
349 /****f* silccore/SilcMessageAPI/silc_message_get_mac
354 * silc_message_get_mac(SilcMessagePayload payload);
358 * Return the MAC of the payload. The caller must already know the
359 * length of the MAC. The caller must not free the MAC.
362 unsigned char *silc_message_get_mac(SilcMessagePayload payload);
364 /****f* silccore/SilcMessageAPI/silc_message_signed_verify
369 * silc_message_signed_verify(SilcMessagePayload message,
370 * SilcPublicKey remote_public_key,
375 * This routine can be used to verify the digital signature from the
376 * message indicated by `message'. The signature is present only if
377 * the SILC_MESSAGE_FLAG_SIGNED is set in the message flags. This
378 * returns SILC_AUTH_OK if the signature verification was successful.
381 SilcAuthResult silc_message_signed_verify(SilcMessagePayload message,
382 SilcPublicKey remote_public_key,
385 /****f* silccore/SilcMessageAPI/silc_message_signed_get_public_key
390 * silc_message_signed_get_public_key(SilcMessagePayload payload,
391 * const unsigned char **pk_data,
392 * SilcUInt32 *pk_data_len);
396 * Returns the decoded SilcPublicKey from the message payload or NULL
397 * if it does not include public key. The caller must free the returned
398 * public key pointer. This also returns the raw public key (before
399 * decoding) into `pk_data' and `pk_data_len' if they are provided. The
400 * caller must not free these pointers.
404 silc_message_signed_get_public_key(SilcMessagePayload payload,
405 const unsigned char **pk_data,
406 SilcUInt32 *pk_data_len);
408 #include "silcmessage_i.h"
410 #endif /* SILCMESSAGE_H */