lib/silcskr/silcskr.h

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