1 /* 2 3 silcskr.h 4 5 Author: Pekka Riikonen <priikone@silcnet.org> 6 7 Copyright (C) 2005 - 2007 Pekka Riikonen 8 9 The contents of this file are subject to one of the Licenses specified 10 in the COPYING file; You may not use this file except in compliance 11 with the License. 12 13 The software distributed under the License is distributed on an "AS IS" 14 basis, in the hope that it will be useful, but WITHOUT WARRANTY OF ANY 15 KIND, either expressed or implied. See the COPYING file for more 16 information. 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 */ 591