updates.
[silc.git] / lib / silccore / silcpacket.h
1 /*
2
3   silcpacket.h
4  
5   Author: Pekka Riikonen <priikone@silcnet.org>
6  
7   Copyright (C) 1997 - 2001 Pekka Riikonen
8  
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; either version 2 of the License, or
12   (at your option) any later version.
13  
14   This program is distributed in the hope that it will be useful,
15   but WITHOUT ANY WARRANTY; without even the implied warranty of
16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17   GNU General Public License for more details.
18
19 */
20
21 /****h* silccore/SilcPacketAPI
22  *
23  * DESCRIPTION
24  *
25  * Implementation of the packet routines for sending and receiving
26  * SILC Packets. These includes the data sending routines and data
27  * reading routines, encrypting and decrypting routines, packet assembling
28  * and packet parsing routines.
29  *
30  ***/
31
32 #ifndef SILCPACKET_H
33 #define SILCPACKET_H
34
35 /* Default byte size of the packet. */
36 #define SILC_PACKET_DEFAULT_SIZE SILC_SOCKET_BUF_SIZE
37
38 /* Header length without source and destination ID's. */
39 #define SILC_PACKET_HEADER_LEN 8 + 2
40
41 /* Minimum length of SILC Packet Header. This much is decrypted always
42    when packet is received to be able to get all the relevant data out
43    from the header. */
44 #define SILC_PACKET_MIN_HEADER_LEN 16 + 2
45
46 /* Maximum padding length */
47 #define SILC_PACKET_MAX_PADLEN 16
48
49 /* Minimum packet length */
50 #define SILC_PACKET_MIN_LEN (SILC_PACKET_HEADER_LEN + 1)
51
52 /* Maximum length of ID */
53 #define SILC_PACKET_MAX_ID_LEN 16
54
55 /****d* silccore/SilcPacketAPI/SilcPacketType
56  *
57  * NAME
58  * 
59  *    typedef unsigned char SilcPacketType;
60  *
61  * DESCRIPTION
62  *
63  *    SILC packet type definition and all the packet types.
64  *
65  * SOURCE
66  */
67 typedef unsigned char SilcPacketType;
68
69 /* SILC Packet types. */
70 #define SILC_PACKET_NONE                 0       /* NULL, never sent */
71 #define SILC_PACKET_DISCONNECT           1       /* Disconnection */
72 #define SILC_PACKET_SUCCESS              2       /* Success */
73 #define SILC_PACKET_FAILURE              3       /* Failure */
74 #define SILC_PACKET_REJECT               4       /* Rejected */
75 #define SILC_PACKET_NOTIFY               5       /* Notify message */
76 #define SILC_PACKET_ERROR                6       /* Error message */
77 #define SILC_PACKET_CHANNEL_MESSAGE      7       /* Message for channel */
78 #define SILC_PACKET_CHANNEL_KEY          8       /* Key of the channel */
79 #define SILC_PACKET_PRIVATE_MESSAGE      9       /* Private message */
80 #define SILC_PACKET_PRIVATE_MESSAGE_KEY  10      /* Private message key*/
81 #define SILC_PACKET_COMMAND              11      /* Command */
82 #define SILC_PACKET_COMMAND_REPLY        12      /* Reply to a command */
83 #define SILC_PACKET_KEY_EXCHANGE         13      /* Start of KE */
84 #define SILC_PACKET_KEY_EXCHANGE_1       14      /* KE1 */
85 #define SILC_PACKET_KEY_EXCHANGE_2       15      /* KE2 */
86 #define SILC_PACKET_CONNECTION_AUTH_REQUEST 16   /* Request of auth meth */
87 #define SILC_PACKET_CONNECTION_AUTH      17      /* Connectinon auth */
88 #define SILC_PACKET_NEW_ID               18      /* Sending new ID */
89 #define SILC_PACKET_NEW_CLIENT           19      /* Client registering */
90 #define SILC_PACKET_NEW_SERVER           20      /* Server registering */
91 #define SILC_PACKET_NEW_CHANNEL          21      /* Channel registering */
92 #define SILC_PACKET_REKEY                22      /* Re-key start */
93 #define SILC_PACKET_REKEY_DONE           23      /* Re-key done */
94 #define SILC_PACKET_HEARTBEAT            24      /* Heartbeat */
95 #define SILC_PACKET_KEY_AGREEMENT        25      /* Key Agreement request */
96 #define SILC_PACKET_RESUME_ROUTER        26      /* Backup router resume */
97 #define SILC_PACKET_FTP                  27      /* File Transfer */
98
99 #define SILC_PACKET_PRIVATE              200     /* Private range start  */
100 #define SILC_PACKET_MAX                  255     /* RESERVED */
101 /***/
102
103 /****d* silccore/SilcPacketAPI/SilcPacketVersion
104  *
105  * NAME
106  * 
107  *    typedef unsigned char SilcPacketVersion;
108  *
109  * DESCRIPTION
110  *
111  *    SILC packet version type definition.
112  *
113  ***/
114 typedef unsigned char SilcPacketVersion;
115
116 /****d* silccore/SilcPacketAPI/SilcPacketFlags
117  *
118  * NAME
119  * 
120  *    typedef unsigned char SilcPacketFlags;
121  *
122  * DESCRIPTION
123  *
124  *    SILC packet flags type definition and all the packet flags.
125  *
126  * SOURCE
127  */
128 typedef unsigned char SilcPacketFlags;
129
130 /* All defined packet flags */
131 #define SILC_PACKET_FLAG_NONE             0x00    /* No flags */
132 #define SILC_PACKET_FLAG_PRIVMSG_KEY      0x01    /* Private message key */
133 #define SILC_PACKET_FLAG_LIST             0x02    /* Packet is a list */
134 #define SILC_PACKET_FLAG_BROADCAST        0x04    /* Packet is a broadcast */
135 /***/
136
137 /* Rest of flags still available
138 #define SILC_PACKET_FLAG_XXX              0x08
139 #define SILC_PACKET_FLAG_XXX              0x10
140 #define SILC_PACKET_FLAG_XXX              0x20
141 #define SILC_PACKET_FLAG_XXX              0x40
142 #define SILC_PACKET_FLAG_XXX              0x80
143 */
144
145 /****s* silccore/SilcPacketAPI/SilcPacketContext
146  *
147  * NAME
148  * 
149  *    typedef struct { ... } SilcPacketContext;
150  *
151  * DESCRIPTION
152  *
153  *    In packet sending this is filled and sent to silc_packet_assemble 
154  *    which then uses it to assemble new packet. In packet reception pointer 
155  *    to this context is sent to silc_packet_parse which parses the packet 
156  *    and returns the relevant information to this structure. On packet 
157  *    reception returned ID's are always the hash values of the ID's from 
158  *    the packet. 
159  *
160  *    Short description of the fields following:
161  *
162  *    SilcBuffer buffer
163  *
164  *      The data buffer.
165  *
166  *    SilcPacketType type
167  *
168  *      Type of the packet. Types are defined below.
169  *
170  *    SilcPacketFlags flags
171  *
172  *      Packet flags. Flags are defined above.
173  *
174  *    unsigned char *src_id
175  *    uint16 src_id_len
176  *    unsigned char src_id_type
177  *
178  *      Source ID, its length and type. On packet reception retuned ID's
179  *      are always the hash values of the ID's from the packet.
180  *
181  *    unsigned char *dst_id;
182  *    uint16 dst_id_len;
183  *    unsigned char src_id_type;
184  *
185  *      Destination ID, its length and type. On packet reception retuned
186  *      ID's are always the hash values of the ID's from the packet.
187  *
188  *    uint16 truelen
189  *    uint16 padlen
190  *
191  *      The true lenght of the packet and the padded length of the packet.
192  *      These may be set by the caller before calling any of the 
193  *      silc_packet_* routines. If not provided the library will calculate
194  *      the values.
195  *
196  *    int users;
197  *
198  *      Reference counter for this context. The context is freed only 
199  *      after the reference counter hits zero. The counter is added
200  *      calling silc_packet_context_dup and decreased by calling the
201  *      silc_packet_context_free.
202  *
203  *    uint32 sequence;
204  *
205  *      Packet sequence number.
206  *
207  ***/
208 typedef struct {
209   SilcBuffer buffer;
210   SilcPacketType type;
211   SilcPacketFlags flags;
212
213   unsigned char *src_id;
214   uint16 src_id_len;
215   unsigned char src_id_type;
216
217   unsigned char *dst_id;
218   uint16 dst_id_len;
219   unsigned char dst_id_type;
220
221   uint16 truelen;
222   uint16 padlen;
223
224   /* Back pointers */
225   void *context;
226   SilcSocketConnection sock;
227
228   int users;
229
230   uint32 sequence;
231 } SilcPacketContext;
232
233 /****s* silccore/SilcPacketAPI/SilcPacketParserContext
234  *
235  * NAME
236  * 
237  *    typedef struct { ... } SilcPacketParserContext;
238  *
239  * DESCRIPTION
240  *
241  *    This context is used in packet reception when silc_packet_receive_process
242  *    function calls parser callback that performs the actual packet decryption
243  *    and parsing. This context is sent as argument to the parser function.
244  *    This context must be free'd by the parser callback function.
245  *
246  *    Following description of the fields:
247  *
248  *    SilcPacketContext *packet
249  *
250  *      The actual packet received from the network. In this phase the
251  *      context is not parsed, only the packet->buffer is allocated and
252  *      it includes the raw packet data, which is encrypted.
253  *
254  *    SilcSocketConnection sock
255  *
256  *      The associated connection.
257  *
258  *    void *context
259  *
260  *      User context that is sent to the silc_packet_receive_process
261  *      function. This usually includes application and connection specific
262  *      data.
263  *
264  ***/
265 typedef struct {
266   SilcPacketContext *packet;
267   SilcSocketConnection sock;
268   void *context;
269 } SilcPacketParserContext;
270
271 /****f* silccore/SilcPacketAPI/SilcPacketParserCallback
272  *
273  * SYNOPSIS
274  *
275  *    typedef void (*SilcPacketParserCallback)(SilcPacketParserContext 
276  *                                             *parse_context);
277  *
278  * DESCRIPTION
279  *
280  *    This callback is given to the silc_packet_receive_process function.
281  *    The callback is called by the library every time a packet is
282  *    received from the network. After the packet has been decrypted
283  *    and at least partially parsed it is passed to the application
284  *    for further parsing using this callback and the SilcPacketParserContext
285  *    context. The application receiving the SilcPacketParserContext
286  *    must free it.
287  *
288  ***/
289 typedef void (*SilcPacketParserCallback)(SilcPacketParserContext 
290                                          *parse_context);
291
292 /****f* silccore/SilcPacketAPI/SilcPacketCheckDecrypt
293  *
294  * SYNOPSIS
295  *
296  *    typedef int (*SilcPacketCheckDecrypt)(SilcPacketType packet_type,
297  *                                          SilcBuffer buffer,
298  *                                          SilcPacketContext *packet,
299  *                                          void *context);
300  *
301  * DESCRIPTION
302  *
303  *    This callback function relates to the checking whether the packet is
304  *    normal packet or special packet and how it should be processed.  If
305  *    the callback returns TRUE the packet is normal and FALSE if the packet
306  *    is special and requires special procesing. Some of the packets in
307  *    SILC are special (like channel message packets that are encrypted
308  *    using channel specific keys) and requires special processing. That
309  *    is the reason for this callback function.
310  *
311  *    The library will call this function if provided for the
312  *    silc_packet_decrypt function. The `packet_type' is the type of
313  *    packet received (this is also actually the first time application
314  *    receives information of the received packet, next time it receives
315  *    it is when the SilcPacketParserCallback function is called),
316  *    the `buffer' is the raw packet data the `packet' the allocated
317  *    SilcPacketContext that is filled when parsing the packet and `context'
318  *    is application specific user context.
319  *
320  ***/
321 typedef int (*SilcPacketCheckDecrypt)(SilcPacketType packet_type,
322                                       SilcBuffer buffer,
323                                       SilcPacketContext *packet,
324                                       void *context);
325
326 /* Macros */
327
328 /****d* silccore/SilcPacketAPI/SILC_PACKET_LENGTH
329  *
330  * NAME
331  * 
332  *    #define SILC_PACKET_LENGTH ...
333  *
334  * DESCRIPTION
335  *
336  *    Returns true length of the packet and padded length of the packet.
337  *    This is primarily used by the libary in packet parsing phase but
338  *    the application may use it as well if needed.
339  *
340  * SOURCE
341  */
342 #define SILC_PACKET_LENGTH(__packet, __ret_truelen, __ret_padlen)            \
343 do {                                                                         \
344   SILC_GET16_MSB((__ret_truelen), (__packet)->data);                         \
345   (__ret_padlen) = (((__ret_truelen) - 2) +                                  \
346                     SILC_PACKET_MAX_PADLEN) & ~(SILC_PACKET_MAX_PADLEN - 1); \
347 } while(0)
348 /***/
349
350 /****d* silccore/SilcPacketAPI/SILC_PACKET_PADLEN
351  *
352  * NAME
353  * 
354  *    #define SILC_PACKET_PADLEN ...
355  *
356  * DESCRIPTION
357  *
358  *    Returns the length of the padding in the packet. This is used
359  *    by various library routines to determine needed padding length.
360  *
361  * SOURCE
362  */
363 #define SILC_PACKET_PADLEN(__packetlen)                                  \
364   SILC_PACKET_MAX_PADLEN - ((__packetlen) - 2) % SILC_PACKET_MAX_PADLEN;
365 /***/
366
367 /* Prototypes */
368
369 /****f* silccore/SilcPacketAPI/silc_packet_send
370  *
371  * SYNOPSIS
372  *
373  *    int silc_packet_send(SilcSocketConnection sock, int force_send);
374  *
375  * DESCRIPTION
376  *
377  *    Actually sends the packet. This flushes the connections outgoing data
378  *    buffer. If data is sent directly to the network this returns the bytes
379  *    written, if error occured this returns -1 and if the data could not
380  *    be written directly to the network at this time this returns -2, in
381  *    which case the data should be queued by the caller and sent at some
382  *    later time. If `force_send' is TRUE this attempts to write the data
383  *    directly to the network, if FALSE, this returns -2.
384  *
385  ***/
386 int silc_packet_send(SilcSocketConnection sock, int force_send);
387
388 /****f* silccore/SilcPacketAPI/silc_packet_encrypt
389  *
390  * SYNOPSIS
391  *
392  *    void silc_packet_encrypt(SilcCipher cipher, SilcHmac hmac, 
393  *                             SilcBuffer buffer, uint32 len);
394  *
395  * DESCRIPTION
396  *
397  *    Encrypts a packet. This also creates HMAC of the packet before 
398  *    encryption and adds the HMAC at the end of the buffer. This assumes
399  *    that there is enough free space at the end of the buffer to add the
400  *    computed HMAC. This is the normal way of encrypting packets, if some
401  *    other process of HMAC computing and encryption is needed this function
402  *    cannot be used. 
403  *
404  ***/
405 void silc_packet_encrypt(SilcCipher cipher, SilcHmac hmac, 
406                          SilcBuffer buffer, uint32 len);
407
408 /****f* silccore/SilcPacketAPI/silc_packet_assemble
409  *
410  * SYNOPSIS
411  *
412  *    void silc_packet_assemble(SilcPacketContext *ctx);
413  *
414  * DESCRIPTION
415  *
416  *    Assembles a new packet to be ready for send out. The buffer sent as
417  *    argument must include the data to be sent and it must not be encrypted. 
418  *    The packet also must have enough free space so that the SILC header
419  *    and padding maybe added to the packet. The packet is encrypted after 
420  *    this function has returned.
421  *
422  *    The buffer sent as argument should be something like following:
423  *
424  *    --------------------------------------------
425  *    | head             | data           | tail |
426  *    --------------------------------------------
427  *    ^                  ^
428  *    58 bytes           x bytes
429  *
430  *    So that the SILC header and 1 - 16 bytes of padding can fit to
431  *    the buffer. After assembly the buffer might look like this:
432  *
433  *    --------------------------------------------
434  *    | data                              |      |
435  *    --------------------------------------------
436  *    ^                                   ^
437  *    Start of assembled packet
438  *
439  *    Packet construct is as follows (* = won't be encrypted):
440  *
441  *    n bytes       SILC Header
442  *      2 bytes     Payload length  (*)
443  *      1 byte      Flags
444  *      1 byte      Packet type
445  *      2 bytes     Source ID Length
446  *      2 bytes     Destination ID Length
447  *      1 byte      Source ID Type
448  *      n bytes     Source ID
449  *      1 byte      Destination ID Type
450  *      n bytes     Destination ID
451  *
452  *    1 - 16 bytes    Padding
453  *
454  *    n bytes        Data payload
455  *
456  *    All fields in the packet will be authenticated by MAC. The MAC is
457  *    not computed here, it must be computed separately before encrypting
458  *    the packet.
459  *
460  ***/
461 void silc_packet_assemble(SilcPacketContext *ctx);
462
463 /****f* silccore/SilcPacketAPI/silc_packet_send_prepare
464  *
465  * SYNOPSIS
466  *
467  *    void silc_packet_send_prepare(SilcSocketConnection sock,
468  *                                  uint32 header_len,
469  *                                  uint32 padlen,
470  *                                  uint32 data_len);
471  *
472  * DESCRIPTION
473  *
474  *    Prepare outgoing data buffer for packet sending. This moves the data
475  *    area so that new packet may be added into it. If needed this allocates
476  *    more space to the buffer. This handles directly the connection's
477  *    outgoing buffer in SilcSocketConnection object.
478  *
479  ***/
480 void silc_packet_send_prepare(SilcSocketConnection sock,
481                               uint32 header_len,
482                               uint32 padlen,
483                               uint32 data_len);
484
485 /****f* silccore/SilcPacketAPI/silc_packet_receive
486  *
487  * SYNOPSIS
488  *
489  *    int silc_packet_receive(SilcSocketConnection sock);
490  *
491  * DESCRIPTION
492  *
493  *    Receives packet from network and reads the data into connection's
494  *    incoming data buffer. If the data was read directly this returns the
495  *    read bytes, if error occured this returns -1, if the data could not
496  *    be read directly at this time this returns -2 in which case the data
497  *    should be read again at some later time, or If EOF occured this returns
498  *    0.
499  *
500  ***/
501 int silc_packet_receive(SilcSocketConnection sock);
502
503 /****f* silccore/SilcPacketAPI/silc_packet_decrypt
504  *
505  * SYNOPSIS
506  *
507  *    int silc_packet_decrypt(SilcCipher cipher, SilcHmac hmac,
508  *                            SilcBuffer buffer, SilcPacketContext *packet,
509  *                            SilcPacketCheckDecrypt check_packet,
510  *                            void *context);
511  *
512  * DESCRIPTION
513  *
514  *    Decrypts a packet. This assumes that typical SILC packet is the
515  *    packet to be decrypted and thus checks for normal and special SILC
516  *    packets and can handle both of them. This also computes and checks
517  *    the HMAC of the packet. If any other special or customized decryption
518  *    processing is required this function cannot be used. This returns
519  *    -1 on error, 0 when packet is normal packet and 1 when the packet
520  *    is special and requires special processing. 
521  *
522  *    The `check_packet' is a callback funtion that this function will 
523  *    call.  The callback relates to the checking whether the packet is
524  *    normal packet or special packet and how it should be processed.  If
525  *    the callback return TRUE the packet is normal and FALSE if the packet
526  *    is special and requires special procesing.
527  *
528  ***/
529 int silc_packet_decrypt(SilcCipher cipher, SilcHmac hmac,
530                         SilcBuffer buffer, SilcPacketContext *packet,
531                         SilcPacketCheckDecrypt check_packet,
532                         void *context);
533
534 /****f* silccore/SilcPacketAPI/silc_packet_receive_process
535  *
536  * SYNOPSIS
537  *
538  *    void silc_packet_receive_process(SilcSocketConnection sock,
539  *                                     SilcCipher cipher, SilcHmac hmac,
540  *                                     SilcPacketParserCallback parser,
541  *                                     void *context);
542  *
543  * DESCRIPTION
544  *
545  *    Processes the received data. This checks the received data and 
546  *    calls parser callback that handles the actual packet decryption
547  *    and parsing. If more than one packet was received this calls the
548  *    parser multiple times. The parser callback will get context
549  *    SilcPacketParserContext that includes the packet and the `context'
550  *    sent to this function.
551  *
552  ***/
553 void silc_packet_receive_process(SilcSocketConnection sock,
554                                  SilcCipher cipher, SilcHmac hmac,
555                                  SilcPacketParserCallback parser,
556                                  void *context);
557
558 /****f* silccore/SilcPacketAPI/silc_packet_parse
559  *
560  * SYNOPSIS
561  *
562  *    SilcPacketType silc_packet_parse(SilcPacketContext *ctx);
563  *
564  * DESCRIPTION
565  *
566  *    Parses the packet. This is called when a whole packet is ready to be
567  *    parsed. The buffer sent must be already decrypted before calling this 
568  *    function. The len argument must be the true length of the packet. This 
569  *    function returns the type of the packet. The data section of the 
570  *    buffer is parsed, not head or tail sections.
571  *
572  ***/
573 SilcPacketType silc_packet_parse(SilcPacketContext *ctx);
574
575 /****f* silccore/SilcPacketAPI/silc_packet_parse_special
576  *
577  * SYNOPSIS
578  *
579  *    SilcPacketType silc_packet_parse_special(SilcPacketContext *ctx);
580  *
581  * DESCRIPTION
582  *
583  *    Perform special SILC Packet header parsing. This is required to some
584  *    packet types that have the data payload encrypted with different key
585  *    than the header area plus padding of the packet. Hence, this parses
586  *    the header in a way that it does not take the data area into account
587  *    and parses the header and padding area only.
588  *
589  ***/
590 SilcPacketType silc_packet_parse_special(SilcPacketContext *ctx);
591
592 /****f* silccore/SilcPacketAPI/silc_packet_context_alloc
593  *
594  * SYNOPSIS
595  *
596  *    SilcPacketContext *silc_packet_context_alloc();
597  *
598  * DESCRIPTION
599  *
600  *    Allocates a packet context. Packet contexts are used when 
601  *    packets are assembled and parsed. The context is freed by the
602  *    silc_packet_context_free function.
603  *
604  ***/
605 SilcPacketContext *silc_packet_context_alloc(void);
606
607 /****f* silccore/SilcPacketAPI/silc_packet_context_dup
608  *
609  * SYNOPSIS
610  *
611  *    SilcPacketContext *silc_packet_context_dup(SilcPacketContext *ctx);
612  *
613  * DESCRIPTION
614  *
615  *    Duplicates the packet context. It actually does not duplicate
616  *    any data, instead a reference counter is increased.
617  *
618  ***/
619 SilcPacketContext *silc_packet_context_dup(SilcPacketContext *ctx);
620
621 /****f* silccore/SilcPacketAPI/silc_packet_context_free
622  *
623  * SYNOPSIS
624  *
625  *    void silc_packet_context_free(SilcPacketContext *ctx);
626  *
627  * DESCRIPTION
628  *
629  *    Frees the packet context. The context is actually freed when the
630  *    reference counter hits zero.
631  *
632  ***/
633 void silc_packet_context_free(SilcPacketContext *ctx);
634
635 #endif