lib/silccore/silcid.h

   1 /*
   2
   3   silcid.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 2000 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/SilcIDAPI
  22  *
  23  * DESCRIPTION
  24  *
  25  * These are important ID types used in SILC. SILC server creates these
  26  * but SILC client has to handle these as well since these are used in
  27  * packet sending and reception. However, client never creates these
  28  * but it receives the correct ID's from server. Clients, servers and
  29  * channels are identified by the these ID's.
  30  *
  31  * The ID's are based on IP addresses. The IP address provides a good
  32  * way to distinguish the ID's from other ID's. The ID's supports both
  33  * IPv4 and IPv6.
  34  *
  35  * This file also includes the implementation of the SILC ID Payload
  36  * parsing and encoding.
  37  *
  38  ***/
  39
  40 #ifndef SILCID_H
  41 #define SILCID_H
  42
  43 /****d* silccore/SilcIDAPI/SilcIdType
  44  *
  45  * NAME
  46  *
  47  *    typedef SilcUInt16 SilcIdType;
  48  *
  49  * DESCRIPTION
  50  *
  51  *    SILC ID type definitions and the ID types.
  52  *
  53  * SOURCE
  54  */
  55 typedef SilcUInt16 SilcIdType;
  56
  57 /* The SILC ID Types */
  58 #define SILC_ID_NONE        0
  59 #define SILC_ID_SERVER      1
  60 #define SILC_ID_CLIENT      2
  61 #define SILC_ID_CHANNEL     3
  62 /***/
  63
  64 /* The ID Lenghts. These are IPv4 based and should be noted if used directly
  65    that these cannot be used with IPv6. */
  66 #define SILC_ID_SERVER_LEN      (64 / 8)
  67 #define SILC_ID_CLIENT_LEN      (128 / 8)
  68 #define SILC_ID_CHANNEL_LEN     (64 / 8)
  69
  70 #define CLIENTID_HASH_LEN       (88 / 8) /* Client ID's 88 bit MD5 hash */
  71
  72 /****s* silccore/SilcIDAPI/SilcIDPayload
  73  *
  74  * NAME
  75  *
  76  *    typedef struct SilcIDPayloadStruct *SilcIDPayload;
  77  *
  78  * DESCRIPTION
  79  *
  80  *    This context is the actual ID Payload and is allocated by
  81  *    silc_id_payload_parse and given as argument usually to all
  82  *    silc_id_payload_* functions.  It is freed by the function
  83  *    silc_id_payload_free.
  84  *
  85  ***/
  86 typedef struct SilcIDPayloadStruct *SilcIDPayload;
  87
  88 /****s* silccore/SilcIDAPI/SilcArgumentPayload
  89  *
  90  * NAME
  91  *
  92  *    typedef struct SilcArgumentPayloadStruct *SilcArgumentPayload;
  93  *
  94  * DESCRIPTION
  95  *
  96  *    This context is the actual Argument Payload and is allocated
  97  *    by silc_argument_payload_parse and given as argument usually to
  98  *    all silc_argument_payload_* functions.  It is freed by the
  99  *    silc_argument_payload_free function.
 100  *
 101  ***/
 102 typedef struct SilcArgumentPayloadStruct *SilcArgumentPayload;
 103
 104 /* Prototypes */
 105
 106 /****f* silccore/SilcIDAPI/silc_id_payload_parse
 107  *
 108  * SYNOPSIS
 109  *
 110  *    SilcIDPayload silc_id_payload_parse(const unsigned char *payload,
 111  *                                        SilcUInt32 payload_len);
 112  *
 113  * DESCRIPTION
 114  *
 115  *    Parses buffer and return ID payload into payload structure. The
 116  *    `buffer' is raw payload buffer.
 117  *
 118  ***/
 119 SilcIDPayload silc_id_payload_parse(const unsigned char *payload,
 120                                     SilcUInt32 payload_len);
 121
 122 /****f* silccore/SilcIDAPI/silc_id_payload_parse_id
 123  *
 124  * SYNOPSIS
 125  *
 126  *    void *silc_id_payload_parse_id(const unsigned char *data, SilcUInt32 len);
 127  *
 128  * DESCRIPTION
 129  *
 130  *    Return ID directly from the raw ID Payload data buffer. The
 131  *    caller must free the returned ID.
 132  *
 133  ***/
 134 void *silc_id_payload_parse_id(const unsigned char *data, SilcUInt32 len);
 135
 136 /****f* silccore/SilcIDAPI/silc_id_payload_encode
 137  *
 138  * SYNOPSIS
 139  *
 140  *    SilcBuffer silc_id_payload_encode(const void *id, SilcIdType type);
 141  *
 142  * DESCRIPTION
 143  *
 144  *    Encodes ID Payload. The `id' is the ID of the type `type' to put
 145  *    into the payload. Returns the encoded payload buffer.
 146  *
 147  ***/
 148 SilcBuffer silc_id_payload_encode(const void *id, SilcIdType type);
 149
 150 /****f* silccore/SilcIDAPI/silc_id_payload_encode_data
 151  *
 152  * SYNOPSIS
 153  *
 154  *    SilcBuffer silc_id_payload_encode_data(const unsigned char *id,
 155  *                                           uin32 id_len, SilcIdType type);
 156  *
 157  * DESCRIPTION
 158  *
 159  *    Encodes ID Payload. The `id' is raw ID data of the length of `id_len'
 160  *    of type of `type'. Returns the encoded payload buffer.
 161  *
 162  ***/
 163 SilcBuffer silc_id_payload_encode_data(const unsigned char *id,
 164                                        SilcUInt32 id_len, SilcIdType type);
 165
 166 /****f* silccore/SilcIDAPI/silc_id_payload_free
 167  *
 168  * SYNOPSIS
 169  *
 170  *    void silc_id_payload_free(SilcIDPayload payload);
 171  *
 172  * DESCRIPTION
 173  *
 174  *    Frees the ID Payload and all data in it.
 175  *
 176  ***/
 177 void silc_id_payload_free(SilcIDPayload payload);
 178
 179 /****f* silccore/SilcIDAPI/silc_id_payload_get_type
 180  *
 181  * SYNOPSIS
 182  *
 183  *    SilcIdType silc_id_payload_get_type(SilcIDPayload payload);
 184  *
 185  * DESCRIPTION
 186  *
 187  *    Returns the ID type from the ID Payload. The type tells the
 188  *    type of the ID in the payload.
 189  *
 190  ***/
 191 SilcIdType silc_id_payload_get_type(SilcIDPayload payload);
 192
 193 /****f* silccore/SilcIDAPI/silc_id_payload_get_id
 194  *
 195  * SYNOPSIS
 196  *
 197  *    void *silc_id_payload_get_id(SilcIDPayload payload);
 198  *
 199  * DESCRIPTION
 200  *
 201  *    Returns the ID in the ID Payload. The caller must free the
 202  *    returned ID.
 203  *
 204  ***/
 205 void *silc_id_payload_get_id(SilcIDPayload payload);
 206
 207 /****f* silccore/SilcIDAPI/silc_id_payload_get_data
 208  *
 209  * SYNOPSIS
 210  *
 211  *    unsigned char *silc_id_payload_get_data(SilcIDPayload payload);
 212  *
 213  * DESCRIPTION
 214  *
 215  *    Returns the raw ID data from the ID Payload. The data is duplicated
 216  *    and the caller must free it.
 217  *
 218  ***/
 219 unsigned char *silc_id_payload_get_data(SilcIDPayload payload);
 220
 221 /****f* silccore/SilcIDAPI/silc_id_payload_get_len
 222  *
 223  * SYNOPSIS
 224  *
 225  *    SilcUInt32 silc_id_payload_get_len(SilcIDPayload payload);
 226  *
 227  * DESCRIPTION
 228  *
 229  *    Returns the length of the ID in the ID Payload.
 230  *
 231  ***/
 232 SilcUInt32 silc_id_payload_get_len(SilcIDPayload payload);
 233
 234 /****s* silccore/SilcIDAPI/SilcIDIP
 235  *
 236  * NAME
 237  *
 238  *    typedef struct { ... } SilcIDIP;
 239  *
 240  * DESCRIPTION
 241  *
 242  *    Generic IP address structure to indicate either IPv4 or IPv6 address.
 243  *    This structure is used inside all SILC ID's. The true length of the
 244  *    ID depends of the length of the IP address.
 245  *
 246  * SOURCE
 247  */
 248 typedef struct {
 249   unsigned char data[16];       /* IP data (in MSB first order) */
 250   SilcUInt8 data_len;           /* Length of the data (4 or 16) */
 251 } SilcIDIP;
 252 /***/
 253
 254 /****s* silccore/SilcIDAPI/SilcServerID
 255  *
 256  * NAME
 257  *
 258  *    typedef struct { ... } SilcServerID;
 259  *
 260  * DESCRIPTION
 261  *
 262  *    64 or 160 bit SilcServerID structure:
 263  *
 264  *     n bit IP address
 265  *    16 bit port
 266  *    16 bit random number
 267  *
 268  * SOURCE
 269  */
 270 typedef struct {
 271   SilcIDIP ip;                  /* n bit IP address */
 272   SilcUInt16 port;                      /* 16 bit port */
 273   SilcUInt16 rnd;                       /* 16 bit random number */
 274 } SilcServerID;
 275 /***/
 276
 277 /****s* silccore/SilcIDAPI/SilcClientID
 278  *
 279  * NAME
 280  *
 281  *    typedef struct { ... } SilcClientID;
 282  *
 283  * DESCRIPTION
 284  *
 285  *    128 or 224 bit SilcClientID structure:
 286  *
 287  *      n bit ServerID IP address [bits 1-32 or bits 1-128]
 288  *      8 bit random number
 289  *     88 bit hash value from nickname
 290  *
 291  * SOURCE
 292  */
 293 typedef struct {
 294   SilcIDIP ip;                                  /* n bit IP address */
 295   unsigned char rnd;                            /* 8 bit random number */
 296   unsigned char hash[CLIENTID_HASH_LEN];        /* 88 bit MD5 hash */
 297 } SilcClientID;
 298 /***/
 299
 300 /****s* silccore/SilcIDAPI/SilcChannelID
 301  *
 302  * NAME
 303  *
 304  *    typedef struct { ... } SilcChannelID;
 305  *
 306  * DESCRIPTION
 307  *
 308  *    64 or 160 bit SilcChannel ID structure:
 309  *
 310  *     n bit Router's ServerID IP address [bits 1-32 or bits 1-128]
 311  *    16 bit Router's ServerID port [bits 33-48 or bits 129-144]
 312  *    16 bit random number
 313  *
 314  * SOURCE
 315  */
 316 typedef struct {
 317   SilcIDIP ip;                                  /* n bit IP address */
 318   SilcUInt16 port;                                      /* 16 bit port */
 319   SilcUInt16 rnd;                                       /* 16 bit random number */
 320 } SilcChannelID;
 321 /***/
 322
 323 /* Macros */
 324
 325 /****d* silccore/SilcIDAPI/SILC_ID_COMPARE
 326  *
 327  * NAME
 328  *
 329  *    #define SILC_ID_COMPARE ...
 330  *
 331  * DESCRIPTION
 332  *
 333  *    Compares two ID's. Returns TRUE if they match and FALSE if they do
 334  *    not.
 335  *
 336  * SOURCE
 337  */
 338 #define SILC_ID_COMPARE(id1, id2, len) (!memcmp(id1, id2, len))
 339 /***/
 340
 341 /****d* silccore/SilcIDAPI/SILC_ID_CLIENT_COMPARE
 342  *
 343  * NAME
 344  *
 345  *    #define SILC_ID_CLIENT_COMPARE ...
 346  *
 347  * DESCRIPTION
 348  *
 349  *    Compares Client ID's. Returns TRUE if they match.
 350  *
 351  * SOURCE
 352  */
 353 #define SILC_ID_CLIENT_COMPARE(id1, id2) \
 354   SILC_ID_COMPARE(id1, id2, sizeof(SilcClientID))
 355 /***/
 356
 357 /****d* silccore/SilcIDAPI/SILC_ID_SERVER_COMPARE
 358  *
 359  * NAME
 360  *
 361  *    #define SILC_ID_SERVER_COMPARE ...
 362  *
 363  * DESCRIPTION
 364  *
 365  *    Compares Server ID's. Returns TRUE if they match.
 366  *
 367  * SOURCE
 368  */
 369 #define SILC_ID_SERVER_COMPARE(id1, id2) \
 370   SILC_ID_COMPARE(id1, id2, sizeof(SilcServerID))
 371 /***/
 372
 373 /****d* silccore/SilcIDAPI/SILC_ID_CHANNEL_COMPARE
 374  *
 375  * NAME
 376  *
 377  *    #define SILC_ID_CHANNEL_COMPARE ...
 378  *
 379  * DESCRIPTION
 380  *
 381  *    Compares Channel ID's. Returns TRUE if they match.
 382  *
 383  * SOURCE
 384  */
 385 #define SILC_ID_CHANNEL_COMPARE(id1, id2) \
 386   SILC_ID_COMPARE(id1, id2, sizeof(SilcChannelID))
 387 /***/
 388
 389 /****d* silccore/SilcIDAPI/SILC_ID_COMPARE_TYPE
 390  *
 391  * NAME
 392  *
 393  *    #define SILC_ID_COMPARE_TYPE ...
 394  *
 395  * DESCRIPTION
 396  *
 397  *    Compares two ID's by type. Returns TRUE if they match.
 398  *
 399  * SOURCE
 400  */
 401 #define SILC_ID_COMPARE_TYPE(id1, id2, type)                    \
 402   (type == SILC_ID_SERVER ? SILC_ID_SERVER_COMPARE(id1, id2) :  \
 403    type == SILC_ID_CLIENT ? SILC_ID_CLIENT_COMPARE(id1, id2) :  \
 404    SILC_ID_CHANNEL_COMPARE(id1, id2))
 405 /***/
 406
 407 /****d* silccore/SilcIDAPI/SILC_ID_COMPARE_HASH
 408  *
 409  * NAME
 410  *
 411  *    #define SILC_ID_COMPARE_HASH ...
 412  *
 413  * DESCRIPTION
 414  *
 415  *    Compares the nickname hash of the Client ID. Returns TRUE if
 416  *    they match. Since the nickname hash is based on the nickname of
 417  *    the client this can be used to search the ID by nickname (taking
 418  *    the hash out of it) or using the hash from the ID.
 419  *
 420  * SOURCE
 421  */
 422 #define SILC_ID_COMPARE_HASH(id1, id2) \
 423   (!memcmp((id1)->hash, (id2)->hash, CLIENTID_HASH_LEN))
 424 /***/
 425
 426 /* Prototypes */
 427
 428 /****f* silccore/SilcIDAPI/silc_id_id2str
 429  *
 430  * SYNOPSIS
 431  *
 432  *    unsigned char *silc_id_id2str(const void *id, SilcIdType type);
 433  *
 434  * DESCRIPTION
 435  *
 436  *    Converts an ID of type `type' to data. This can be used to
 437  *    convert the ID's to data for inclusion in the packets.
 438  *
 439  ***/
 440 unsigned char *silc_id_id2str(const void *id, SilcIdType type);
 441
 442 /****f* silccore/SilcIDAPI/silc_id_str2id
 443  *
 444  * SYNOPSIS
 445  *
 446  *    void *silc_id_str2id(const unsigned char *id, SilcUInt32 id_len,
 447  *                         SilcIdType type);
 448  *
 449  * DESCRIPTION
 450  *
 451  *    Converts ID data string to an ID. This can be used to get the
 452  *    ID out of data that has been taken for example from packet.
 453  *
 454  ***/
 455 void *silc_id_str2id(const unsigned char *id, SilcUInt32 id_len, SilcIdType type);
 456
 457 /****f* silccore/SilcIDAPI/silc_id_get_len
 458  *
 459  * SYNOPSIS
 460  *
 461  *    SilcUInt32 silc_id_get_len(const void *id, SilcIdType type);
 462  *
 463  * DESCRIPTION
 464  *
 465  *    Returns the true length of the ID of the type `type'.
 466  *
 467  ***/
 468 SilcUInt32 silc_id_get_len(const void *id, SilcIdType type);
 469
 470 /****f* silccore/SilcIDAPI/silc_id_dup
 471  *
 472  * SYNOPSIS
 473  *
 474  *    void *silc_id_dup(const void *id, SilcIdType type);
 475  *
 476  * DESCRIPTION
 477  *
 478  *    Duplicates the ID of the type `type'. The caller must free the
 479  *    duplicated ID.
 480  *
 481  ***/
 482 void *silc_id_dup(const void *id, SilcIdType type);
 483
 484 #endif