5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1997 - 2006 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.
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.
37 /****s* silccore/SilcMessageAPI/SilcMessagePayload
41 * typedef struct SilcMessagePayloadStruct *SilcMessagePayload;
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.
52 typedef struct SilcMessagePayloadStruct *SilcMessagePayload;
54 /****s* silccore/SilcMessageAPI/SilcMessageSignedPayload
58 * typedef struct SilcMessageSignedPayloadStruct *SilcMessageSignedPayload;
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.
71 typedef struct SilcMessageSignedPayloadStruct *SilcMessageSignedPayload;
73 /****d* silccore/SilcMessageAPI/SilcMessageFlags
77 * typedef SilcUInt16 SilcMessageFlags;
81 * The message flags type definition and the message flags. The
82 * message flags are used to indicate some status of the message.
86 typedef SilcUInt16 SilcMessageFlags;
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 */
105 /****f* silccore/SilcMessageAPI/silc_message_payload_decrypt
109 * SilcBool silc_message_payload_decrypt(unsigned char *data,
111 * SilcBool private_message,
112 * SilcBool static_key,
115 * SilcBool check_mac);
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.
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.
134 SilcBool silc_message_payload_decrypt(unsigned char *data,
136 SilcBool private_message,
142 /****f* silccore/SilcMessageAPI/silc_message_payload_parse
147 * silc_message_payload_parse(unsigned char *payload,
148 * SilcUInt32 payload_len,
149 * SilcBool private_message,
150 * SilcBool static_key,
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.
172 silc_message_payload_parse(unsigned char *payload,
173 SilcUInt32 payload_len,
174 SilcBool private_message,
179 /****f* silccore/SilcMessageAPI/silc_message_payload_encrypt
183 * SilcBool silc_message_payload_encrypt(unsigned char *data,
184 * SilcUInt32 data_len,
185 * SilcUInt32 true_len,
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.
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.
204 SilcBool silc_message_payload_encrypt(unsigned char *data,
211 /****f* silccore/SilcMessageAPI/silc_message_payload_encode
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,
223 * SilcPublicKey public_key,
224 * SilcPrivateKey private_key,
226 * SilcBuffer buffer);
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.
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).
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.
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.
262 SilcBuffer silc_message_payload_encode(SilcMessageFlags flags,
263 const unsigned char *data,
265 SilcBool generate_iv,
266 SilcBool private_message,
270 SilcPublicKey public_key,
271 SilcPrivateKey private_key,
275 /****f* silccore/SilcMessageAPI/silc_message_payload_free
279 * void silc_message_payload_free(SilcMessagePayload payload);
283 * Free's Message Payload and all data in it.
286 void silc_message_payload_free(SilcMessagePayload payload);
288 /****f* silccore/SilcMessageAPI/silc_message_get_flags
292 * SilcMessageFlags silc_message_get_flags(SilcMessagePayload payload);
296 * Returns the message flags from the payload.
299 SilcMessageFlags silc_message_get_flags(SilcMessagePayload payload);
301 /****f* silccore/SilcMessageAPI/silc_message_get_data
306 * silc_message_get_data(SilcMessagePayload payload,
307 * SilcUInt32 *data_len);
311 * Return the data in the payload, that is, the actual message data.
312 * The caller must not free it.
315 unsigned char *silc_message_get_data(SilcMessagePayload payload,
316 SilcUInt32 *data_len);
318 /****f* silccore/SilcMessageAPI/silc_message_get_mac
323 * silc_message_get_mac(SilcMessagePayload payload);
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.
331 unsigned char *silc_message_get_mac(SilcMessagePayload payload);
333 /****f* silccore/SilcMessageAPI/silc_message_get_iv
338 * silc_message_get_iv(SilcMessagePayload payload);
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.
346 unsigned char *silc_message_get_iv(SilcMessagePayload payload);
348 /****f* silccore/SilcMessageAPI/silc_message_get_signature
352 * SilcMessageSignedPayload
353 * silc_message_get_signature(SilcMessagePayload payload);
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.
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.
367 SilcMessageSignedPayload
368 silc_message_get_signature(SilcMessagePayload payload);
370 /****f* silccore/SilcMessageAPI/silc_message_signed_payload_parse
374 * SilcMessageSignedPayload
375 * silc_message_signed_payload_parse(const unsigned char *data,
376 * SilcUInt32 data_len);
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
389 SilcMessageSignedPayload
390 silc_message_signed_payload_parse(const unsigned char *data,
391 SilcUInt32 data_len);
393 /****f* silccore/SilcMessageAPI/silc_message_signed_payload_encode
398 * silc_message_signed_payload_encode(const unsigned char *message_payload,
399 * SilcUInt32 message_payload_len,
400 * SilcPublicKey public_key,
401 * SilcPrivateKey private_key,
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.
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.
421 silc_message_signed_payload_encode(const unsigned char *message_payload,
422 SilcUInt32 message_payload_len,
423 SilcPublicKey public_key,
424 SilcPrivateKey private_key,
427 /****f* silccore/SilcMessageAPI/silc_message_signed_payload_free
431 * void silc_message_signed_payload_free(SilcMessageSignedPayload sig);
435 * Frees the SilcMessageSignedPayload Payload.
438 void silc_message_signed_payload_free(SilcMessageSignedPayload sig);
440 /****f* silccore/SilcMessageAPI/silc_message_signed_verify
444 * int silc_message_signed_verify(SilcMessageSignedPayload sig,
445 * SilcMessagePayload message,
446 * SilcPublicKey remote_public_key,
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.
456 int silc_message_signed_verify(SilcMessageSignedPayload sig,
457 SilcMessagePayload message,
458 SilcPublicKey remote_public_key,
461 /****f* silccore/SilcMessageAPI/silc_message_signed_get_public_key
466 * silc_message_signed_get_public_key(SilcMessageSignedPayload sig,
467 * const unsigned char **pk_data,
468 * SilcUInt32 *pk_data_len);
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.
480 silc_message_signed_get_public_key(SilcMessageSignedPayload sig,
481 const unsigned char **pk_data,
482 SilcUInt32 *pk_data_len);
484 #endif /* SILCMESSAGE_H */