lib/silccore/silcid.h

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