lib/silccore/silcid.h

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