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