1 /* 2 3 silcmessage.h 4 5 Author: Pekka Riikonen <priikone@silcnet.org> 6 7 Copyright (C) 1997 - 2014 Pekka Riikonen 8 9 The contents of this file are subject to one of the Licenses specified 10 in the COPYING file; You may not use this file except in compliance 11 with the License. 12 13 The software distributed under the License is distributed on an "AS IS" 14 basis, in the hope that it will be useful, but WITHOUT WARRANTY OF ANY 15 KIND, either expressed or implied. See the COPYING file for more 16 information. 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. 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 28 * this interface. 29 * 30 ***/ 31 32 #ifndef SILCMESSAGE_H 33 #define SILCMESSAGE_H 34 35 /****s* silccore/SilcMessageAPI/SilcMessagePayload 36 * 37 * NAME 38 * 39 * typedef struct SilcMessagePayloadObject 40 * *SilcMessagePayload, SilcMessagePayloadStruct; 41 * 42 * 43 * DESCRIPTION 44 * 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. 49 * 50 ***/ 51 typedef struct SilcMessagePayloadObject 52 *SilcMessagePayload, SilcMessagePayloadStruct; 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_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 */ 85 /***/ 86 87 /****f* silccore/SilcMessageAPI/silc_message_payload_decrypt 88 * 89 * SYNOPSIS 90 * 91 * SilcBool silc_message_payload_decrypt(unsigned char *data, 92 * size_t data_len, 93 * SilcBool private_message, 94 * SilcBool static_key, 95 * SilcCipher cipher, 96 * SilcHmac hmac, 97 * unsigned char *sender_id, 98 * SilcUInt32 sender_id_len, 99 * unsigned char *receiver_id, 100 * SilcUInt32 receiver_id_len, 101 * SilcBool check_mac); 102 * 103 * DESCRIPTION 104 * 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. 112 * 113 * The `sender_id' and `receiver_id' are the IDs from the packet header 114 * of the packet where this message payload was received. 115 * 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. 121 * 122 ***/ 123 SilcBool silc_message_payload_decrypt(unsigned char *data, 124 size_t data_len, 125 SilcBool private_message, 126 SilcBool static_key, 127 SilcCipher cipher, 128 SilcHmac hmac, 129 unsigned char *sender_id, 130 SilcUInt32 sender_id_len, 131 unsigned char *receiver_id, 132 SilcUInt32 receiver_id_len, 133 SilcBool check_mac); 134 135 /****f* silccore/SilcMessageAPI/silc_message_payload_parse 136 * 137 * SYNOPSIS 138 * 139 * SilcMessagePayload 140 * silc_message_payload_parse(unsigned char *payload, 141 * SilcUInt32 payload_len, 142 * SilcBool private_message, 143 * SilcBool static_key, 144 * SilcCipher cipher, 145 * SilcHmac hmac, 146 * unsigned char *sender_id, 147 * SilcUInt32 sender_id_len, 148 * unsigned char *receiver_id, 149 * SilcUInt32 receiver_id_len, 150 * SilcStack stack, 151 * SilcBool no_allocation, 152 * SilcMessagePayload message); 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 * The `sender_id' and `receiver_id' are the IDs from the packet header 171 * of the packet where this message payload was received. 172 * 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. 180 * 181 ***/ 182 SilcMessagePayload 183 silc_message_payload_parse(unsigned char *payload, 184 SilcUInt32 payload_len, 185 SilcBool private_message, 186 SilcBool static_key, 187 SilcCipher cipher, 188 SilcHmac hmac, 189 unsigned char *sender_id, 190 SilcUInt32 sender_id_len, 191 unsigned char *receiver_id, 192 SilcUInt32 receiver_id_len, 193 SilcStack stack, 194 SilcBool no_allocation, 195 SilcMessagePayload message); 196 197 /****f* silccore/SilcMessageAPI/silc_message_payload_encrypt 198 * 199 * SYNOPSIS 200 * 201 * SilcBool silc_message_payload_encrypt(unsigned char *data, 202 * SilcUInt32 data_len, 203 * SilcUInt32 true_len, 204 * unsigned char *iv, 205 * SilcID *sender_id, 206 * SilcID *receiver_id, 207 * SilcCipher cipher, 208 * SilcHmac hmac); 209 * 210 * DESCRIPTION 211 * 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 217 * message receiver. 218 * 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. 224 * 225 ***/ 226 SilcBool silc_message_payload_encrypt(unsigned char *data, 227 SilcUInt32 data_len, 228 SilcUInt32 true_len, 229 unsigned char *iv, 230 SilcID *sender_id, 231 SilcID *receiver_id, 232 SilcCipher cipher, 233 SilcHmac hmac); 234 235 /****f* silccore/SilcMessageAPI/silc_message_payload_encode 236 * 237 * SYNOPSIS 238 * 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, 244 * SilcCipher cipher, 245 * SilcHmac hmac, 246 * SilcRng rng, 247 * SilcPublicKey public_key, 248 * SilcPrivateKey private_key, 249 * SilcHash hash, 250 * SilcID *sender_id, 251 * SilcID *receiver_id, 252 * SilcBuffer buffer); 253 * 254 * DESCRIPTION 255 * 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. 267 * 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). 275 * 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. 281 * 282 * The `sender_id' is the ID message sender and `receiver_id' is ID of 283 * message receiver. 284 * 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. 289 * 290 ***/ 291 SilcBuffer silc_message_payload_encode(SilcMessageFlags flags, 292 const unsigned char *data, 293 SilcUInt32 data_len, 294 SilcBool generate_iv, 295 SilcBool private_message, 296 SilcCipher cipher, 297 SilcHmac hmac, 298 SilcRng rng, 299 SilcPublicKey public_key, 300 SilcPrivateKey private_key, 301 SilcHash hash, 302 SilcID *sender_id, 303 SilcID *receiver_id, 304 SilcBuffer buffer); 305 306 /****f* silccore/SilcMessageAPI/silc_message_payload_free 307 * 308 * SYNOPSIS 309 * 310 * void silc_message_payload_free(SilcMessagePayload payload); 311 * 312 * DESCRIPTION 313 * 314 * Free's Message Payload and all data in it. 315 * 316 ***/ 317 void silc_message_payload_free(SilcMessagePayload payload); 318 319 /****f* silccore/SilcMessageAPI/silc_message_get_flags 320 * 321 * SYNOPSIS 322 * 323 * SilcMessageFlags silc_message_get_flags(SilcMessagePayload payload); 324 * 325 * DESCRIPTION 326 * 327 * Returns the message flags from the payload. 328 * 329 ***/ 330 SilcMessageFlags silc_message_get_flags(SilcMessagePayload payload); 331 332 /****f* silccore/SilcMessageAPI/silc_message_get_data 333 * 334 * SYNOPSIS 335 * 336 * unsigned char * 337 * silc_message_get_data(SilcMessagePayload payload, 338 * SilcUInt32 *data_len); 339 * 340 * DESCRIPTION 341 * 342 * Return the data in the payload, that is, the actual message data. 343 * The caller must not free it. 344 * 345 ***/ 346 unsigned char *silc_message_get_data(SilcMessagePayload payload, 347 SilcUInt32 *data_len); 348 349 /****f* silccore/SilcMessageAPI/silc_message_get_mac 350 * 351 * SYNOPSIS 352 * 353 * unsigned char * 354 * silc_message_get_mac(SilcMessagePayload payload); 355 * 356 * DESCRIPTION 357 * 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. 360 * 361 ***/ 362 unsigned char *silc_message_get_mac(SilcMessagePayload payload); 363 364 /****f* silccore/SilcMessageAPI/silc_message_signed_verify 365 * 366 * SYNOPSIS 367 * 368 * SilcAuthResult 369 * silc_message_signed_verify(SilcMessagePayload message, 370 * SilcPublicKey remote_public_key, 371 * SilcHash hash); 372 * 373 * DESCRIPTION 374 * 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. 379 * 380 ***/ 381 SilcAuthResult silc_message_signed_verify(SilcMessagePayload message, 382 SilcPublicKey remote_public_key, 383 SilcHash hash); 384 385 /****f* silccore/SilcMessageAPI/silc_message_signed_get_public_key 386 * 387 * SYNOPSIS 388 * 389 * SilcPublicKey 390 * silc_message_signed_get_public_key(SilcMessagePayload payload, 391 * const unsigned char **pk_data, 392 * SilcUInt32 *pk_data_len); 393 * 394 * DESCRIPTION 395 * 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. 401 * 402 ***/ 403 SilcPublicKey 404 silc_message_signed_get_public_key(SilcMessagePayload payload, 405 const unsigned char **pk_data, 406 SilcUInt32 *pk_data_len); 407 408 #include "silcmessage_i.h" 409 410 #endif /* SILCMESSAGE_H */ 411