lib/silcskr/silcskr.h

   1 /*
   2
   3   silcskr.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2005 - 2007 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* silcskr/SILC Key Repository
  21  *
  22  * DESCRIPTION
  23  *
  24  * SILC Key Repository
  25  *
  26  * SILC Key Repository is thread safe.  Same key repository context can be
  27  * safely used in multi threaded environment.
  28  *
  29  ***/
  30
  31 #ifndef SILCSKR_H
  32 #define SILCSKR_H
  33
  34 /****s* silcskr/SilcSKRAPI/SilcSKR
  35  *
  36  * NAME
  37  *
  38  *    typedef struct SilcSKRObject *SilcSKR, SilcSKRStruct;
  39  *
  40  * DESCRIPTION
  41  *
  42  *    This context is the actual SILC Key Repository and is allocated
  43  *    by silc_skr_alloc (or initialized by silc_skr_init) and given as
  44  *    attribute to all silc_skr_* functions.  It is freed by the
  45  *    silc_skr_free (or uninitialized with silc_skr_uninit) function.
  46  *
  47  ***/
  48 typedef struct SilcSKRObject *SilcSKR, SilcSKRStruct;
  49
  50 /****s* silcskr/SilcSKRAPI/SilcSKRFind
  51  *
  52  * NAME
  53  *
  54  *    typedef struct SilcSKRFindStruct *SilcSKRFind
  55  *
  56  * DESCRIPTION
  57  *
  58  *    This context contains the search constraints used find keys from the
  59  *    key repository.  It is allocated by silc_skr_find_alloc and freed
  60  *    by silc_skr_find_free.  The context is given as argument to all
  61  *    silc_skr_find* functions.
  62  *
  63  ***/
  64 typedef struct SilcSKRFindStruct *SilcSKRFind;
  65
  66 /****d* silcskr/SilcSKRAPI/SilcSKRKeyUsage
  67  *
  68  * NAME
  69  *
  70  *    typedef enum { ... } SilcSKRKeyUsage;
  71  *
  72  * DESCRIPTION
  73  *
  74  *    Indicates the usage of the key.  Keys can be added for different
  75  *    reasons and for different purpose to the repository.  SilcSKRKeyUsage
  76  *    indicates for what reason the key exists in the repository.  The default
  77  *    usage is SILC_SKR_USAGE_ANY and allows any kind of usage for the key.
  78  *    If the usage should be limited then specific usage bitmask can be
  79  *    specified when adding the key.  When searching keys from the
  80  *    repository at least one of the key usage bits must be found in order
  81  *    to find the key.
  82  *
  83  * SOURCE
  84  */
  85 typedef enum {
  86   SILC_SKR_USAGE_ANY                   = 0x0000,  /* Any usage */
  87   SILC_SKR_USAGE_AUTH                  = 0x0001,  /* Signatures/verification */
  88   SILC_SKR_USAGE_ENC                   = 0x0002,  /* Encryption/decryption */
  89   SILC_SKR_USAGE_KEY_AGREEMENT         = 0x0004,  /* Key agreement protocol */
  90   SILC_SKR_USAGE_IDENTIFICATION        = 0x0008,  /* Identifying key owner */
  91   SILC_SKR_USAGE_SERVICE_AUTHORIZATION = 0x0010,  /* Service authorization */
  92
  93   /* From 0x0100 reserved for private/application use. */
  94 } SilcSKRKeyUsage;
  95 /***/
  96
  97 /****s* silcskr/SilcSKRAPI/SilcSKRKey
  98  *
  99  * NAME
 100  *
 101  *    typedef struct SilcSKRKeyStruct { ... } *SilcSKRKey;
 102  *
 103  * DESCRIPTION
 104  *
 105  *    This context holds the public key, optional public key specific
 106  *    context and public key usage bits.  This context is returned in
 107  *    the SilcSKRFindCallback list.  Each entry in the list is SIlcSKRKey.
 108  *
 109  * SOURCE
 110  *
 111  */
 112 typedef struct SilcSKRKeyStruct {
 113   SilcSKRKeyUsage usage;        /* Key usage */
 114   SilcPublicKey key;            /* Public key */
 115   void *key_context;            /* Optional key specific context */
 116 } *SilcSKRKey;
 117 /***/
 118
 119 /****d* silcskr/SilcSKRAPI/SilcSKRStatus
 120  *
 121  * NAME
 122  *
 123  *    typedef enum { ... } SilcSKRStatus;
 124  *
 125  * DESCRIPTION
 126  *
 127  *    Indicates the status of the key repository procedures.  This is
 128  *    returned to SilcSKRFindCallback function to indicate the status
 129  *    of the finding.  This is a bitmask, and more than one status may
 130  *    be set at one time.
 131  *
 132  *    If there are no errors only SILC_SKR_OK is set.  If error occurred
 133  *    then at least SILC_SKR_ERROR is set, and possibly other error
 134  *    status also.
 135  *
 136  * SOURCE
 137  */
 138 typedef enum {
 139   SILC_SKR_OK                 = 0x00000001, /* All is Ok */
 140   SILC_SKR_ERROR              = 0x00000002, /* Generic error status */
 141   SILC_SKR_ALREADY_EXIST      = 0x00000004, /* Key already exist */
 142   SILC_SKR_NOT_FOUND          = 0x00000008, /* No keys were found */
 143   SILC_SKR_NO_MEMORY          = 0x00000010, /* System out of memory */
 144   SILC_SKR_UNSUPPORTED_TYPE   = 0x00000020, /* Unsupported PKCS type */
 145 } SilcSKRStatus;
 146 /***/
 147
 148 /****f* silcskr/SilcSKRAPI/SilcSKRFindCallback
 149  *
 150  * SYNOPSIS
 151  *
 152  *    typedef void (*SilcSKRFindCallback)(SilcSKR skr, SilcSKRFind find,
 153  *                                        SilcSKRStatus status,
 154  *                                        SilcDList keys, void *context);
 155  *
 156  * DESCRIPTION
 157  *
 158  *    Callback that is given as argument to silc_skr_find and other find
 159  *    functions.  Returns the results of the finding.  If keys were found
 160  *    the `keys' is non-NULL and receiver must free it with silc_dlist_uninit.
 161  *    Each entry in the `keys' is SilcSKRKey context.  The list `keys' is
 162  *    already at start so calling silc_dlist_start is not necessary when
 163  *    traversing the list from the start.  If the `find' is non-NULL it must
 164  *    be freed with silc_skr_find_free.
 165  *
 166  ***/
 167 typedef void (*SilcSKRFindCallback)(SilcSKR skr, SilcSKRFind find,
 168                                     SilcSKRStatus status,
 169                                     SilcDList keys, void *context);
 170
 171 /****f* silcskr/SilcSKRAPI/silc_skr_alloc
 172  *
 173  * SYNOPSIS
 174  *
 175  *    SilcSKR silc_skr_alloc(void);
 176  *
 177  * DESCRIPTION
 178  *
 179  *    Allocates key repository context.
 180  *
 181  ***/
 182 SilcSKR silc_skr_alloc(void);
 183
 184 /****f* silcskr/SilcSKRAPI/silc_skr_free
 185  *
 186  * SYNOPSIS
 187  *
 188  *    void silc_skr_free(SilcSKR skr);
 189  *
 190  * DESCRIPTION
 191  *
 192  *    Free's the key repository context `skr' and all resources in it.
 193  *
 194  ***/
 195 void silc_skr_free(SilcSKR skr);
 196
 197 /****f* silcskr/SilcSKRAPI/silc_skr_init
 198  *
 199  * SYNOPSIS
 200  *
 201  *    SilcBool silc_skr_init(SilcSKR skr);
 202  *
 203  * DESCRIPTION
 204  *
 205  *    Initializes a pre-allocated SilcSKR context.  This function is
 206  *    equivalent to silc_skr_alloc but takes pre-allocated context as
 207  *    argument.  Returns FALSE if initialization failed.
 208  *
 209  ***/
 210 SilcBool silc_skr_init(SilcSKR skr);
 211
 212 /****f* silcskr/SilcSKRAPI/silc_skr_uninit
 213  *
 214  * SYNOPSIS
 215  *
 216  *    void silc_skr_uninit(SilcSKR skr);
 217  *
 218  * DESCRIPTION
 219  *
 220  *    Uninitializes a pre-allocated SilcSKR context.  Use this function if
 221  *    you called silc_skr_init.
 222  *
 223  ***/
 224 void silc_skr_uninit(SilcSKR skr);
 225
 226 /****f* silcskr/SilcSKRAPI/silc_skr_add_public_key
 227  *
 228  * SYNOPSIS
 229  *
 230  *    SilcSKRStatus silc_skr_add_public_key(SilcSKR skr,
 231  *                                          SilcPublicKey public_key,
 232  *                                          SilcSKRKeyUsage usage,
 233  *                                          void *key_context);
 234  *
 235  * DESCRIPTION
 236  *
 237  *    Add a public key to repository.  The repository will steal `public_key'
 238  *    and caller must not free it.  The `key_context' is optional key specific
 239  *    context that will be saved in the repository with the key, and can be
 240  *    retrieved with the key.  Public key can be added only once to the
 241  *    repository.  To add same key more than once to repository different
 242  *    `key_context' must be used each time.
 243  *
 244  *    Returns SILC_SKR_OK if the key was added successfully, and error
 245  *    status if key could not be added, or has been added already.
 246  *
 247  * EXAMPLE
 248  *
 249  *    // Add a key to repository
 250  *    if (silc_skr_add_public_key(repository, public_key,
 251  *                                SILC_SKR_USAGE_ANY, NULL) != SILC_SKR_OK)
 252  *      goto error;
 253  *
 254  ***/
 255 SilcSKRStatus silc_skr_add_public_key(SilcSKR skr,
 256                                       SilcPublicKey public_key,
 257                                       SilcSKRKeyUsage usage,
 258                                       void *key_context);
 259
 260 /****f* silcskr/SilcSKRAPI/silc_skr_add_public_key_simple
 261  *
 262  * SYNOPSIS
 263  *
 264  *    SilcSKRStatus silc_skr_add_public_key_simple(SilcSKR skr,
 265  *                                                 SilcPublicKey public_key,
 266  *                                                 SilcSKRKeyUsage usage,
 267  *                                                 void *key_context);
 268  *
 269  * DESCRIPTION
 270  *
 271  *    Same as silc_skr_add_public_key but adds only the public key, usage
 272  *    bits and key context.  The key cannot be found with any other search
 273  *    constraint except setting the public key, usage bits and/or key
 274  *    context as search constraint.  This function can be used to add the
 275  *    key with as little memory as possible to the repository, and makes
 276  *    it a good way to cheaply store large amounts of public keys.
 277  *
 278  *    Returns SILC_SKR_OK if the key was added successfully, and error
 279  *    status if key could not be added, or has been added already.
 280  *
 281  ***/
 282 SilcSKRStatus silc_skr_add_public_key_simple(SilcSKR skr,
 283                                              SilcPublicKey public_key,
 284                                              SilcSKRKeyUsage usage,
 285                                              void *key_context);
 286
 287 /****f* silcskr/SilcSKRAPI/silc_skr_find_alloc
 288  *
 289  * SYNOPSIS
 290  *
 291  *    SilcSKRFind silc_skr_find_alloc(void);
 292  *
 293  * DESCRIPTION
 294  *
 295  *    Allocates SilcSKRFind context that will hold search constraints used
 296  *    to find specific keys from the repository.  Caller must free the
 297  *    context by calling silc_skr_find_free.
 298  *
 299  ***/
 300 SilcSKRFind silc_skr_find_alloc(void);
 301
 302 /****f* silcskr/SilcSKRAPI/silc_skr_find_free
 303  *
 304  * SYNOPSIS
 305  *
 306  *    void silc_skr_find_free(SilcSKRFind find);
 307  *
 308  * DESCRIPTION
 309  *
 310  *    Free's the search constraints context `find' and all resources in it.
 311  *
 312  ***/
 313 void silc_skr_find_free(SilcSKRFind find);
 314
 315 /****f* silcskr/SilcSKRAPI/silc_skr_find_add_pkcs_type
 316  *
 317  * SYNOPSIS
 318  *
 319  *    SilcBool silc_skr_find_add_pkcs_type(SilcSKRFind find,
 320  *                                         SilcPKCSType type);
 321  *
 322  * DESCRIPTION
 323  *
 324  *    Sets public key cryptosystem type as search constraint.  Will search
 325  *    only for the specific type of key(s).
 326  *
 327  ***/
 328 SilcBool silc_skr_find_set_pkcs_type(SilcSKRFind find, SilcPKCSType type);
 329
 330 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_username
 331  *
 332  * SYNOPSIS
 333  *
 334  *    SilcBool silc_skr_find_set_username(SilcSKRFind find,
 335  *                                        const char *username);
 336  *
 337  * DESCRIPTION
 338  *
 339  *    Sets username as search constraint.  This specific username must be
 340  *    present in the key.
 341  *
 342  *    This may be used with SILC_PKCS_SILC PKCS type only.
 343  *
 344  ***/
 345 SilcBool silc_skr_find_set_username(SilcSKRFind find, const char *username);
 346
 347 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_host
 348  *
 349  * SYNOPSIS
 350  *
 351  *    SilcBool silc_skr_find_set_host(SilcSKRFind find,
 352  *                                    const char *host);
 353  *
 354  * DESCRIPTION
 355  *
 356  *    Sets host as search constraint.  This specific host must be
 357  *    present in the key.  The `host' may be a hostname or IP address.
 358  *
 359  *    This may be used with SILC_PKCS_SILC PKCS type only.
 360  *
 361  ***/
 362 SilcBool silc_skr_find_set_host(SilcSKRFind find, const char *host);
 363
 364 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_realname
 365  *
 366  * SYNOPSIS
 367  *
 368  *    SilcBool silc_skr_find_set_realname(SilcSKRFind find,
 369  *                                        const char *realname);
 370  *
 371  * DESCRIPTION
 372  *
 373  *    Sets real name as search constraint.  This specific name must be
 374  *    present in the key.
 375  *
 376  *    This may be used with SILC_PKCS_SILC PKCS type only.
 377  *
 378  ***/
 379 SilcBool silc_skr_find_set_realname(SilcSKRFind find, const char *realname);
 380
 381 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_email
 382  *
 383  * SYNOPSIS
 384  *
 385  *    SilcBool silc_skr_find_set_email(SilcSKRFind find,
 386  *                                     const char *email);
 387  *
 388  * DESCRIPTION
 389  *
 390  *    Sets email address as search constraint.  This specific address must be
 391  *    present in the key.
 392  *
 393  *    This may be used with SILC_PKCS_SILC PKCS type only.
 394  *
 395  ***/
 396 SilcBool silc_skr_find_set_email(SilcSKRFind find, const char *email);
 397
 398 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_org
 399  *
 400  * SYNOPSIS
 401  *
 402  *    SilcBool silc_skr_find_set_org(SilcSKRFind find,
 403  *                                   const char *email);
 404  *
 405  * DESCRIPTION
 406  *
 407  *    Sets organization as search constraint.  This specific organization
 408  *    must be present in the key.
 409  *
 410  *    This may be used with SILC_PKCS_SILC PKCS type only.
 411  *
 412  ***/
 413 SilcBool silc_skr_find_set_org(SilcSKRFind find, const char *org);
 414
 415 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_country
 416  *
 417  * SYNOPSIS
 418  *
 419  *    SilcBool silc_skr_find_set_country(SilcSKRFind find,
 420  *                                       const char *email);
 421  *
 422  * DESCRIPTION
 423  *
 424  *    Sets country as search constraint.  This specific country must be
 425  *    present in the key.
 426  *
 427  *    This may be used with SILC_PKCS_SILC PKCS type only.
 428  *
 429  ***/
 430 SilcBool silc_skr_find_set_country(SilcSKRFind find, const char *country);
 431
 432 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_public_key
 433  *
 434  * SYNOPSIS
 435  *
 436  *    SilcBool silc_skr_find_set_public_key(SilcSKRFind find,
 437  *                                          SilcPublicKey public_key);
 438  *
 439  * DESCRIPTION
 440  *
 441  *    Sets public key as search constraint.  This specific key must be
 442  *    present in the key.
 443  *
 444  ***/
 445 SilcBool silc_skr_find_set_public_key(SilcSKRFind find,
 446                                       SilcPublicKey public_key);
 447
 448 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_context
 449  *
 450  * SYNOPSIS
 451  *
 452  *    SilcBool silc_skr_find_set_context(SilcSKRFind find, void *context);
 453  *
 454  * DESCRIPTION
 455  *
 456  *    Sets public key specific context as search constraint.  This specific
 457  *    context must be associated with the key.  This is the context that
 458  *    was given as argument when adding the key to repository.
 459  *
 460  ***/
 461 SilcBool silc_skr_find_set_context(SilcSKRFind find, void *context);
 462
 463 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_usage
 464  *
 465  * SYNOPSIS
 466  *
 467  *    SilcBool silc_skr_find_set_usage(SilcSKRFind find,
 468  *                                     SilcSKRKeyUsage usage);
 469  *
 470  * DESCRIPTION
 471  *
 472  *    Sets key usage as search constraint.  At least one of the key usage
 473  *    bits must be present in the key.  This search constraint cannot be
 474  *    used alone to search keys.  At least one other search constraint
 475  *    must also be used.
 476  *
 477  ***/
 478 SilcBool silc_skr_find_set_usage(SilcSKRFind find, SilcSKRKeyUsage usage);
 479
 480 /****f* silcskr/SilcSKRAPI/silc_skr_find
 481  *
 482  * SYNOPSIS
 483  *
 484  *    SilcAsyncOperation silc_skr_find(SilcSKR skr, SilcSchedule schedule,
 485  *                                     SilcSKRFind find,
 486  *                                     SilcSKRFindCallback callback,
 487  *                                     void *callback_context);
 488  *
 489  * DESCRIPTION
 490  *
 491  *    Finds key(s) from key repository `skr' by the search constraints
 492  *    `find'.  As the finding procedure may be asynchronous this returns
 493  *    SilcAsyncOperation that may be used to control (like abort) the
 494  *    operation.  The `callback' with `callback_context' will be called
 495  *    to return found keys.  If this returns NULL the finding was not
 496  *    asynchronous, and the `callback' has been called already.
 497  *
 498  * EXAMPLE
 499  *
 500  *   SilcSKRFind find;
 501  *
 502  *   // Find all SILC public keys originating from Finland
 503  *   find = silc_skr_find_alloc();
 504  *   silc_skr_find_set_pkcs_type(find, SILC_PKCS_SILC);
 505  *   silc_skr_find_set_country(find, "FI");
 506  *
 507  *   // Find
 508  *   silc_skr_find(skr, schedule, find, find_callback, cb_context);
 509  *
 510  ***/
 511 SilcAsyncOperation silc_skr_find(SilcSKR skr, SilcSchedule schedule,
 512                                  SilcSKRFind find,
 513                                  SilcSKRFindCallback callback,
 514                                  void *callback_context);
 515
 516 #include "silcskr_i.h"
 517
 518 #endif /* SILCSKR_H */