lib/silcskr/silcskr.h

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