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