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; version 2 of the License.
  12
  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.
  17
  18 */
  19
  20 /****h* silccore/SilcPacketAPI
  21  *
  22  * DESCRIPTION
  23  *
  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.
  28  *
  29  ***/
  30
  31 #ifndef SILCPACKET_H
  32 #define SILCPACKET_H
  33
  34 /* Default byte size of the packet. */
  35 #define SILC_PACKET_DEFAULT_SIZE SILC_SOCKET_BUF_SIZE
  36
  37 /* Header length without source and destination ID's. */
  38 #define SILC_PACKET_HEADER_LEN 10
  39
  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
  42    from the header. */
  43 #define SILC_PACKET_MIN_HEADER_LEN 16
  44
  45 /* Maximum padding length */
  46 #define SILC_PACKET_MAX_PADLEN 128
  47
  48 /* Default padding length */
  49 #define SILC_PACKET_DEFAULT_PADLEN 16
  50
  51 /* Minimum packet length */
  52 #define SILC_PACKET_MIN_LEN (SILC_PACKET_HEADER_LEN + 1)
  53
  54 /* Maximum length of ID */
  55 #define SILC_PACKET_MAX_ID_LEN 16
  56
  57 /****d* silccore/SilcPacketAPI/SilcPacketType
  58  *
  59  * NAME
  60  *
  61  *    typedef unsigned char SilcPacketType;
  62  *
  63  * DESCRIPTION
  64  *
  65  *    SILC packet type definition and all the packet types.
  66  *
  67  * SOURCE
  68  */
  69 typedef unsigned char SilcPacketType;
  70
  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 */
 100
 101 #define SILC_PACKET_PRIVATE              200     /* Private range start  */
 102 #define SILC_PACKET_MAX                  255     /* RESERVED */
 103 /***/
 104
 105 /****d* silccore/SilcPacketAPI/SilcPacketVersion
 106  *
 107  * NAME
 108  *
 109  *    typedef unsigned char SilcPacketVersion;
 110  *
 111  * DESCRIPTION
 112  *
 113  *    SILC packet version type definition.
 114  *
 115  ***/
 116 typedef unsigned char SilcPacketVersion;
 117
 118 /****d* silccore/SilcPacketAPI/SilcPacketFlags
 119  *
 120  * NAME
 121  *
 122  *    typedef unsigned char SilcPacketFlags;
 123  *
 124  * DESCRIPTION
 125  *
 126  *    SILC packet flags type definition and all the packet flags.
 127  *
 128  * SOURCE
 129  */
 130 typedef unsigned char SilcPacketFlags;
 131
 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 */
 137 /***/
 138
 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
 145 */
 146
 147 /****s* silccore/SilcPacketAPI/SilcPacketContext
 148  *
 149  * NAME
 150  *
 151  *    typedef struct { ... } SilcPacketContext;
 152  *
 153  * DESCRIPTION
 154  *
 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
 160  *    the packet.
 161  *
 162  *    Short description of the fields following:
 163  *
 164  *    SilcBuffer buffer
 165  *
 166  *      The data buffer.
 167  *
 168  *    SilcPacketType type
 169  *
 170  *      Type of the packet. Types are defined below.
 171  *
 172  *    SilcPacketFlags flags
 173  *
 174  *      Packet flags. Flags are defined above.
 175  *
 176  *    unsigned char *src_id
 177  *    uint16 src_id_len
 178  *    unsigned char src_id_type
 179  *
 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.
 182  *
 183  *    unsigned char *dst_id;
 184  *    uint16 dst_id_len;
 185  *    unsigned char src_id_type;
 186  *
 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.
 189  *
 190  *    uint16 truelen
 191  *    uint16 padlen
 192  *
 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
 196  *      the values.
 197  *
 198  *    int users;
 199  *
 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.
 204  *
 205  *    uint32 sequence;
 206  *
 207  *      Packet sequence number.
 208  *
 209  ***/
 210 typedef struct {
 211   SilcBuffer buffer;
 212
 213   uint16 truelen;
 214   SilcPacketFlags flags;
 215   SilcPacketType type;
 216   uint8 padlen;
 217
 218   unsigned char *src_id;
 219   uint8 src_id_len;
 220   uint8 src_id_type;
 221
 222   unsigned char *dst_id;
 223   uint8 dst_id_len;
 224   uint8 dst_id_type;
 225
 226   /* Back pointers */
 227   void *context;
 228   SilcSocketConnection sock;
 229
 230   int users;
 231   bool long_pad;                /* Set to TRUE to use maximum padding
 232                                    in packet (up to 256 bytes). */
 233
 234   uint32 sequence;
 235 } SilcPacketContext;
 236
 237 /****s* silccore/SilcPacketAPI/SilcPacketParserContext
 238  *
 239  * NAME
 240  *
 241  *    typedef struct { ... } SilcPacketParserContext;
 242  *
 243  * DESCRIPTION
 244  *
 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.
 250  *
 251  *    Following description of the fields:
 252  *
 253  *    SilcPacketContext *packet
 254  *
 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.
 258  *
 259  *    bool normal
 260  *
 261  *      Indicates whether the received packet is normal or special packet.
 262  *      If special the parsing process is special also.
 263  *
 264  *    SilcSocketConnection sock
 265  *
 266  *      The associated connection.
 267  *
 268  *    void *context
 269  *
 270  *      User context that is sent to the silc_packet_receive_process
 271  *      function. This usually includes application and connection specific
 272  *      data.
 273  *
 274  ***/
 275 typedef struct {
 276   SilcPacketContext *packet;
 277   bool normal;
 278   SilcSocketConnection sock;
 279   void *context;
 280 } SilcPacketParserContext;
 281
 282 /****f* silccore/SilcPacketAPI/SilcPacketParserCallback
 283  *
 284  * SYNOPSIS
 285  *
 286  *    typedef void (*SilcPacketParserCallback)(SilcPacketParserContext
 287  *                                             *parse_context);
 288  *
 289  * DESCRIPTION
 290  *
 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
 297  *    must free it.
 298  *
 299  ***/
 300 typedef void (*SilcPacketParserCallback)(SilcPacketParserContext
 301                                          *parse_context, void *context);
 302
 303 /* Macros */
 304
 305 /****d* silccore/SilcPacketAPI/SILC_PACKET_LENGTH
 306  *
 307  * NAME
 308  *
 309  *    #define SILC_PACKET_LENGTH ...
 310  *
 311  * DESCRIPTION
 312  *
 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
 315  *    well if needed.
 316  *
 317  * SOURCE
 318  */
 319 #define SILC_PACKET_LENGTH(__packet, __ret_truelen, __ret_paddedlen)    \
 320 do {                                                                    \
 321   SILC_GET16_MSB((__ret_truelen), (__packet)->data);                    \
 322   (__ret_paddedlen) = (__ret_truelen) + (__packet)->data[4];            \
 323 } while(0)
 324 /***/
 325
 326 /****d* silccore/SilcPacketAPI/SILC_PACKET_PADLEN
 327  *
 328  * NAME
 329  *
 330  *    #define SILC_PACKET_PADLEN ...
 331  *
 332  * DESCRIPTION
 333  *
 334  *    Returns the length of the padding in the packet. This is used
 335  *    by various library routines to determine needed padding length.
 336  *
 337  * SOURCE
 338  */
 339 #define SILC_PACKET_PADLEN(__packetlen, __blocklen)             \
 340   SILC_PACKET_DEFAULT_PADLEN - (__packetlen) %                  \
 341     ((__blocklen) ? (__blocklen) : SILC_PACKET_DEFAULT_PADLEN)
 342 /***/
 343
 344 /****d* silccore/SilcPacketAPI/SILC_PACKET_PADLEN_MAX
 345  *
 346  * NAME
 347  *
 348  *    #define SILC_PACKET_PADLEN_MAX ...
 349  *
 350  * DESCRIPTION
 351  *
 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.
 355  *
 356  * SOURCE
 357  */
 358 #define SILC_PACKET_PADLEN_MAX(__packetlen)                             \
 359   SILC_PACKET_MAX_PADLEN - (__packetlen) % SILC_PACKET_MAX_PADLEN
 360 /***/
 361
 362 /* Prototypes */
 363
 364 /****f* silccore/SilcPacketAPI/silc_packet_send
 365  *
 366  * SYNOPSIS
 367  *
 368  *    int silc_packet_send(SilcSocketConnection sock, bool force_send);
 369  *
 370  * DESCRIPTION
 371  *
 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.
 379  *
 380  ***/
 381 int silc_packet_send(SilcSocketConnection sock, bool force_send);
 382
 383 /****f* silccore/SilcPacketAPI/silc_packet_encrypt
 384  *
 385  * SYNOPSIS
 386  *
 387  *    void silc_packet_encrypt(SilcCipher cipher, SilcHmac hmac,
 388  *                             SilcBuffer buffer, uint32 len);
 389  *
 390  * DESCRIPTION
 391  *
 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
 397  *    cannot be used.
 398  *
 399  ***/
 400 void silc_packet_encrypt(SilcCipher cipher, SilcHmac hmac, uint32 sequence,
 401                          SilcBuffer buffer, uint32 len);
 402
 403 /****f* silccore/SilcPacketAPI/silc_packet_assemble
 404  *
 405  * SYNOPSIS
 406  *
 407  *    void silc_packet_assemble(SilcPacketContext *ctx);
 408  *
 409  * DESCRIPTION
 410  *
 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.
 416  *
 417  *    The buffer sent as argument should be something like following:
 418  *
 419  *    --------------------------------------------
 420  *    | head             | data           | tail |
 421  *    --------------------------------------------
 422  *    ^                  ^
 423  *    58 bytes           x bytes
 424  *
 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:
 427  *
 428  *    --------------------------------------------
 429  *    | data                              |      |
 430  *    --------------------------------------------
 431  *    ^                                   ^
 432  *    Start of assembled packet
 433  *
 434  *    Packet construct is as follows (* = won't be encrypted):
 435  *
 436  *    n bytes       SILC Header
 437  *      2 bytes     Payload length  (*)
 438  *      1 byte      Flags
 439  *      1 byte      Packet type
 440  *      2 bytes     Source ID Length
 441  *      2 bytes     Destination ID Length
 442  *      1 byte      Source ID Type
 443  *      n bytes     Source ID
 444  *      1 byte      Destination ID Type
 445  *      n bytes     Destination ID
 446  *
 447  *    1 - 16 bytes    Padding
 448  *
 449  *    n bytes        Data payload
 450  *
 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
 453  *    the packet.
 454  *
 455  ***/
 456 void silc_packet_assemble(SilcPacketContext *ctx, SilcCipher cipher);
 457
 458 /****f* silccore/SilcPacketAPI/silc_packet_send_prepare
 459  *
 460  * SYNOPSIS
 461  *
 462  *    void silc_packet_send_prepare(SilcSocketConnection sock,
 463  *                                  uint32 header_len,
 464  *                                  uint32 padlen,
 465  *                                  uint32 data_len);
 466  *
 467  * DESCRIPTION
 468  *
 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.
 473  *
 474  ***/
 475 void silc_packet_send_prepare(SilcSocketConnection sock,
 476                               uint32 header_len,
 477                               uint32 padlen,
 478                               uint32 data_len);
 479
 480 /****f* silccore/SilcPacketAPI/silc_packet_receive
 481  *
 482  * SYNOPSIS
 483  *
 484  *    int silc_packet_receive(SilcSocketConnection sock);
 485  *
 486  * DESCRIPTION
 487  *
 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
 493  *    0.
 494  *
 495  ***/
 496 int silc_packet_receive(SilcSocketConnection sock);
 497
 498 /****f* silccore/SilcPacketAPI/silc_packet_receive_process
 499  *
 500  * SYNOPSIS
 501  *
 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);
 507  *
 508  * DESCRIPTION
 509  *
 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
 515  *    function.
 516  *
 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.
 522  *
 523  ***/
 524 void silc_packet_receive_process(SilcSocketConnection sock,
 525                                  bool local_is_router,
 526                                  SilcCipher cipher, SilcHmac hmac,
 527                                  uint32 sequence,
 528                                  SilcPacketParserCallback parser,
 529                                  void *parser_context);
 530
 531 /****f* silccore/SilcPacketAPI/silc_packet_parse
 532  *
 533  * SYNOPSIS
 534  *
 535  *    SilcPacketType silc_packet_parse(SilcPacketContext *ctx);
 536  *
 537  * DESCRIPTION
 538  *
 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.
 544  *
 545  ***/
 546 SilcPacketType silc_packet_parse(SilcPacketContext *ctx, SilcCipher cipher);
 547
 548 /****f* silccore/SilcPacketAPI/silc_packet_parse_special
 549  *
 550  * SYNOPSIS
 551  *
 552  *    SilcPacketType silc_packet_parse_special(SilcPacketContext *ctx);
 553  *
 554  * DESCRIPTION
 555  *
 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.
 561  *
 562  ***/
 563 SilcPacketType silc_packet_parse_special(SilcPacketContext *ctx,
 564                                          SilcCipher cipher);
 565
 566 /****f* silccore/SilcPacketAPI/silc_packet_context_alloc
 567  *
 568  * SYNOPSIS
 569  *
 570  *    SilcPacketContext *silc_packet_context_alloc();
 571  *
 572  * DESCRIPTION
 573  *
 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.
 577  *
 578  ***/
 579 SilcPacketContext *silc_packet_context_alloc(void);
 580
 581 /****f* silccore/SilcPacketAPI/silc_packet_context_dup
 582  *
 583  * SYNOPSIS
 584  *
 585  *    SilcPacketContext *silc_packet_context_dup(SilcPacketContext *ctx);
 586  *
 587  * DESCRIPTION
 588  *
 589  *    Duplicates the packet context. It actually does not duplicate
 590  *    any data, instead a reference counter is increased.
 591  *
 592  ***/
 593 SilcPacketContext *silc_packet_context_dup(SilcPacketContext *ctx);
 594
 595 /****f* silccore/SilcPacketAPI/silc_packet_context_free
 596  *
 597  * SYNOPSIS
 598  *
 599  *    void silc_packet_context_free(SilcPacketContext *ctx);
 600  *
 601  * DESCRIPTION
 602  *
 603  *    Frees the packet context. The context is actually freed when the
 604  *    reference counter hits zero.
 605  *
 606  ***/
 607 void silc_packet_context_free(SilcPacketContext *ctx);
 608
 609 #endif