5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1997 - 2001 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/SilcPacketAPI
24 * Implementation of the packet routines for sending and receiving
25 * SILC Packets. These includes the data sending routines and data
26 * reading routines, encrypting and decrypting routines, packet assembling
27 * and packet parsing routines.
34 /* Default byte size of the packet. */
35 #define SILC_PACKET_DEFAULT_SIZE SILC_SOCKET_BUF_SIZE
37 /* Header length without source and destination ID's. */
38 #define SILC_PACKET_HEADER_LEN 10
40 /* Minimum length of SILC Packet Header. This much is decrypted always
41 when packet is received to be able to get all the relevant data out
43 #define SILC_PACKET_MIN_HEADER_LEN 16
45 /* Maximum padding length */
46 #define SILC_PACKET_MAX_PADLEN 128
48 /* Default padding length */
49 #define SILC_PACKET_DEFAULT_PADLEN 16
51 /* Minimum packet length */
52 #define SILC_PACKET_MIN_LEN (SILC_PACKET_HEADER_LEN + 1)
54 /* Maximum length of ID */
55 #define SILC_PACKET_MAX_ID_LEN 16
57 /****d* silccore/SilcPacketAPI/SilcPacketType
61 * typedef unsigned char SilcPacketType;
65 * SILC packet type definition and all the packet types.
69 typedef unsigned char SilcPacketType;
71 /* SILC Packet types. */
72 #define SILC_PACKET_NONE 0 /* NULL, never sent */
73 #define SILC_PACKET_DISCONNECT 1 /* Disconnection */
74 #define SILC_PACKET_SUCCESS 2 /* Success */
75 #define SILC_PACKET_FAILURE 3 /* Failure */
76 #define SILC_PACKET_REJECT 4 /* Rejected */
77 #define SILC_PACKET_NOTIFY 5 /* Notify message */
78 #define SILC_PACKET_ERROR 6 /* Error message */
79 #define SILC_PACKET_CHANNEL_MESSAGE 7 /* Message for channel */
80 #define SILC_PACKET_CHANNEL_KEY 8 /* Key of the channel */
81 #define SILC_PACKET_PRIVATE_MESSAGE 9 /* Private message */
82 #define SILC_PACKET_PRIVATE_MESSAGE_KEY 10 /* Private message key*/
83 #define SILC_PACKET_COMMAND 11 /* Command */
84 #define SILC_PACKET_COMMAND_REPLY 12 /* Reply to a command */
85 #define SILC_PACKET_KEY_EXCHANGE 13 /* Start of KE */
86 #define SILC_PACKET_KEY_EXCHANGE_1 14 /* KE1 */
87 #define SILC_PACKET_KEY_EXCHANGE_2 15 /* KE2 */
88 #define SILC_PACKET_CONNECTION_AUTH_REQUEST 16 /* Request of auth meth */
89 #define SILC_PACKET_CONNECTION_AUTH 17 /* Connectinon auth */
90 #define SILC_PACKET_NEW_ID 18 /* Sending new ID */
91 #define SILC_PACKET_NEW_CLIENT 19 /* Client registering */
92 #define SILC_PACKET_NEW_SERVER 20 /* Server registering */
93 #define SILC_PACKET_NEW_CHANNEL 21 /* Channel registering */
94 #define SILC_PACKET_REKEY 22 /* Re-key start */
95 #define SILC_PACKET_REKEY_DONE 23 /* Re-key done */
96 #define SILC_PACKET_HEARTBEAT 24 /* Heartbeat */
97 #define SILC_PACKET_KEY_AGREEMENT 25 /* Key Agreement request */
98 #define SILC_PACKET_RESUME_ROUTER 26 /* Backup router resume */
99 #define SILC_PACKET_FTP 27 /* File Transfer */
101 #define SILC_PACKET_PRIVATE 200 /* Private range start */
102 #define SILC_PACKET_MAX 255 /* RESERVED */
105 /****d* silccore/SilcPacketAPI/SilcPacketVersion
109 * typedef unsigned char SilcPacketVersion;
113 * SILC packet version type definition.
116 typedef unsigned char SilcPacketVersion;
118 /****d* silccore/SilcPacketAPI/SilcPacketFlags
122 * typedef unsigned char SilcPacketFlags;
126 * SILC packet flags type definition and all the packet flags.
130 typedef unsigned char SilcPacketFlags;
132 /* All defined packet flags */
133 #define SILC_PACKET_FLAG_NONE 0x00 /* No flags */
134 #define SILC_PACKET_FLAG_PRIVMSG_KEY 0x01 /* Private message key */
135 #define SILC_PACKET_FLAG_LIST 0x02 /* Packet is a list */
136 #define SILC_PACKET_FLAG_BROADCAST 0x04 /* Packet is a broadcast */
139 /* Rest of flags still available
140 #define SILC_PACKET_FLAG_XXX 0x08
141 #define SILC_PACKET_FLAG_XXX 0x10
142 #define SILC_PACKET_FLAG_XXX 0x20
143 #define SILC_PACKET_FLAG_XXX 0x40
144 #define SILC_PACKET_FLAG_XXX 0x80
147 /****s* silccore/SilcPacketAPI/SilcPacketContext
151 * typedef struct { ... } SilcPacketContext;
155 * In packet sending this is filled and sent to silc_packet_assemble
156 * which then uses it to assemble new packet. In packet reception pointer
157 * to this context is sent to silc_packet_parse which parses the packet
158 * and returns the relevant information to this structure. On packet
159 * reception returned ID's are always the hash values of the ID's from
162 * Short description of the fields following:
168 * SilcPacketType type
170 * Type of the packet. Types are defined below.
172 * SilcPacketFlags flags
174 * Packet flags. Flags are defined above.
176 * unsigned char *src_id
178 * unsigned char src_id_type
180 * Source ID, its length and type. On packet reception retuned ID's
181 * are always the hash values of the ID's from the packet.
183 * unsigned char *dst_id;
185 * unsigned char src_id_type;
187 * Destination ID, its length and type. On packet reception retuned
188 * ID's are always the hash values of the ID's from the packet.
193 * The true lenght of the packet and the padded length of the packet.
194 * These may be set by the caller before calling any of the
195 * silc_packet_* routines. If not provided the library will calculate
200 * Reference counter for this context. The context is freed only
201 * after the reference counter hits zero. The counter is added
202 * calling silc_packet_context_dup and decreased by calling the
203 * silc_packet_context_free.
207 * Packet sequence number.
214 SilcPacketFlags flags;
218 unsigned char *src_id;
222 unsigned char *dst_id;
228 SilcSocketConnection sock;
231 bool long_pad; /* Set to TRUE to use maximum padding
232 in packet (up to 256 bytes). */
237 /****s* silccore/SilcPacketAPI/SilcPacketParserContext
241 * typedef struct { ... } SilcPacketParserContext;
245 * This context is used in packet reception when the function
246 * silc_packet_receive_process calls parser callback that performs
247 * the actual packet decryption and parsing. This context is sent as
248 * argument to the parser function. This context must be free'd by
249 * the parser callback function.
251 * Following description of the fields:
253 * SilcPacketContext *packet
255 * The actual packet received from the network. In this phase the
256 * context is not parsed, only the packet->buffer is allocated and
257 * it includes the raw packet data, which is encrypted.
261 * Indicates whether the received packet is normal or special packet.
262 * If special the parsing process is special also.
264 * SilcSocketConnection sock
266 * The associated connection.
270 * User context that is sent to the silc_packet_receive_process
271 * function. This usually includes application and connection specific
276 SilcPacketContext *packet;
278 SilcSocketConnection sock;
280 } SilcPacketParserContext;
282 /****f* silccore/SilcPacketAPI/SilcPacketParserCallback
286 * typedef void (*SilcPacketParserCallback)(SilcPacketParserContext
291 * This callback is given to the silc_packet_receive_process function.
292 * The callback is called by the library every time a packet is
293 * received from the network. After the packet has been decrypted
294 * and at least partially parsed it is passed to the application
295 * for further parsing using this callback and the SilcPacketParserContext
296 * context. The application receiving the SilcPacketParserContext
300 typedef void (*SilcPacketParserCallback)(SilcPacketParserContext
301 *parse_context, void *context);
305 /****d* silccore/SilcPacketAPI/SILC_PACKET_LENGTH
309 * #define SILC_PACKET_LENGTH ...
313 * Returns true length of the packet. This is primarily used by the
314 * libary in packet parsing phase but the application may use it as
319 #define SILC_PACKET_LENGTH(__packet, __ret_truelen, __ret_paddedlen) \
321 SILC_GET16_MSB((__ret_truelen), (__packet)->data); \
322 (__ret_paddedlen) = (__ret_truelen) + (__packet)->data[4]; \
326 /****d* silccore/SilcPacketAPI/SILC_PACKET_PADLEN
330 * #define SILC_PACKET_PADLEN ...
334 * Returns the length of the padding in the packet. This is used
335 * by various library routines to determine needed padding length.
339 #define SILC_PACKET_PADLEN(__packetlen, __blocklen) \
340 SILC_PACKET_DEFAULT_PADLEN - (__packetlen) % \
341 ((__blocklen) ? (__blocklen) : SILC_PACKET_DEFAULT_PADLEN)
344 /****d* silccore/SilcPacketAPI/SILC_PACKET_PADLEN_MAX
348 * #define SILC_PACKET_PADLEN_MAX ...
352 * Returns the length of the padding up to the maximum length, which
353 * is 128 butes. This is used by various library routines to determine
354 * needed padding length.
358 #define SILC_PACKET_PADLEN_MAX(__packetlen) \
359 SILC_PACKET_MAX_PADLEN - (__packetlen) % SILC_PACKET_MAX_PADLEN
364 /****f* silccore/SilcPacketAPI/silc_packet_send
368 * int silc_packet_send(SilcSocketConnection sock, bool force_send);
372 * Actually sends the packet. This flushes the connections outgoing data
373 * buffer. If data is sent directly to the network this returns the bytes
374 * written, if error occured this returns -1 and if the data could not
375 * be written directly to the network at this time this returns -2, in
376 * which case the data should be queued by the caller and sent at some
377 * later time. If `force_send' is TRUE this attempts to write the data
378 * directly to the network, if FALSE, this returns -2.
381 int silc_packet_send(SilcSocketConnection sock, bool force_send);
383 /****f* silccore/SilcPacketAPI/silc_packet_encrypt
387 * void silc_packet_encrypt(SilcCipher cipher, SilcHmac hmac,
388 * SilcBuffer buffer, uint32 len);
392 * Encrypts a packet. This also creates HMAC of the packet before
393 * encryption and adds the HMAC at the end of the buffer. This assumes
394 * that there is enough free space at the end of the buffer to add the
395 * computed HMAC. This is the normal way of encrypting packets, if some
396 * other process of HMAC computing and encryption is needed this function
400 void silc_packet_encrypt(SilcCipher cipher, SilcHmac hmac, uint32 sequence,
401 SilcBuffer buffer, uint32 len);
403 /****f* silccore/SilcPacketAPI/silc_packet_assemble
407 * void silc_packet_assemble(SilcPacketContext *ctx);
411 * Assembles a new packet to be ready for send out. The buffer sent as
412 * argument must include the data to be sent and it must not be encrypted.
413 * The packet also must have enough free space so that the SILC header
414 * and padding maybe added to the packet. The packet is encrypted after
415 * this function has returned.
417 * The buffer sent as argument should be something like following:
419 * --------------------------------------------
420 * | head | data | tail |
421 * --------------------------------------------
425 * So that the SILC header and 1 - 16 bytes of padding can fit to
426 * the buffer. After assembly the buffer might look like this:
428 * --------------------------------------------
430 * --------------------------------------------
432 * Start of assembled packet
434 * Packet construct is as follows (* = won't be encrypted):
436 * n bytes SILC Header
437 * 2 bytes Payload length (*)
440 * 2 bytes Source ID Length
441 * 2 bytes Destination ID Length
442 * 1 byte Source ID Type
444 * 1 byte Destination ID Type
445 * n bytes Destination ID
447 * 1 - 16 bytes Padding
449 * n bytes Data payload
451 * All fields in the packet will be authenticated by MAC. The MAC is
452 * not computed here, it must be computed separately before encrypting
456 void silc_packet_assemble(SilcPacketContext *ctx, SilcCipher cipher);
458 /****f* silccore/SilcPacketAPI/silc_packet_send_prepare
462 * void silc_packet_send_prepare(SilcSocketConnection sock,
469 * Prepare outgoing data buffer for packet sending. This moves the data
470 * area so that new packet may be added into it. If needed this allocates
471 * more space to the buffer. This handles directly the connection's
472 * outgoing buffer in SilcSocketConnection object.
475 void silc_packet_send_prepare(SilcSocketConnection sock,
480 /****f* silccore/SilcPacketAPI/silc_packet_receive
484 * int silc_packet_receive(SilcSocketConnection sock);
488 * Receives packet from network and reads the data into connection's
489 * incoming data buffer. If the data was read directly this returns the
490 * read bytes, if error occured this returns -1, if the data could not
491 * be read directly at this time this returns -2 in which case the data
492 * should be read again at some later time, or If EOF occured this returns
496 int silc_packet_receive(SilcSocketConnection sock);
498 /****f* silccore/SilcPacketAPI/silc_packet_receive_process
502 * void silc_packet_receive_process(SilcSocketConnection sock,
503 * bool local_is_router,
504 * SilcCipher cipher, SilcHmac hmac,
505 * SilcPacketParserCallback parser,
506 * void *parser_context);
510 * Processes and decrypts the incmoing data, and calls parser callback
511 * for each received packet that will handle the actual packet parsing.
512 * If more than one packet was received this calls the parser multiple
513 * times. The parser callback will get context SilcPacketParserContext
514 * that includes the packet and the `parser_context' sent to this
517 * The `local_is_router' indicates whether the caller is router server
518 * in which case the receiving process of a certain packet types may
519 * be special. Normal server and client must set it to FALSE. The
520 * SilcPacketParserContext will indicate also whether the received
521 * packet was normal or special packet.
524 void silc_packet_receive_process(SilcSocketConnection sock,
525 bool local_is_router,
526 SilcCipher cipher, SilcHmac hmac,
528 SilcPacketParserCallback parser,
529 void *parser_context);
531 /****f* silccore/SilcPacketAPI/silc_packet_parse
535 * SilcPacketType silc_packet_parse(SilcPacketContext *ctx);
539 * Parses the packet. This is called when a whole packet is ready to be
540 * parsed. The buffer sent must be already decrypted before calling this
541 * function. The len argument must be the true length of the packet. This
542 * function returns the type of the packet. The data section of the
543 * buffer is parsed, not head or tail sections.
546 SilcPacketType silc_packet_parse(SilcPacketContext *ctx, SilcCipher cipher);
548 /****f* silccore/SilcPacketAPI/silc_packet_parse_special
552 * SilcPacketType silc_packet_parse_special(SilcPacketContext *ctx);
556 * Perform special SILC Packet header parsing. This is required to some
557 * packet types that have the data payload encrypted with different key
558 * than the header area plus padding of the packet. Hence, this parses
559 * the header in a way that it does not take the data area into account
560 * and parses the header and padding area only.
563 SilcPacketType silc_packet_parse_special(SilcPacketContext *ctx,
566 /****f* silccore/SilcPacketAPI/silc_packet_context_alloc
570 * SilcPacketContext *silc_packet_context_alloc();
574 * Allocates a packet context. Packet contexts are used when
575 * packets are assembled and parsed. The context is freed by the
576 * silc_packet_context_free function.
579 SilcPacketContext *silc_packet_context_alloc(void);
581 /****f* silccore/SilcPacketAPI/silc_packet_context_dup
585 * SilcPacketContext *silc_packet_context_dup(SilcPacketContext *ctx);
589 * Duplicates the packet context. It actually does not duplicate
590 * any data, instead a reference counter is increased.
593 SilcPacketContext *silc_packet_context_dup(SilcPacketContext *ctx);
595 /****f* silccore/SilcPacketAPI/silc_packet_context_free
599 * void silc_packet_context_free(SilcPacketContext *ctx);
603 * Frees the packet context. The context is actually freed when the
604 * reference counter hits zero.
607 void silc_packet_context_free(SilcPacketContext *ctx);