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 is a generic public key and certificate repository
  25  * which allows fast and versatile ways to retrieve public keys from the
  26  * the repository.
  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/SilcSKRAPI/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/SilcSKRAPI/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/SilcSKRAPI/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/SilcSKRAPI/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 /****d* silcskr/SilcSKRAPI/SilcSKRStatus
 122  *
 123  * NAME
 124  *
 125  *    typedef enum { ... } SilcSKRStatus;
 126  *
 127  * DESCRIPTION
 128  *
 129  *    Indicates the status of the key repository procedures.  This is
 130  *    returned to SilcSKRFindCallback function to indicate the status
 131  *    of the finding.  This is a bitmask, and more than one status may
 132  *    be set at one time.
 133  *
 134  *    If there are no errors only SILC_SKR_OK is set.  If error occurred
 135  *    then at least SILC_SKR_ERROR is set, and possibly other error
 136  *    status also.
 137  *
 138  *    If the SILC_SKR_UNSUPPORTED_TYPE is returned the repository does not
 139  *    support the public key type and it cannot be added to the repository.
 140  *
 141  * SOURCE
 142  */
 143 typedef enum {
 144   SILC_SKR_OK                 = 0x00000001, /* All is Ok */
 145   SILC_SKR_ERROR              = 0x00000002, /* Generic error status */
 146   SILC_SKR_ALREADY_EXIST      = 0x00000004, /* Key already exist */
 147   SILC_SKR_NOT_FOUND          = 0x00000008, /* No keys were found */
 148   SILC_SKR_NO_MEMORY          = 0x00000010, /* System out of memory */
 149   SILC_SKR_UNSUPPORTED_TYPE   = 0x00000020, /* Unsupported PKCS type */
 150 } SilcSKRStatus;
 151 /***/
 152
 153 /****f* silcskr/SilcSKRAPI/SilcSKRFindCallback
 154  *
 155  * SYNOPSIS
 156  *
 157  *    typedef void (*SilcSKRFindCallback)(SilcSKR skr, SilcSKRFind find,
 158  *                                        SilcSKRStatus status,
 159  *                                        SilcDList keys, void *context);
 160  *
 161  * DESCRIPTION
 162  *
 163  *    Callback that is given as argument to silc_skr_find and other find
 164  *    functions.  Returns the results of the finding.  If keys were found
 165  *    the `keys' is non-NULL and receiver must free it with silc_dlist_uninit.
 166  *    Each entry in the `keys' is SilcSKRKey context.  The list `keys' is
 167  *    already at start so calling silc_dlist_start is not necessary when
 168  *    traversing the list from the start.  If the `find' is non-NULL it must
 169  *    be freed with silc_skr_find_free.
 170  *
 171  ***/
 172 typedef void (*SilcSKRFindCallback)(SilcSKR skr, SilcSKRFind find,
 173                                     SilcSKRStatus status,
 174                                     SilcDList keys, void *context);
 175
 176 /****f* silcskr/SilcSKRAPI/silc_skr_alloc
 177  *
 178  * SYNOPSIS
 179  *
 180  *    SilcSKR silc_skr_alloc(void);
 181  *
 182  * DESCRIPTION
 183  *
 184  *    Allocates key repository context.
 185  *
 186  ***/
 187 SilcSKR silc_skr_alloc(void);
 188
 189 /****f* silcskr/SilcSKRAPI/silc_skr_free
 190  *
 191  * SYNOPSIS
 192  *
 193  *    void silc_skr_free(SilcSKR skr);
 194  *
 195  * DESCRIPTION
 196  *
 197  *    Free's the key repository context `skr' and all resources in it.
 198  *
 199  ***/
 200 void silc_skr_free(SilcSKR skr);
 201
 202 /****f* silcskr/SilcSKRAPI/silc_skr_init
 203  *
 204  * SYNOPSIS
 205  *
 206  *    SilcBool silc_skr_init(SilcSKR skr);
 207  *
 208  * DESCRIPTION
 209  *
 210  *    Initializes a pre-allocated SilcSKR context.  This function is
 211  *    equivalent to silc_skr_alloc but takes pre-allocated context as
 212  *    argument.  Returns FALSE if initialization failed.
 213  *
 214  ***/
 215 SilcBool silc_skr_init(SilcSKR skr);
 216
 217 /****f* silcskr/SilcSKRAPI/silc_skr_uninit
 218  *
 219  * SYNOPSIS
 220  *
 221  *    void silc_skr_uninit(SilcSKR skr);
 222  *
 223  * DESCRIPTION
 224  *
 225  *    Uninitializes a pre-allocated SilcSKR context.  Use this function if
 226  *    you called silc_skr_init.
 227  *
 228  ***/
 229 void silc_skr_uninit(SilcSKR skr);
 230
 231 /****f* silcskr/SilcSKRAPI/silc_skr_add_public_key
 232  *
 233  * SYNOPSIS
 234  *
 235  *    SilcSKRStatus silc_skr_add_public_key(SilcSKR skr,
 236  *                                          SilcPublicKey public_key,
 237  *                                          SilcSKRKeyUsage usage,
 238  *                                          void *key_context,
 239  *                                          SilcSKRKey *return_key);
 240  *
 241  * DESCRIPTION
 242  *
 243  *    Add a public key to repository.  The repository will steal `public_key'
 244  *    and caller must not free it.  The `key_context' is optional key specific
 245  *    context that will be saved in the repository with the key, and can be
 246  *    retrieved with the key.  Public key can be added only once to the
 247  *    repository.  To add same key more than once to repository different
 248  *    `key_context' must be used each time.
 249  *
 250  *    Returns an entry of the added public key in the repository to the
 251  *    `return_key' pointer, if it is non-NULL.  The returned entry remains
 252  *    valid as long as the public key is in the repository, however a
 253  *    reference may be taken with silc_skr_ref_public_key to assure the
 254  *    entry remains valid.
 255  *
 256  *    Returns SILC_SKR_OK if the key was added successfully, and error
 257  *    status if key could not be added, or has been added already.
 258  *
 259  * EXAMPLE
 260  *
 261  *    // Add a key to repository
 262  *    if (silc_skr_add_public_key(repository, pubkey, SILC_SKR_USAGE_ANY,
 263  *                                NULL, NULL) != SILC_SKR_OK)
 264  *      goto error;
 265  *
 266  ***/
 267 SilcSKRStatus silc_skr_add_public_key(SilcSKR skr,
 268                                       SilcPublicKey public_key,
 269                                       SilcSKRKeyUsage usage,
 270                                       void *key_context,
 271                                       SilcSKRKey *return_key);
 272
 273 /****f* silcskr/SilcSKRAPI/silc_skr_add_public_key_simple
 274  *
 275  * SYNOPSIS
 276  *
 277  *    SilcSKRStatus silc_skr_add_public_key_simple(SilcSKR skr,
 278  *                                                 SilcPublicKey public_key,
 279  *                                                 SilcSKRKeyUsage usage,
 280  *                                                 void *key_context,
 281  *                                                 SilcSKRKey *return_key);
 282  *
 283  * DESCRIPTION
 284  *
 285  *    Same as silc_skr_add_public_key but adds only the public key, usage
 286  *    bits and key context.  The key cannot be found with any other search
 287  *    constraint except setting the public key, usage bits and/or key
 288  *    context as search constraint.  This function can be used to add the
 289  *    key with as little memory as possible to the repository, and makes
 290  *    it a good way to cheaply store large amounts of public keys.
 291  *
 292  *    Returns an entry of the added public key in the repository to the
 293  *    `return_key' pointer, if it is non-NULL.  The returned entry remains
 294  *    valid as long as the public key is in the repository, however a
 295  *    reference may be taken with silc_skr_ref_public_key to assure the
 296  *    entry remains valid.
 297  *
 298  *    Returns SILC_SKR_OK if the key was added successfully, and error
 299  *    status if key could not be added, or has been added already.
 300  *
 301  ***/
 302 SilcSKRStatus silc_skr_add_public_key_simple(SilcSKR skr,
 303                                              SilcPublicKey public_key,
 304                                              SilcSKRKeyUsage usage,
 305                                              void *key_context,
 306                                              SilcSKRKey *return_key);
 307
 308 /****f* silcskr/SilcSKRAPI/silc_skr_del_public_key
 309  *
 310  * SYNOPSIS
 311  *
 312  *    SilcSKRStatus silc_skr_del_public_key(SilcSKR skr,
 313  *                                          SilcPublicKey public_key,
 314  *                                          void *key_context);
 315  *
 316  * DESCRIPTION
 317  *
 318  *    Removes and destroyes the public key from the repository.  The
 319  *    public_key will become invalid after this call returns.
 320  *
 321  *    Returns SILC_SKR_OK if the key was added successfully, and error
 322  *    status if key could not be added, or has been added already.
 323  *
 324  ***/
 325 SilcSKRStatus silc_skr_del_public_key(SilcSKR skr,
 326                                       SilcPublicKey public_key,
 327                                       void *key_context);
 328
 329 /****f* silcskr/SilcSKRAPI/silc_skr_ref_public_key
 330  *
 331  * SYNOPSIS
 332  *
 333  *    void silc_skr_ref_public_key(SilcSKR skr, SilcSKRKey key);
 334  *
 335  * DESCRIPTION
 336  *
 337  *    Takes a reference of the public key added to repository indicated
 338  *    by `key'.  The reference must be released by calling the function
 339  *    silc_skr_unref_public_key when it is not needed anymore.
 340  *
 341  ***/
 342 void silc_skr_ref_public_key(SilcSKR skr, SilcSKRKey key);
 343
 344 /****f* silcskr/SilcSKRAPI/silc_skr_unref_public_key
 345  *
 346  * SYNOPSIS
 347  *
 348  *    void silc_skr_unref_public_key(SilcSKR skr, SilcSKRKey key);
 349  *
 350  * DESCRIPTION
 351  *
 352  *    Releases the reference of the public key added to the repository
 353  *    indicated by `key'.  If the released reference is the last reference
 354  *    to the key it will become invalid after this function returns.
 355  *
 356  ***/
 357 void silc_skr_unref_public_key(SilcSKR skr, SilcSKRKey key);
 358
 359 /****f* silcskr/SilcSKRAPI/silc_skr_find_alloc
 360  *
 361  * SYNOPSIS
 362  *
 363  *    SilcSKRFind silc_skr_find_alloc(void);
 364  *
 365  * DESCRIPTION
 366  *
 367  *    Allocates SilcSKRFind context that will hold search constraints used
 368  *    to find specific keys from the repository.  Caller must free the
 369  *    context by calling silc_skr_find_free.
 370  *
 371  ***/
 372 SilcSKRFind silc_skr_find_alloc(void);
 373
 374 /****f* silcskr/SilcSKRAPI/silc_skr_find_free
 375  *
 376  * SYNOPSIS
 377  *
 378  *    void silc_skr_find_free(SilcSKRFind find);
 379  *
 380  * DESCRIPTION
 381  *
 382  *    Free's the search constraints context `find' and all resources in it.
 383  *
 384  ***/
 385 void silc_skr_find_free(SilcSKRFind find);
 386
 387 /****f* silcskr/SilcSKRAPI/silc_skr_find_add_pkcs_type
 388  *
 389  * SYNOPSIS
 390  *
 391  *    SilcBool silc_skr_find_add_pkcs_type(SilcSKRFind find,
 392  *                                         SilcPKCSType type);
 393  *
 394  * DESCRIPTION
 395  *
 396  *    Sets public key cryptosystem type as search constraint.  Will search
 397  *    only for the specific type of key(s).
 398  *
 399  ***/
 400 SilcBool silc_skr_find_set_pkcs_type(SilcSKRFind find, SilcPKCSType type);
 401
 402 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_username
 403  *
 404  * SYNOPSIS
 405  *
 406  *    SilcBool silc_skr_find_set_username(SilcSKRFind find,
 407  *                                        const char *username);
 408  *
 409  * DESCRIPTION
 410  *
 411  *    Sets username as search constraint.  This specific username must be
 412  *    present in the key.
 413  *
 414  *    This may be used with SILC_PKCS_SILC PKCS type only.
 415  *
 416  ***/
 417 SilcBool silc_skr_find_set_username(SilcSKRFind find, const char *username);
 418
 419 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_host
 420  *
 421  * SYNOPSIS
 422  *
 423  *    SilcBool silc_skr_find_set_host(SilcSKRFind find,
 424  *                                    const char *host);
 425  *
 426  * DESCRIPTION
 427  *
 428  *    Sets host as search constraint.  This specific host must be
 429  *    present in the key.  The `host' may be a hostname or IP address.
 430  *
 431  *    This may be used with SILC_PKCS_SILC PKCS type only.
 432  *
 433  ***/
 434 SilcBool silc_skr_find_set_host(SilcSKRFind find, const char *host);
 435
 436 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_realname
 437  *
 438  * SYNOPSIS
 439  *
 440  *    SilcBool silc_skr_find_set_realname(SilcSKRFind find,
 441  *                                        const char *realname);
 442  *
 443  * DESCRIPTION
 444  *
 445  *    Sets real name as search constraint.  This specific name must be
 446  *    present in the key.
 447  *
 448  *    This may be used with SILC_PKCS_SILC PKCS type only.
 449  *
 450  ***/
 451 SilcBool silc_skr_find_set_realname(SilcSKRFind find, const char *realname);
 452
 453 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_email
 454  *
 455  * SYNOPSIS
 456  *
 457  *    SilcBool silc_skr_find_set_email(SilcSKRFind find,
 458  *                                     const char *email);
 459  *
 460  * DESCRIPTION
 461  *
 462  *    Sets email address as search constraint.  This specific address must be
 463  *    present in the key.
 464  *
 465  *    This may be used with SILC_PKCS_SILC PKCS type only.
 466  *
 467  ***/
 468 SilcBool silc_skr_find_set_email(SilcSKRFind find, const char *email);
 469
 470 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_org
 471  *
 472  * SYNOPSIS
 473  *
 474  *    SilcBool silc_skr_find_set_org(SilcSKRFind find,
 475  *                                   const char *email);
 476  *
 477  * DESCRIPTION
 478  *
 479  *    Sets organization as search constraint.  This specific organization
 480  *    must be present in the key.
 481  *
 482  *    This may be used with SILC_PKCS_SILC PKCS type only.
 483  *
 484  ***/
 485 SilcBool silc_skr_find_set_org(SilcSKRFind find, const char *org);
 486
 487 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_country
 488  *
 489  * SYNOPSIS
 490  *
 491  *    SilcBool silc_skr_find_set_country(SilcSKRFind find,
 492  *                                       const char *email);
 493  *
 494  * DESCRIPTION
 495  *
 496  *    Sets country as search constraint.  This specific country must be
 497  *    present in the key.
 498  *
 499  *    This may be used with SILC_PKCS_SILC PKCS type only.
 500  *
 501  ***/
 502 SilcBool silc_skr_find_set_country(SilcSKRFind find, const char *country);
 503
 504 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_public_key
 505  *
 506  * SYNOPSIS
 507  *
 508  *    SilcBool silc_skr_find_set_public_key(SilcSKRFind find,
 509  *                                          SilcPublicKey public_key);
 510  *
 511  * DESCRIPTION
 512  *
 513  *    Sets public key as search constraint.  This specific key must be
 514  *    present in the key.
 515  *
 516  ***/
 517 SilcBool silc_skr_find_set_public_key(SilcSKRFind find,
 518                                       SilcPublicKey public_key);
 519
 520 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_context
 521  *
 522  * SYNOPSIS
 523  *
 524  *    SilcBool silc_skr_find_set_context(SilcSKRFind find, void *context);
 525  *
 526  * DESCRIPTION
 527  *
 528  *    Sets public key specific context as search constraint.  This specific
 529  *    context must be associated with the key.  This is the context that
 530  *    was given as argument when adding the key to repository.
 531  *
 532  ***/
 533 SilcBool silc_skr_find_set_context(SilcSKRFind find, void *context);
 534
 535 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_usage
 536  *
 537  * SYNOPSIS
 538  *
 539  *    SilcBool silc_skr_find_set_usage(SilcSKRFind find,
 540  *                                     SilcSKRKeyUsage usage);
 541  *
 542  * DESCRIPTION
 543  *
 544  *    Sets key usage as search constraint.  At least one of the key usage
 545  *    bits must be present in the key.  This search constraint cannot be
 546  *    used alone to search keys.  At least one other search constraint
 547  *    must also be used.
 548  *
 549  ***/
 550 SilcBool silc_skr_find_set_usage(SilcSKRFind find, SilcSKRKeyUsage usage);
 551
 552 /****f* silcskr/SilcSKRAPI/silc_skr_find
 553  *
 554  * SYNOPSIS
 555  *
 556  *    SilcAsyncOperation silc_skr_find(SilcSKR skr, SilcSchedule schedule,
 557  *                                     SilcSKRFind find,
 558  *                                     SilcSKRFindCallback callback,
 559  *                                     void *callback_context);
 560  *
 561  * DESCRIPTION
 562  *
 563  *    Finds key(s) from key repository `skr' by the search constraints
 564  *    `find'.  As the finding procedure may be asynchronous this returns
 565  *    SilcAsyncOperation that may be used to control (like abort) the
 566  *    operation.  The `callback' with `callback_context' will be called
 567  *    to return found keys.  If this returns NULL the finding was not
 568  *    asynchronous, and the `callback' has been called already.
 569  *
 570  * EXAMPLE
 571  *
 572  *   SilcSKRFind find;
 573  *
 574  *   // Find all SILC public keys originating from Finland
 575  *   find = silc_skr_find_alloc();
 576  *   silc_skr_find_set_pkcs_type(find, SILC_PKCS_SILC);
 577  *   silc_skr_find_set_country(find, "FI");
 578  *
 579  *   // Find
 580  *   silc_skr_find(skr, schedule, find, find_callback, cb_context);
 581  *
 582  ***/
 583 SilcAsyncOperation silc_skr_find(SilcSKR skr, SilcSchedule schedule,
 584                                  SilcSKRFind find,
 585                                  SilcSKRFindCallback callback,
 586                                  void *callback_context);
 587
 588 #include "silcskr_i.h"
 589
 590 #endif /* SILCSKR_H */