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/Packet Protocol Interface
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 packet length */
55 #define SILC_PACKET_MAX_LEN 0xffff
57 /* Maximum length of ID */
58 #define SILC_PACKET_MAX_ID_LEN 28
60 /****d* silccore/SilcPacketAPI/SilcPacketType
64 * typedef SilcUInt8 SilcPacketType;
68 * SILC packet type definition and all the packet types.
72 typedef SilcUInt8 SilcPacketType;
74 /* SILC Packet types. */
75 #define SILC_PACKET_NONE 0 /* NULL, never sent */
76 #define SILC_PACKET_DISCONNECT 1 /* Disconnection */
77 #define SILC_PACKET_SUCCESS 2 /* Success */
78 #define SILC_PACKET_FAILURE 3 /* Failure */
79 #define SILC_PACKET_REJECT 4 /* Rejected */
80 #define SILC_PACKET_NOTIFY 5 /* Notify message */
81 #define SILC_PACKET_ERROR 6 /* Error message */
82 #define SILC_PACKET_CHANNEL_MESSAGE 7 /* Message for channel */
83 #define SILC_PACKET_CHANNEL_KEY 8 /* Key of the channel */
84 #define SILC_PACKET_PRIVATE_MESSAGE 9 /* Private message */
85 #define SILC_PACKET_PRIVATE_MESSAGE_KEY 10 /* Private message key*/
86 #define SILC_PACKET_COMMAND 11 /* Command */
87 #define SILC_PACKET_COMMAND_REPLY 12 /* Reply to a command */
88 #define SILC_PACKET_KEY_EXCHANGE 13 /* Start of KE */
89 #define SILC_PACKET_KEY_EXCHANGE_1 14 /* KE1 */
90 #define SILC_PACKET_KEY_EXCHANGE_2 15 /* KE2 */
91 #define SILC_PACKET_CONNECTION_AUTH_REQUEST 16 /* Request of auth meth */
92 #define SILC_PACKET_CONNECTION_AUTH 17 /* Connectinon auth */
93 #define SILC_PACKET_NEW_ID 18 /* Sending new ID */
94 #define SILC_PACKET_NEW_CLIENT 19 /* Client registering */
95 #define SILC_PACKET_NEW_SERVER 20 /* Server registering */
96 #define SILC_PACKET_NEW_CHANNEL 21 /* Channel registering */
97 #define SILC_PACKET_REKEY 22 /* Re-key start */
98 #define SILC_PACKET_REKEY_DONE 23 /* Re-key done */
99 #define SILC_PACKET_HEARTBEAT 24 /* Heartbeat */
100 #define SILC_PACKET_KEY_AGREEMENT 25 /* Key Agreement request */
101 #define SILC_PACKET_RESUME_ROUTER 26 /* Backup router resume */
102 #define SILC_PACKET_FTP 27 /* File Transfer */
103 #define SILC_PACKET_RESUME_CLIENT 28 /* Client resume */
105 #define SILC_PACKET_PRIVATE 200 /* Private range start */
106 #define SILC_PACKET_MAX 255 /* RESERVED */
109 /****d* silccore/SilcPacketAPI/SilcPacketVersion
113 * typedef SilcUInt8 SilcPacketVersion;
117 * SILC packet version type definition.
120 typedef SilcUInt8 SilcPacketVersion;
122 /****d* silccore/SilcPacketAPI/SilcPacketFlags
126 * typedef SilcUInt8 SilcPacketFlags;
130 * SILC packet flags type definition and all the packet flags.
134 typedef SilcUInt8 SilcPacketFlags;
136 /* All defined packet flags */
137 #define SILC_PACKET_FLAG_NONE 0x00 /* No flags */
138 #define SILC_PACKET_FLAG_PRIVMSG_KEY 0x01 /* Private message key */
139 #define SILC_PACKET_FLAG_LIST 0x02 /* Packet is a list */
140 #define SILC_PACKET_FLAG_BROADCAST 0x04 /* Packet is a broadcast */
141 #define SILC_PACKET_FLAG_COMPRESSED 0x08 /* Payload is compressed */
144 /* Rest of flags still available
145 #define SILC_PACKET_FLAG_XXX 0x10
146 #define SILC_PACKET_FLAG_XXX 0x20
147 #define SILC_PACKET_FLAG_XXX 0x40
148 #define SILC_PACKET_FLAG_XXX 0x80
151 /****s* silccore/SilcPacketAPI/SilcPacketContext
155 * typedef struct { ... } SilcPacketContext;
159 * In packet sending this is filled and sent to silc_packet_assemble
160 * which then uses it to assemble new packet. In packet reception pointer
161 * to this context is sent to silc_packet_parse which parses the packet
162 * and returns the relevant information to this structure. On packet
163 * reception returned ID's are always the hash values of the ID's from
166 * Short description of the fields following:
170 * True length of the packet. This may be set by the caller before
171 * calling any of the silc_packet_* routines. If not provided the
172 * library will calculate the values.
174 * SilcPacketFlags flags
176 * Packet flags. Flags are defined above.
178 * SilcPacketType type
180 * Type of the packet. Types are defined below.
182 * unsigned char *src_id
183 * SilcUInt8 src_id_len
184 * SilcUInt8 src_id_type
186 * Source ID, its length and type. On packet reception retuned ID's
187 * are always the hash values of the ID's from the packet.
189 * unsigned char *dst_id;
190 * SilcUInt8 dst_id_len;
191 * SilcUInt8 src_id_type;
193 * Destination ID, its length and type. On packet reception retuned
194 * ID's are always the hash values of the ID's from the packet.
198 * If set to TRUE the packet will include the maximum padding allowed
199 * in SILC packet, which is 128 bytes. If FALSE only the amount of
200 * padding needed will be applied.
204 * Reference counter for this context. The context is freed only
205 * after the reference counter hits zero. The counter is added
206 * calling silc_packet_context_dup and decreased by calling the
207 * silc_packet_context_free.
211 * The padded length of the packet. This may be set by the caller
212 * before calling any of the silc_packet_* routines. If not provided
213 * the library will calculate the values.
215 * SilcUInt32 sequence;
217 * Packet sequence number. Set only when this context is a parsed
222 * The actual packet data. Set only when this context is a parsed
228 SilcPacketFlags flags;
231 unsigned char *src_id;
232 unsigned char *dst_id;
233 unsigned int src_id_len : 5;
234 unsigned int src_id_type : 2;
235 unsigned int dst_id_len : 5;
236 unsigned int dst_id_type : 2;
237 unsigned int long_pad : 1; /* Set when maximum padding in packet */
238 unsigned int users : 9; /* Reference counter */
239 unsigned int padlen : 8;
245 /****s* silccore/SilcPacketAPI/SilcPacketParserContext
249 * typedef struct { ... } SilcPacketParserContext;
253 * This context is used in packet reception when the function
254 * silc_packet_receive_process calls parser callback that performs
255 * the actual packet decryption and parsing. This context is sent as
256 * argument to the parser function. This context must be free'd by
257 * the parser callback function.
259 * Following description of the fields:
261 * SilcPacketContext *packet
263 * The actual packet received from the network. In this phase the
264 * context is not parsed, only the packet->buffer is allocated and
265 * it includes the raw packet data, which is encrypted.
269 * Indicates whether the received packet is normal or special packet.
270 * If special the parsing process is special also.
272 * SilcSocketConnection sock
274 * The associated connection.
278 * User context that is sent to the silc_packet_receive_process
279 * function. This usually includes application and connection specific
284 SilcPacketContext *packet;
286 SilcSocketConnection sock;
288 } SilcPacketParserContext;
290 /****f* silccore/SilcPacketAPI/SilcPacketParserCallback
294 * typedef bool (*SilcPacketParserCallback)(SilcPacketParserContext
299 * This callback is given to the silc_packet_receive_process function.
300 * The callback is called by the library every time a packet is
301 * received from the network. After the packet has been decrypted
302 * and at least partially parsed it is passed to the application
303 * for further parsing using this callback and the SilcPacketParserContext
304 * context. The application receiving the SilcPacketParserContext
307 * This returns TRUE if the library should continue packet processing
308 * (assuming there is more data to be processed), and FALSE if the
309 * upper layer does not want the library to continue but to leave the
310 * rest of the data is the packet queue untouched. Application may
311 * want to do this for example if the cipher is not ready before
312 * processing a certain packet. In this case the application wants
313 * to recall the processing function with the correct cipher.
316 typedef bool (*SilcPacketParserCallback)(SilcPacketParserContext
317 *parse_context, void *context);
321 /****d* silccore/SilcPacketAPI/SILC_PACKET_LENGTH
325 * #define SILC_PACKET_LENGTH ...
329 * Returns true length of the packet. This is primarily used by the
330 * libary in packet parsing phase but the application may use it as
335 #define SILC_PACKET_LENGTH(__packetdata, __ret_truelen, __ret_paddedlen) \
337 SILC_GET16_MSB((__ret_truelen), (__packetdata)); \
338 (__ret_paddedlen) = (__ret_truelen) + (__packetdata)[4]; \
342 /****d* silccore/SilcPacketAPI/SILC_PACKET_DATALEN
346 * #define SILC_PACKET_DATALEN ...
350 * Calculates the data length with given header length. This macro
351 * can be used to check whether the data_len with header_len exceeds
352 * SILC_PACKET_MAX_LEN. If it does, this returns the new data_len
353 * so that the SILC_PACKET_MAX_LEN is not exceeded. If the data_len
354 * plus header_len fits SILC_PACKET_MAX_LEN the returned data length
355 * is the data_len given as argument. This macro can be used when
360 #define SILC_PACKET_DATALEN(data_len, header_len) \
361 ((data_len + header_len) > SILC_PACKET_MAX_LEN ? \
362 data_len - ((data_len + header_len) - SILC_PACKET_MAX_LEN) : data_len)
365 /****d* silccore/SilcPacketAPI/SILC_PACKET_PADLEN
369 * #define SILC_PACKET_PADLEN ...
373 * Calculates the length of the padding in the packet. This is used
374 * by various library routines to determine needed padding length.
378 #define SILC_PACKET_PADLEN(__packetlen, __blocklen, __padlen) \
380 __padlen = (SILC_PACKET_DEFAULT_PADLEN - (__packetlen) % \
381 ((__blocklen) ? (__blocklen) : SILC_PACKET_DEFAULT_PADLEN)); \
383 __padlen += ((__blocklen) ? (__blocklen) : SILC_PACKET_DEFAULT_PADLEN); \
387 /****d* silccore/SilcPacketAPI/SILC_PACKET_PADLEN_MAX
391 * #define SILC_PACKET_PADLEN_MAX ...
395 * Returns the length of the padding up to the maximum length, which
396 * is 128 bytes. This is used by various library routines to determine
397 * needed padding length.
401 #define SILC_PACKET_PADLEN_MAX(__packetlen, __blocklen, __padlen) \
403 __padlen = (SILC_PACKET_MAX_PADLEN - (__packetlen) % \
404 ((__blocklen) ? (__blocklen) : SILC_PACKET_DEFAULT_PADLEN)); \
410 /****f* silccore/SilcPacketAPI/silc_packet_send
414 * int silc_packet_send(SilcSocketConnection sock, bool force_send);
418 * Actually sends the packet. This flushes the connections outgoing data
419 * buffer. If data is sent directly to the network this returns the bytes
420 * written, if error occured this returns -1 and if the data could not
421 * be written directly to the network at this time this returns -2, in
422 * which case the data should be queued by the caller and sent at some
423 * later time. If `force_send' is TRUE this attempts to write the data
424 * directly to the network, if FALSE, this returns -2.
427 int silc_packet_send(SilcSocketConnection sock, bool force_send);
429 /****f* silccore/SilcPacketAPI/silc_packet_encrypt
433 * void silc_packet_encrypt(SilcCipher cipher, SilcHmac hmac,
434 * SilcBuffer buffer, SilcUInt32 len);
438 * Encrypts a packet. This also creates HMAC of the packet before
439 * encryption and adds the HMAC at the end of the buffer. This assumes
440 * that there is enough free space at the end of the buffer to add the
441 * computed HMAC. This is the normal way of encrypting packets, if some
442 * other process of HMAC computing and encryption is needed this function
446 void silc_packet_encrypt(SilcCipher cipher, SilcHmac hmac, SilcUInt32 sequence,
447 SilcBuffer buffer, SilcUInt32 len);
449 /****f* silccore/SilcPacketAPI/silc_packet_assemble
453 * bool silc_packet_assemble(SilcPacketContext *packet, SilcRng rng,
454 * SilcCipher cipher, SilcHmac hmac,
455 * SilcSocketConnection sock,
456 * const unsigned char *data, SilcUInt32 data_len,
457 * const SilcBuffer assembled_packet);
461 * Assembles new packet to be ready for encrypting and sending out.
462 * The `packet' is filled by caller to include the packet header specific
463 * values. This prepares the socket connection's `sock' outoing buffer
464 * for sending data, and returns the assembled packet to the
465 * `assembled_packet' pointer sent by the caller. The `assembled_packet'
466 * is a reference to the socket connection's outgoing buffer. The
467 * returned packet can be encrypted, and then sent to network by calling
468 * silc_packet_send function. The `assembled_packet' may be freely
469 * modified (like encrypted etc.) but it must not be freed, since it is
470 * reference from `sock' outgoing buffer, and it is const.
473 bool silc_packet_assemble(SilcPacketContext *packet, SilcRng rng,
474 SilcCipher cipher, SilcHmac hmac,
475 SilcSocketConnection sock,
476 const unsigned char *data, SilcUInt32 data_len,
477 const SilcBuffer assembled_packet);
479 /****f* silccore/SilcPacketAPI/silc_packet_send_prepare
483 * bool silc_packet_send_prepare(SilcSocketConnection sock,
484 * SilcUInt32 header_len,
485 * SilcUInt32 pad_len,
486 * SilcUInt32 data_len,
488 * const SilcBuffer packet);
492 * This function can be used to prepare the outgoing data buffer in
493 * the socket connection specified by `sock' for packet sending.
494 * This is used internally by packet sending routines, but application
495 * may call this if it doesn't call silc_packet_assemble function.
496 * If that function is called then application must not call this since
497 * that function calls this internally.
499 * This returns the prepared data area into the `packet' pointer provided
500 * caller, which can be used then to add data to it, and later encrypt
501 * it. The `packet' includes reference to the socket connection's
502 * outgoing buffer. The `packet' may be freely modified (like
503 * encrypted etc.) but it must not be freed, since it is reference from
504 * `sock' outgoing buffer, and it is const.
507 bool silc_packet_send_prepare(SilcSocketConnection sock,
508 SilcUInt32 header_len,
512 const SilcBuffer packet);
514 /****f* silccore/SilcPacketAPI/silc_packet_receive
518 * int silc_packet_receive(SilcSocketConnection sock);
522 * Receives packet from network and reads the data into connection's
523 * incoming data buffer. If the data was read directly this returns the
524 * read bytes, if error occured this returns -1, if the data could not
525 * be read directly at this time this returns -2 in which case the data
526 * should be read again at some later time, or If EOF occured this returns
530 int silc_packet_receive(SilcSocketConnection sock);
532 /****f* silccore/SilcPacketAPI/silc_packet_receive_process
536 * bool silc_packet_receive_process(SilcSocketConnection sock,
537 * bool local_is_router,
538 * SilcCipher cipher, SilcHmac hmac,
539 * SilcPacketParserCallback parser,
540 * void *parser_context);
544 * Processes and decrypts the incoming data, and calls parser callback
545 * for each received packet that will handle the actual packet parsing.
546 * If more than one packet was received this calls the parser multiple
547 * times. The parser callback will get context SilcPacketParserContext
548 * that includes the packet and the `parser_context' sent to this
551 * The `local_is_router' indicates whether the caller is router server
552 * in which case the receiving process of a certain packet types may
553 * be special. Normal server and client must set it to FALSE. The
554 * SilcPacketParserContext will indicate also whether the received
555 * packet was normal or special packet.
558 bool silc_packet_receive_process(SilcSocketConnection sock,
559 bool local_is_router,
560 SilcCipher cipher, SilcHmac hmac,
562 SilcPacketParserCallback parser,
563 void *parser_context);
565 /****f* silccore/SilcPacketAPI/silc_packet_parse
569 * SilcPacketType silc_packet_parse(SilcPacketContext *ctx);
573 * Parses the packet. This is called when a whole packet is ready to be
574 * parsed. The buffer sent must be already decrypted before calling this
575 * function. The len argument must be the true length of the packet. This
576 * function returns the type of the packet. The data section of the
577 * buffer is parsed, not head or tail sections.
580 SilcPacketType silc_packet_parse(SilcPacketContext *ctx, SilcCipher cipher);
582 /****f* silccore/SilcPacketAPI/silc_packet_parse_special
586 * SilcPacketType silc_packet_parse_special(SilcPacketContext *ctx);
590 * Perform special SILC Packet header parsing. This is required to some
591 * packet types that have the data payload encrypted with different key
592 * than the header area plus padding of the packet. Hence, this parses
593 * the header in a way that it does not take the data area into account
594 * and parses the header and padding area only.
597 SilcPacketType silc_packet_parse_special(SilcPacketContext *ctx,
600 /****f* silccore/SilcPacketAPI/silc_packet_context_alloc
604 * SilcPacketContext *silc_packet_context_alloc();
608 * Allocates a packet context. Packet contexts are used when
609 * packets are assembled and parsed. The context is freed by the
610 * silc_packet_context_free function.
613 SilcPacketContext *silc_packet_context_alloc(void);
615 /****f* silccore/SilcPacketAPI/silc_packet_context_dup
619 * SilcPacketContext *silc_packet_context_dup(SilcPacketContext *ctx);
623 * Duplicates the packet context. It actually does not duplicate
624 * any data, instead a reference counter is increased.
627 SilcPacketContext *silc_packet_context_dup(SilcPacketContext *ctx);
629 /****f* silccore/SilcPacketAPI/silc_packet_context_free
633 * void silc_packet_context_free(SilcPacketContext *ctx);
637 * Frees the packet context. The context is actually freed when the
638 * reference counter hits zero.
641 void silc_packet_context_free(SilcPacketContext *ctx);