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/SILC ID Interface
  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 /* Prototypes */
  89
  90 /****f* silccore/SilcIDAPI/silc_id_payload_parse
  91  *
  92  * SYNOPSIS
  93  *
  94  *    SilcIDPayload silc_id_payload_parse(const unsigned char *payload,
  95  *                                        SilcUInt32 payload_len);
  96  *
  97  * DESCRIPTION
  98  *
  99  *    Parses buffer and return ID payload into payload structure. The
 100  *    `buffer' is raw payload buffer.  The caller must free the returned
 101  *    payload.
 102  *
 103  ***/
 104 SilcIDPayload silc_id_payload_parse(const unsigned char *payload,
 105                                     SilcUInt32 payload_len);
 106
 107 /****f* silccore/SilcIDAPI/silc_id_payload_parse_id
 108  *
 109  * SYNOPSIS
 110  *
 111  *    void *silc_id_payload_parse_id(const unsigned char *data,
 112  *                                   SilcUInt32 len,
 113  *                                   SilcIdType *type);
 114  *
 115  * DESCRIPTION
 116  *
 117  *    Return ID directly from the raw ID Payload data buffer. The
 118  *    caller must free the returned ID.
 119  *
 120  ***/
 121 void *silc_id_payload_parse_id(const unsigned char *data, SilcUInt32 len,
 122                                SilcIdType *type);
 123
 124 /****f* silccore/SilcIDAPI/silc_id_payload_encode
 125  *
 126  * SYNOPSIS
 127  *
 128  *    SilcBuffer silc_id_payload_encode(const void *id, SilcIdType type);
 129  *
 130  * DESCRIPTION
 131  *
 132  *    Encodes ID Payload. The `id' is the ID of the type `type' to put
 133  *    into the payload. Returns the encoded payload buffer.
 134  *
 135  ***/
 136 SilcBuffer silc_id_payload_encode(const void *id, SilcIdType type);
 137
 138 /****f* silccore/SilcIDAPI/silc_id_payload_encode_data
 139  *
 140  * SYNOPSIS
 141  *
 142  *    SilcBuffer silc_id_payload_encode_data(const unsigned char *id,
 143  *                                           uin32 id_len, SilcIdType type);
 144  *
 145  * DESCRIPTION
 146  *
 147  *    Encodes ID Payload. The `id' is raw ID data of the length of `id_len'
 148  *    of type of `type'. Returns the encoded payload buffer.
 149  *
 150  ***/
 151 SilcBuffer silc_id_payload_encode_data(const unsigned char *id,
 152                                        SilcUInt32 id_len, SilcIdType type);
 153
 154 /****f* silccore/SilcIDAPI/silc_id_payload_free
 155  *
 156  * SYNOPSIS
 157  *
 158  *    void silc_id_payload_free(SilcIDPayload payload);
 159  *
 160  * DESCRIPTION
 161  *
 162  *    Frees the ID Payload and all data in it.
 163  *
 164  ***/
 165 void silc_id_payload_free(SilcIDPayload payload);
 166
 167 /****f* silccore/SilcIDAPI/silc_id_payload_get_type
 168  *
 169  * SYNOPSIS
 170  *
 171  *    SilcIdType silc_id_payload_get_type(SilcIDPayload payload);
 172  *
 173  * DESCRIPTION
 174  *
 175  *    Returns the ID type from the ID Payload. The type tells the
 176  *    type of the ID in the payload.
 177  *
 178  ***/
 179 SilcIdType silc_id_payload_get_type(SilcIDPayload payload);
 180
 181 /****f* silccore/SilcIDAPI/silc_id_payload_get_id
 182  *
 183  * SYNOPSIS
 184  *
 185  *    void *silc_id_payload_get_id(SilcIDPayload payload);
 186  *
 187  * DESCRIPTION
 188  *
 189  *    Returns the ID in the ID Payload. The caller must free the
 190  *    returned ID.
 191  *
 192  ***/
 193 void *silc_id_payload_get_id(SilcIDPayload payload);
 194
 195 /****f* silccore/SilcIDAPI/silc_id_payload_get_data
 196  *
 197  * SYNOPSIS
 198  *
 199  *    unsigned char *silc_id_payload_get_data(SilcIDPayload payload);
 200  *
 201  * DESCRIPTION
 202  *
 203  *    Returns the raw ID data from the ID Payload. The data is duplicated
 204  *    and the caller must free it.
 205  *
 206  ***/
 207 unsigned char *silc_id_payload_get_data(SilcIDPayload payload);
 208
 209 /****f* silccore/SilcIDAPI/silc_id_payload_get_len
 210  *
 211  * SYNOPSIS
 212  *
 213  *    SilcUInt32 silc_id_payload_get_len(SilcIDPayload payload);
 214  *
 215  * DESCRIPTION
 216  *
 217  *    Returns the length of the ID in the ID Payload.
 218  *
 219  ***/
 220 SilcUInt32 silc_id_payload_get_len(SilcIDPayload payload);
 221
 222 /****s* silccore/SilcIDAPI/SilcIDIP
 223  *
 224  * NAME
 225  *
 226  *    typedef struct { ... } SilcIDIP;
 227  *
 228  * DESCRIPTION
 229  *
 230  *    Generic IP address structure to indicate either IPv4 or IPv6 address.
 231  *    This structure is used inside all SILC ID's. The true length of the
 232  *    ID depends of the length of the IP address.
 233  *
 234  * SOURCE
 235  */
 236 typedef struct {
 237   unsigned char data[16];       /* IP data (in MSB first order) */
 238   SilcUInt8 data_len;           /* Length of the data (4 or 16) */
 239 } SilcIDIP;
 240 /***/
 241
 242 /****s* silccore/SilcIDAPI/SilcServerID
 243  *
 244  * NAME
 245  *
 246  *    typedef struct { ... } SilcServerID;
 247  *
 248  * DESCRIPTION
 249  *
 250  *    64 or 160 bit SilcServerID structure:
 251  *
 252  *     n bit IP address
 253  *    16 bit port
 254  *    16 bit random number
 255  *
 256  * SOURCE
 257  */
 258 typedef struct {
 259   SilcIDIP ip;                  /* n bit IP address */
 260   SilcUInt16 port;              /* 16 bit port */
 261   SilcUInt16 rnd;               /* 16 bit random number */
 262 } SilcServerID;
 263 /***/
 264
 265 /****s* silccore/SilcIDAPI/SilcClientID
 266  *
 267  * NAME
 268  *
 269  *    typedef struct { ... } SilcClientID;
 270  *
 271  * DESCRIPTION
 272  *
 273  *    128 or 224 bit SilcClientID structure:
 274  *
 275  *      n bit ServerID IP address [bits 1-32 or bits 1-128]
 276  *      8 bit random number
 277  *     88 bit hash value from lowercase nickname
 278  *
 279  * SOURCE
 280  */
 281 typedef struct {
 282   SilcIDIP ip;                                  /* n bit IP address */
 283   unsigned char rnd;                            /* 8 bit random number */
 284   unsigned char hash[CLIENTID_HASH_LEN];        /* 88 bit MD5 hash */
 285 } SilcClientID;
 286 /***/
 287
 288 /****s* silccore/SilcIDAPI/SilcChannelID
 289  *
 290  * NAME
 291  *
 292  *    typedef struct { ... } SilcChannelID;
 293  *
 294  * DESCRIPTION
 295  *
 296  *    64 or 160 bit SilcChannel ID structure:
 297  *
 298  *     n bit Router's ServerID IP address [bits 1-32 or bits 1-128]
 299  *    16 bit Router's ServerID port [bits 33-48 or bits 129-144]
 300  *    16 bit random number
 301  *
 302  * SOURCE
 303  */
 304 typedef struct {
 305   SilcIDIP ip;                  /* n bit IP address */
 306   SilcUInt16 port;              /* 16 bit port */
 307   SilcUInt16 rnd;               /* 16 bit random number */
 308 } SilcChannelID;
 309 /***/
 310
 311 /* Macros */
 312
 313 /****d* silccore/SilcIDAPI/SILC_ID_COMPARE
 314  *
 315  * NAME
 316  *
 317  *    #define SILC_ID_COMPARE ...
 318  *
 319  * DESCRIPTION
 320  *
 321  *    Compares two ID's. Returns TRUE if they match and FALSE if they do
 322  *    not.
 323  *
 324  * SOURCE
 325  */
 326 #define SILC_ID_COMPARE(id1, id2, len) (!memcmp(id1, id2, len))
 327 /***/
 328
 329 /****d* silccore/SilcIDAPI/SILC_ID_CLIENT_COMPARE
 330  *
 331  * NAME
 332  *
 333  *    #define SILC_ID_CLIENT_COMPARE ...
 334  *
 335  * DESCRIPTION
 336  *
 337  *    Compares Client ID's. Returns TRUE if they match.
 338  *
 339  * SOURCE
 340  */
 341 #define SILC_ID_CLIENT_COMPARE(id1, id2) \
 342   SILC_ID_COMPARE(id1, id2, sizeof(SilcClientID))
 343 /***/
 344
 345 /****d* silccore/SilcIDAPI/SILC_ID_SERVER_COMPARE
 346  *
 347  * NAME
 348  *
 349  *    #define SILC_ID_SERVER_COMPARE ...
 350  *
 351  * DESCRIPTION
 352  *
 353  *    Compares Server ID's. Returns TRUE if they match.
 354  *
 355  * SOURCE
 356  */
 357 #define SILC_ID_SERVER_COMPARE(id1, id2) \
 358   SILC_ID_COMPARE(id1, id2, sizeof(SilcServerID))
 359 /***/
 360
 361 /****d* silccore/SilcIDAPI/SILC_ID_CHANNEL_COMPARE
 362  *
 363  * NAME
 364  *
 365  *    #define SILC_ID_CHANNEL_COMPARE ...
 366  *
 367  * DESCRIPTION
 368  *
 369  *    Compares Channel ID's. Returns TRUE if they match.
 370  *
 371  * SOURCE
 372  */
 373 #define SILC_ID_CHANNEL_COMPARE(id1, id2) \
 374   SILC_ID_COMPARE(id1, id2, sizeof(SilcChannelID))
 375 /***/
 376
 377 /****d* silccore/SilcIDAPI/SILC_ID_COMPARE_TYPE
 378  *
 379  * NAME
 380  *
 381  *    #define SILC_ID_COMPARE_TYPE ...
 382  *
 383  * DESCRIPTION
 384  *
 385  *    Compares two ID's by type. Returns TRUE if they match.
 386  *
 387  * SOURCE
 388  */
 389 #define SILC_ID_COMPARE_TYPE(id1, id2, type)                    \
 390   (type == SILC_ID_SERVER ? SILC_ID_SERVER_COMPARE(id1, id2) :  \
 391    type == SILC_ID_CLIENT ? SILC_ID_CLIENT_COMPARE(id1, id2) :  \
 392    SILC_ID_CHANNEL_COMPARE(id1, id2))
 393 /***/
 394
 395 /****d* silccore/SilcIDAPI/SILC_ID_COMPARE_HASH
 396  *
 397  * NAME
 398  *
 399  *    #define SILC_ID_COMPARE_HASH ...
 400  *
 401  * DESCRIPTION
 402  *
 403  *    Compares the nickname hash of the Client ID. Returns TRUE if
 404  *    they match. Since the nickname hash is based on the nickname of
 405  *    the client this can be used to search the ID by nickname (taking
 406  *    the hash out of it) or using the hash from the ID.
 407  *
 408  * SOURCE
 409  */
 410 #define SILC_ID_COMPARE_HASH(id1, id2) \
 411   (!memcmp((id1)->hash, (id2)->hash, CLIENTID_HASH_LEN))
 412 /***/
 413
 414 /* Prototypes */
 415
 416 /****f* silccore/SilcIDAPI/silc_id_id2str
 417  *
 418  * SYNOPSIS
 419  *
 420  *    unsigned char *silc_id_id2str(const void *id, SilcIdType type);
 421  *
 422  * DESCRIPTION
 423  *
 424  *    Converts an ID of type `type' to data. This can be used to
 425  *    convert the ID's to data for inclusion in the packets.  Use the
 426  *    silc_id_get_len to get the length of the ID.
 427  *
 428  ***/
 429 unsigned char *silc_id_id2str(const void *id, SilcIdType type);
 430
 431 /****f* silccore/SilcIDAPI/silc_id_str2id
 432  *
 433  * SYNOPSIS
 434  *
 435  *    void *silc_id_str2id(const unsigned char *id, SilcUInt32 id_len,
 436  *                         SilcIdType type);
 437  *
 438  * DESCRIPTION
 439  *
 440  *    Converts ID data string to an ID. This can be used to get the
 441  *    ID out of data that has been taken for example from packet.
 442  *
 443  ***/
 444 void *silc_id_str2id(const unsigned char *id, SilcUInt32 id_len,
 445                      SilcIdType type);
 446
 447 /****f* silccore/SilcIDAPI/silc_id_get_len
 448  *
 449  * SYNOPSIS
 450  *
 451  *    SilcUInt32 silc_id_get_len(const void *id, SilcIdType type);
 452  *
 453  * DESCRIPTION
 454  *
 455  *    Returns the true length of the ID of the type `type'.
 456  *
 457  ***/
 458 SilcUInt32 silc_id_get_len(const void *id, SilcIdType type);
 459
 460 /****f* silccore/SilcIDAPI/silc_id_dup
 461  *
 462  * SYNOPSIS
 463  *
 464  *    void *silc_id_dup(const void *id, SilcIdType type);
 465  *
 466  * DESCRIPTION
 467  *
 468  *    Duplicates the ID of the type `type'. The caller must free the
 469  *    duplicated ID.
 470  *
 471  ***/
 472 void *silc_id_dup(const void *id, SilcIdType type);
 473
 474 #endif