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