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