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