crypto/provider_core.c

   1 /*
   2  * Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
   3  *
   4  * Licensed under the Apache License 2.0 (the "License").  You may not use
   5  * this file except in compliance with the License.  You can obtain a copy
   6  * in the file LICENSE in the source distribution or at
   7  * https://www.openssl.org/source/license.html
   8  */
   9
  10 #include <openssl/core.h>
  11 #include <openssl/core_dispatch.h>
  12 #include <openssl/core_names.h>
  13 #include <openssl/provider.h>
  14 #include <openssl/params.h>
  15 #include <openssl/opensslv.h>
  16 #include "crypto/cryptlib.h"
  17 #include "crypto/evp.h" /* evp_method_store_flush */
  18 #include "crypto/rand.h"
  19 #include "internal/nelem.h"
  20 #include "internal/thread_once.h"
  21 #include "internal/provider.h"
  22 #include "internal/refcount.h"
  23 #include "provider_local.h"
  24 #ifndef FIPS_MODULE
  25 # include <openssl/self_test.h>
  26 #endif
  27
  28 static OSSL_PROVIDER *provider_new(const char *name,
  29                                    OSSL_provider_init_fn *init_function);
  30
  31 /*-
  32  * Provider Object structure
  33  * =========================
  34  */
  35
  36 typedef struct {
  37     char *name;
  38     char *value;
  39 } INFOPAIR;
  40 DEFINE_STACK_OF(INFOPAIR)
  41
  42 struct provider_store_st;        /* Forward declaration */
  43
  44 struct ossl_provider_st {
  45     /* Flag bits */
  46     unsigned int flag_initialized:1;
  47     unsigned int flag_activated:1;
  48     unsigned int flag_fallback:1; /* Can be used as fallback */
  49     unsigned int flag_activated_as_fallback:1;
  50
  51     /* Getting and setting the flags require synchronization */
  52     CRYPTO_RWLOCK *flag_lock;
  53
  54     /* OpenSSL library side data */
  55     CRYPTO_REF_COUNT refcnt;
  56     CRYPTO_RWLOCK *refcnt_lock;  /* For the ref counter */
  57     CRYPTO_REF_COUNT activatecnt;
  58     CRYPTO_RWLOCK *activatecnt_lock; /* For the activate counter */
  59     char *name;
  60     char *path;
  61     DSO *module;
  62     OSSL_provider_init_fn *init_function;
  63     STACK_OF(INFOPAIR) *parameters;
  64     OSSL_LIB_CTX *libctx; /* The library context this instance is in */
  65     struct provider_store_st *store; /* The store this instance belongs to */
  66 #ifndef FIPS_MODULE
  67     /*
  68      * In the FIPS module inner provider, this isn't needed, since the
  69      * error upcalls are always direct calls to the outer provider.
  70      */
  71     int error_lib;     /* ERR library number, one for each provider */
  72 # ifndef OPENSSL_NO_ERR
  73     ERR_STRING_DATA *error_strings; /* Copy of what the provider gives us */
  74 # endif
  75 #endif
  76
  77     /* Provider side functions */
  78     OSSL_FUNC_provider_teardown_fn *teardown;
  79     OSSL_FUNC_provider_gettable_params_fn *gettable_params;
  80     OSSL_FUNC_provider_get_params_fn *get_params;
  81     OSSL_FUNC_provider_get_capabilities_fn *get_capabilities;
  82     OSSL_FUNC_provider_self_test_fn *self_test;
  83     OSSL_FUNC_provider_query_operation_fn *query_operation;
  84     OSSL_FUNC_provider_unquery_operation_fn *unquery_operation;
  85
  86     /*
  87      * Cache of bit to indicate of query_operation() has been called on
  88      * a specific operation or not.
  89      */
  90     unsigned char *operation_bits;
  91     size_t operation_bits_sz;
  92     CRYPTO_RWLOCK *opbits_lock;
  93
  94     /* Provider side data */
  95     void *provctx;
  96 };
  97 DEFINE_STACK_OF(OSSL_PROVIDER)
  98
  99 static int ossl_provider_cmp(const OSSL_PROVIDER * const *a,
 100                              const OSSL_PROVIDER * const *b)
 101 {
 102     return strcmp((*a)->name, (*b)->name);
 103 }
 104
 105 /*-
 106  * Provider Object store
 107  * =====================
 108  *
 109  * The Provider Object store is a library context object, and therefore needs
 110  * an index.
 111  */
 112
 113 struct provider_store_st {
 114     STACK_OF(OSSL_PROVIDER) *providers;
 115     CRYPTO_RWLOCK *lock;
 116     char *default_path;
 117     unsigned int use_fallbacks:1;
 118 };
 119
 120 /*
 121  * provider_deactivate_free() is a wrapper around ossl_provider_deactivate()
 122  * and ossl_provider_free(), called as needed.
 123  * Since this is only called when the provider store is being emptied, we
 124  * don't need to care about any lock.
 125  */
 126 static void provider_deactivate_free(OSSL_PROVIDER *prov)
 127 {
 128     if (prov->flag_activated)
 129         ossl_provider_deactivate(prov);
 130     ossl_provider_free(prov);
 131 }
 132
 133 static void provider_store_free(void *vstore)
 134 {
 135     struct provider_store_st *store = vstore;
 136
 137     if (store == NULL)
 138         return;
 139     OPENSSL_free(store->default_path);
 140     sk_OSSL_PROVIDER_pop_free(store->providers, provider_deactivate_free);
 141     CRYPTO_THREAD_lock_free(store->lock);
 142     OPENSSL_free(store);
 143 }
 144
 145 static void *provider_store_new(OSSL_LIB_CTX *ctx)
 146 {
 147     struct provider_store_st *store = OPENSSL_zalloc(sizeof(*store));
 148     const struct predefined_providers_st *p = NULL;
 149
 150     if (store == NULL
 151         || (store->providers = sk_OSSL_PROVIDER_new(ossl_provider_cmp)) == NULL
 152         || (store->lock = CRYPTO_THREAD_lock_new()) == NULL) {
 153         provider_store_free(store);
 154         return NULL;
 155     }
 156     store->use_fallbacks = 1;
 157
 158     for (p = predefined_providers; p->name != NULL; p++) {
 159         OSSL_PROVIDER *prov = NULL;
 160
 161         /*
 162          * We use the internal constructor directly here,
 163          * otherwise we get a call loop
 164          */
 165         prov = provider_new(p->name, p->init);
 166
 167         if (prov == NULL
 168             || sk_OSSL_PROVIDER_push(store->providers, prov) == 0) {
 169             ossl_provider_free(prov);
 170             provider_store_free(store);
 171             ERR_raise(ERR_LIB_CRYPTO, ERR_R_INTERNAL_ERROR);
 172             return NULL;
 173         }
 174         prov->libctx = ctx;
 175         prov->store = store;
 176 #ifndef FIPS_MODULE
 177         prov->error_lib = ERR_get_next_error_library();
 178 #endif
 179         if(p->is_fallback)
 180             ossl_provider_set_fallback(prov);
 181     }
 182
 183     return store;
 184 }
 185
 186 static const OSSL_LIB_CTX_METHOD provider_store_method = {
 187     provider_store_new,
 188     provider_store_free,
 189 };
 190
 191 static struct provider_store_st *get_provider_store(OSSL_LIB_CTX *libctx)
 192 {
 193     struct provider_store_st *store = NULL;
 194
 195     store = ossl_lib_ctx_get_data(libctx, OSSL_LIB_CTX_PROVIDER_STORE_INDEX,
 196                                   &provider_store_method);
 197     if (store == NULL)
 198         ERR_raise(ERR_LIB_CRYPTO, ERR_R_INTERNAL_ERROR);
 199     return store;
 200 }
 201
 202 int ossl_provider_disable_fallback_loading(OSSL_LIB_CTX *libctx)
 203 {
 204     struct provider_store_st *store;
 205
 206     if ((store = get_provider_store(libctx)) != NULL) {
 207         CRYPTO_THREAD_write_lock(store->lock);
 208         store->use_fallbacks = 0;
 209         CRYPTO_THREAD_unlock(store->lock);
 210         return 1;
 211     }
 212     return 0;
 213 }
 214
 215 OSSL_PROVIDER *ossl_provider_find(OSSL_LIB_CTX *libctx, const char *name,
 216                                   int noconfig)
 217 {
 218     struct provider_store_st *store = NULL;
 219     OSSL_PROVIDER *prov = NULL;
 220
 221     if ((store = get_provider_store(libctx)) != NULL) {
 222         OSSL_PROVIDER tmpl = { 0, };
 223         int i;
 224
 225 #ifndef FIPS_MODULE
 226         /*
 227          * Make sure any providers are loaded from config before we try to find
 228          * them.
 229          */
 230         if (!noconfig)
 231             OPENSSL_init_crypto(OPENSSL_INIT_LOAD_CONFIG, NULL);
 232 #endif
 233
 234         tmpl.name = (char *)name;
 235         CRYPTO_THREAD_write_lock(store->lock);
 236         if ((i = sk_OSSL_PROVIDER_find(store->providers, &tmpl)) == -1
 237             || (prov = sk_OSSL_PROVIDER_value(store->providers, i)) == NULL
 238             || !ossl_provider_up_ref(prov))
 239             prov = NULL;
 240         CRYPTO_THREAD_unlock(store->lock);
 241     }
 242
 243     return prov;
 244 }
 245
 246 /*-
 247  * Provider Object methods
 248  * =======================
 249  */
 250
 251 static OSSL_PROVIDER *provider_new(const char *name,
 252                                    OSSL_provider_init_fn *init_function)
 253 {
 254     OSSL_PROVIDER *prov = NULL;
 255
 256     if ((prov = OPENSSL_zalloc(sizeof(*prov))) == NULL
 257 #ifndef HAVE_ATOMICS
 258         || (prov->refcnt_lock = CRYPTO_THREAD_lock_new()) == NULL
 259         || (prov->activatecnt_lock = CRYPTO_THREAD_lock_new()) == NULL
 260 #endif
 261         || !ossl_provider_up_ref(prov) /* +1 One reference to be returned */
 262         || (prov->opbits_lock = CRYPTO_THREAD_lock_new()) == NULL
 263         || (prov->flag_lock = CRYPTO_THREAD_lock_new()) == NULL
 264         || (prov->name = OPENSSL_strdup(name)) == NULL) {
 265         ossl_provider_free(prov);
 266         ERR_raise(ERR_LIB_CRYPTO, ERR_R_MALLOC_FAILURE);
 267         return NULL;
 268     }
 269
 270     prov->init_function = init_function;
 271     return prov;
 272 }
 273
 274 int ossl_provider_up_ref(OSSL_PROVIDER *prov)
 275 {
 276     int ref = 0;
 277
 278     if (CRYPTO_UP_REF(&prov->refcnt, &ref, prov->refcnt_lock) <= 0)
 279         return 0;
 280     return ref;
 281 }
 282
 283 OSSL_PROVIDER *ossl_provider_new(OSSL_LIB_CTX *libctx, const char *name,
 284                                  OSSL_provider_init_fn *init_function,
 285                                  int noconfig)
 286 {
 287     struct provider_store_st *store = NULL;
 288     OSSL_PROVIDER *prov = NULL;
 289
 290     if ((store = get_provider_store(libctx)) == NULL)
 291         return NULL;
 292
 293     if ((prov = ossl_provider_find(libctx, name,
 294                                    noconfig)) != NULL) { /* refcount +1 */
 295         ossl_provider_free(prov); /* refcount -1 */
 296         ERR_raise_data(ERR_LIB_CRYPTO, CRYPTO_R_PROVIDER_ALREADY_EXISTS,
 297                        "name=%s", name);
 298         return NULL;
 299     }
 300
 301     /* provider_new() generates an error, so no need here */
 302     if ((prov = provider_new(name, init_function)) == NULL)
 303         return NULL;
 304
 305     CRYPTO_THREAD_write_lock(store->lock);
 306     if (!ossl_provider_up_ref(prov)) { /* +1 One reference for the store */
 307         ossl_provider_free(prov); /* -1 Reference that was to be returned */
 308         prov = NULL;
 309     } else if (sk_OSSL_PROVIDER_push(store->providers, prov) == 0) {
 310         ossl_provider_free(prov); /* -1 Store reference */
 311         ossl_provider_free(prov); /* -1 Reference that was to be returned */
 312         prov = NULL;
 313     } else {
 314         prov->libctx = libctx;
 315         prov->store = store;
 316 #ifndef FIPS_MODULE
 317         prov->error_lib = ERR_get_next_error_library();
 318 #endif
 319     }
 320     CRYPTO_THREAD_unlock(store->lock);
 321
 322     if (prov == NULL)
 323         ERR_raise(ERR_LIB_CRYPTO, ERR_R_MALLOC_FAILURE);
 324
 325     /*
 326      * At this point, the provider is only partially "loaded".  To be
 327      * fully "loaded", ossl_provider_activate() must also be called.
 328      */
 329
 330     return prov;
 331 }
 332
 333 static void free_infopair(INFOPAIR *pair)
 334 {
 335     OPENSSL_free(pair->name);
 336     OPENSSL_free(pair->value);
 337     OPENSSL_free(pair);
 338 }
 339
 340 void ossl_provider_free(OSSL_PROVIDER *prov)
 341 {
 342     if (prov != NULL) {
 343         int ref = 0;
 344
 345         CRYPTO_DOWN_REF(&prov->refcnt, &ref, prov->refcnt_lock);
 346
 347         /*
 348          * When the refcount drops to zero, we clean up the provider.
 349          * Note that this also does teardown, which may seem late,
 350          * considering that init happens on first activation.  However,
 351          * there may be other structures hanging on to the provider after
 352          * the last deactivation and may therefore need full access to the
 353          * provider's services.  Therefore, we deinit late.
 354          */
 355         if (ref == 0) {
 356             if (prov->flag_initialized) {
 357 #ifndef FIPS_MODULE
 358                 ossl_init_thread_deregister(prov);
 359 #endif
 360                 if (prov->teardown != NULL)
 361                     prov->teardown(prov->provctx);
 362 #ifndef OPENSSL_NO_ERR
 363 # ifndef FIPS_MODULE
 364                 if (prov->error_strings != NULL) {
 365                     ERR_unload_strings(prov->error_lib, prov->error_strings);
 366                     OPENSSL_free(prov->error_strings);
 367                     prov->error_strings = NULL;
 368                 }
 369 # endif
 370 #endif
 371                 OPENSSL_free(prov->operation_bits);
 372                 prov->operation_bits = NULL;
 373                 prov->operation_bits_sz = 0;
 374                 prov->flag_initialized = 0;
 375             }
 376
 377 #ifndef FIPS_MODULE
 378             DSO_free(prov->module);
 379 #endif
 380             OPENSSL_free(prov->name);
 381             OPENSSL_free(prov->path);
 382             sk_INFOPAIR_pop_free(prov->parameters, free_infopair);
 383             CRYPTO_THREAD_lock_free(prov->opbits_lock);
 384             CRYPTO_THREAD_lock_free(prov->flag_lock);
 385 #ifndef HAVE_ATOMICS
 386             CRYPTO_THREAD_lock_free(prov->refcnt_lock);
 387             CRYPTO_THREAD_lock_free(prov->activatecnt_lock);
 388 #endif
 389             OPENSSL_free(prov);
 390         }
 391     }
 392 }
 393
 394 /* Setters */
 395 int ossl_provider_set_module_path(OSSL_PROVIDER *prov, const char *module_path)
 396 {
 397     OPENSSL_free(prov->path);
 398     if (module_path == NULL)
 399         return 1;
 400     if ((prov->path = OPENSSL_strdup(module_path)) != NULL)
 401         return 1;
 402     ERR_raise(ERR_LIB_CRYPTO, ERR_R_MALLOC_FAILURE);
 403     return 0;
 404 }
 405
 406 int ossl_provider_add_parameter(OSSL_PROVIDER *prov,
 407                                 const char *name, const char *value)
 408 {
 409     INFOPAIR *pair = NULL;
 410
 411     if ((pair = OPENSSL_zalloc(sizeof(*pair))) != NULL
 412         && (prov->parameters != NULL
 413             || (prov->parameters = sk_INFOPAIR_new_null()) != NULL)
 414         && (pair->name = OPENSSL_strdup(name)) != NULL
 415         && (pair->value = OPENSSL_strdup(value)) != NULL
 416         && sk_INFOPAIR_push(prov->parameters, pair) > 0)
 417         return 1;
 418
 419     if (pair != NULL) {
 420         OPENSSL_free(pair->name);
 421         OPENSSL_free(pair->value);
 422         OPENSSL_free(pair);
 423     }
 424     ERR_raise(ERR_LIB_CRYPTO, ERR_R_MALLOC_FAILURE);
 425     return 0;
 426 }
 427
 428 /*
 429  * Provider activation.
 430  *
 431  * What "activation" means depends on the provider form; for built in
 432  * providers (in the library or the application alike), the provider
 433  * can already be considered to be loaded, all that's needed is to
 434  * initialize it.  However, for dynamically loadable provider modules,
 435  * we must first load that module.
 436  *
 437  * Built in modules are distinguished from dynamically loaded modules
 438  * with an already assigned init function.
 439  */
 440 static const OSSL_DISPATCH *core_dispatch; /* Define further down */
 441
 442 int OSSL_PROVIDER_set_default_search_path(OSSL_LIB_CTX *libctx,
 443                                           const char *path)
 444 {
 445     struct provider_store_st *store;
 446     char *p = NULL;
 447
 448     if (path != NULL) {
 449         p = OPENSSL_strdup(path);
 450         if (p == NULL) {
 451             ERR_raise(ERR_LIB_CRYPTO, ERR_R_MALLOC_FAILURE);
 452             return 0;
 453         }
 454     }
 455     if ((store = get_provider_store(libctx)) != NULL
 456             && CRYPTO_THREAD_write_lock(store->lock)) {
 457         OPENSSL_free(store->default_path);
 458         store->default_path = p;
 459         CRYPTO_THREAD_unlock(store->lock);
 460         return 1;
 461     }
 462     OPENSSL_free(p);
 463     return 0;
 464 }
 465
 466 /*
 467  * Internal version that doesn't affect the store flags, and thereby avoid
 468  * locking.  Direct callers must remember to set the store flags when
 469  * appropriate.
 470  */
 471 static int provider_init(OSSL_PROVIDER *prov)
 472 {
 473     const OSSL_DISPATCH *provider_dispatch = NULL;
 474     void *tmp_provctx = NULL;    /* safety measure */
 475 #ifndef OPENSSL_NO_ERR
 476 # ifndef FIPS_MODULE
 477     OSSL_FUNC_provider_get_reason_strings_fn *p_get_reason_strings = NULL;
 478 # endif
 479 #endif
 480     int ok = 0;
 481
 482     /*
 483      * The flag lock is used to lock init, not only because the flag is
 484      * checked here and set at the end, but also because this function
 485      * modifies a number of things in the provider structure that this
 486      * function needs to perform under lock anyway.
 487      */
 488     CRYPTO_THREAD_write_lock(prov->flag_lock);
 489     if (prov->flag_initialized) {
 490         ok = 1;
 491         goto end;
 492     }
 493
 494     /*
 495      * If the init function isn't set, it indicates that this provider is
 496      * a loadable module.
 497      */
 498     if (prov->init_function == NULL) {
 499 #ifdef FIPS_MODULE
 500         goto end;
 501 #else
 502         if (prov->module == NULL) {
 503             char *allocated_path = NULL;
 504             const char *module_path = NULL;
 505             char *merged_path = NULL;
 506             const char *load_dir = NULL;
 507             struct provider_store_st *store;
 508
 509             if ((prov->module = DSO_new()) == NULL) {
 510                 /* DSO_new() generates an error already */
 511                 goto end;
 512             }
 513
 514             if ((store = get_provider_store(prov->libctx)) == NULL
 515                     || !CRYPTO_THREAD_read_lock(store->lock))
 516                 goto end;
 517             load_dir = store->default_path;
 518             CRYPTO_THREAD_unlock(store->lock);
 519
 520             if (load_dir == NULL) {
 521                 load_dir = ossl_safe_getenv("OPENSSL_MODULES");
 522                 if (load_dir == NULL)
 523                     load_dir = MODULESDIR;
 524             }
 525
 526             DSO_ctrl(prov->module, DSO_CTRL_SET_FLAGS,
 527                      DSO_FLAG_NAME_TRANSLATION_EXT_ONLY, NULL);
 528
 529             module_path = prov->path;
 530             if (module_path == NULL)
 531                 module_path = allocated_path =
 532                     DSO_convert_filename(prov->module, prov->name);
 533             if (module_path != NULL)
 534                 merged_path = DSO_merge(prov->module, module_path, load_dir);
 535
 536             if (merged_path == NULL
 537                 || (DSO_load(prov->module, merged_path, NULL, 0)) == NULL) {
 538                 DSO_free(prov->module);
 539                 prov->module = NULL;
 540             }
 541
 542             OPENSSL_free(merged_path);
 543             OPENSSL_free(allocated_path);
 544         }
 545
 546         if (prov->module != NULL)
 547             prov->init_function = (OSSL_provider_init_fn *)
 548                 DSO_bind_func(prov->module, "OSSL_provider_init");
 549 #endif
 550     }
 551
 552     /* Call the initialise function for the provider. */
 553     if (prov->init_function == NULL
 554         || !prov->init_function((OSSL_CORE_HANDLE *)prov, core_dispatch,
 555                                 &provider_dispatch, &tmp_provctx)) {
 556         ERR_raise_data(ERR_LIB_CRYPTO, ERR_R_INIT_FAIL,
 557                        "name=%s", prov->name);
 558 #ifndef FIPS_MODULE
 559         DSO_free(prov->module);
 560         prov->module = NULL;
 561 #endif
 562         goto end;
 563     }
 564     prov->provctx = tmp_provctx;
 565
 566     for (; provider_dispatch->function_id != 0; provider_dispatch++) {
 567         switch (provider_dispatch->function_id) {
 568         case OSSL_FUNC_PROVIDER_TEARDOWN:
 569             prov->teardown =
 570                 OSSL_FUNC_provider_teardown(provider_dispatch);
 571             break;
 572         case OSSL_FUNC_PROVIDER_GETTABLE_PARAMS:
 573             prov->gettable_params =
 574                 OSSL_FUNC_provider_gettable_params(provider_dispatch);
 575             break;
 576         case OSSL_FUNC_PROVIDER_GET_PARAMS:
 577             prov->get_params =
 578                 OSSL_FUNC_provider_get_params(provider_dispatch);
 579             break;
 580         case OSSL_FUNC_PROVIDER_SELF_TEST:
 581             prov->self_test =
 582                 OSSL_FUNC_provider_self_test(provider_dispatch);
 583             break;
 584         case OSSL_FUNC_PROVIDER_GET_CAPABILITIES:
 585             prov->get_capabilities =
 586                 OSSL_FUNC_provider_get_capabilities(provider_dispatch);
 587             break;
 588         case OSSL_FUNC_PROVIDER_QUERY_OPERATION:
 589             prov->query_operation =
 590                 OSSL_FUNC_provider_query_operation(provider_dispatch);
 591             break;
 592         case OSSL_FUNC_PROVIDER_UNQUERY_OPERATION:
 593             prov->unquery_operation =
 594                 OSSL_FUNC_provider_unquery_operation(provider_dispatch);
 595             break;
 596 #ifndef OPENSSL_NO_ERR
 597 # ifndef FIPS_MODULE
 598         case OSSL_FUNC_PROVIDER_GET_REASON_STRINGS:
 599             p_get_reason_strings =
 600                 OSSL_FUNC_provider_get_reason_strings(provider_dispatch);
 601             break;
 602 # endif
 603 #endif
 604         }
 605     }
 606
 607 #ifndef OPENSSL_NO_ERR
 608 # ifndef FIPS_MODULE
 609     if (p_get_reason_strings != NULL) {
 610         const OSSL_ITEM *reasonstrings = p_get_reason_strings(prov->provctx);
 611         size_t cnt, cnt2;
 612
 613         /*
 614          * ERR_load_strings() handles ERR_STRING_DATA rather than OSSL_ITEM,
 615          * although they are essentially the same type.
 616          * Furthermore, ERR_load_strings() patches the array's error number
 617          * with the error library number, so we need to make a copy of that
 618          * array either way.
 619          */
 620         cnt = 0;
 621         while (reasonstrings[cnt].id != 0) {
 622             if (ERR_GET_LIB(reasonstrings[cnt].id) != 0)
 623                 goto end;
 624             cnt++;
 625         }
 626         cnt++;                   /* One for the terminating item */
 627
 628         /* Allocate one extra item for the "library" name */
 629         prov->error_strings =
 630             OPENSSL_zalloc(sizeof(ERR_STRING_DATA) * (cnt + 1));
 631         if (prov->error_strings == NULL)
 632             goto end;
 633
 634         /*
 635          * Set the "library" name.
 636          */
 637         prov->error_strings[0].error = ERR_PACK(prov->error_lib, 0, 0);
 638         prov->error_strings[0].string = prov->name;
 639         /*
 640          * Copy reasonstrings item 0..cnt-1 to prov->error_trings positions
 641          * 1..cnt.
 642          */
 643         for (cnt2 = 1; cnt2 <= cnt; cnt2++) {
 644             prov->error_strings[cnt2].error = (int)reasonstrings[cnt2-1].id;
 645             prov->error_strings[cnt2].string = reasonstrings[cnt2-1].ptr;
 646         }
 647
 648         ERR_load_strings(prov->error_lib, prov->error_strings);
 649     }
 650 # endif
 651 #endif
 652
 653     /* With this flag set, this provider has become fully "loaded". */
 654     prov->flag_initialized = 1;
 655     ok = 1;
 656
 657  end:
 658     CRYPTO_THREAD_unlock(prov->flag_lock);
 659     return ok;
 660 }
 661
 662 static int provider_deactivate(OSSL_PROVIDER *prov)
 663 {
 664     int ref = 0;
 665
 666     if (!ossl_assert(prov != NULL))
 667         return 0;
 668
 669     if (CRYPTO_DOWN_REF(&prov->activatecnt, &ref, prov->activatecnt_lock) <= 0)
 670         return 0;
 671
 672     if (ref < 1) {
 673         CRYPTO_THREAD_write_lock(prov->flag_lock);
 674         prov->flag_activated = 0;
 675         CRYPTO_THREAD_unlock(prov->flag_lock);
 676     }
 677
 678     /* We don't deinit here, that's done in ossl_provider_free() */
 679     return 1;
 680 }
 681
 682 static int provider_activate(OSSL_PROVIDER *prov)
 683 {
 684     int ref = 0;
 685
 686     if (CRYPTO_UP_REF(&prov->activatecnt, &ref, prov->activatecnt_lock) <= 0)
 687         return 0;
 688
 689     if (provider_init(prov)) {
 690         CRYPTO_THREAD_write_lock(prov->flag_lock);
 691         prov->flag_activated = 1;
 692         CRYPTO_THREAD_unlock(prov->flag_lock);
 693
 694         return 1;
 695     }
 696
 697     provider_deactivate(prov);
 698     return 0;
 699 }
 700
 701 int ossl_provider_activate(OSSL_PROVIDER *prov, int retain_fallbacks)
 702 {
 703     if (prov == NULL)
 704         return 0;
 705     if (provider_activate(prov)) {
 706         if (!retain_fallbacks) {
 707             CRYPTO_THREAD_write_lock(prov->store->lock);
 708             prov->store->use_fallbacks = 0;
 709             CRYPTO_THREAD_unlock(prov->store->lock);
 710         }
 711         return 1;
 712     }
 713     return 0;
 714 }
 715
 716 int ossl_provider_deactivate(OSSL_PROVIDER *prov)
 717 {
 718     if (prov == NULL)
 719         return 0;
 720     return provider_deactivate(prov);
 721 }
 722
 723 void *ossl_provider_ctx(const OSSL_PROVIDER *prov)
 724 {
 725     return prov->provctx;
 726 }
 727
 728
 729 static int provider_forall_loaded(struct provider_store_st *store,
 730                                   int *found_activated,
 731                                   int (*cb)(OSSL_PROVIDER *provider,
 732                                             void *cbdata),
 733                                   void *cbdata)
 734 {
 735     int i;
 736     int ret = 1;
 737     int num_provs;
 738
 739     num_provs = sk_OSSL_PROVIDER_num(store->providers);
 740
 741     if (found_activated != NULL)
 742         *found_activated = 0;
 743     for (i = 0; i < num_provs; i++) {
 744         OSSL_PROVIDER *prov =
 745             sk_OSSL_PROVIDER_value(store->providers, i);
 746
 747         if (prov->flag_activated) {
 748             if (found_activated != NULL)
 749                 *found_activated = 1;
 750             if (!(ret = cb(prov, cbdata)))
 751                 break;
 752         }
 753     }
 754
 755     return ret;
 756 }
 757
 758 /*
 759  * This function only does something once when store->use_fallbacks == 1,
 760  * and then sets store->use_fallbacks = 0, so the second call and so on is
 761  * effectively a no-op.
 762  */
 763 static void provider_activate_fallbacks(struct provider_store_st *store)
 764 {
 765     int use_fallbacks;
 766     int num_provs;
 767     int activated_fallback_count = 0;
 768     int i;
 769
 770     CRYPTO_THREAD_read_lock(store->lock);
 771     use_fallbacks = store->use_fallbacks;
 772     CRYPTO_THREAD_unlock(store->lock);
 773     if (!use_fallbacks)
 774         return;
 775
 776     CRYPTO_THREAD_write_lock(store->lock);
 777     /* Check again, just in case another thread changed it */
 778     use_fallbacks = store->use_fallbacks;
 779     if (!use_fallbacks) {
 780         CRYPTO_THREAD_unlock(store->lock);
 781         return;
 782     }
 783
 784     num_provs = sk_OSSL_PROVIDER_num(store->providers);
 785     for (i = 0; i < num_provs; i++) {
 786         OSSL_PROVIDER *prov = sk_OSSL_PROVIDER_value(store->providers, i);
 787
 788         if (ossl_provider_up_ref(prov)) {
 789             if (prov->flag_fallback) {
 790                 if (provider_activate(prov)) {
 791                     prov->flag_activated_as_fallback = 1;
 792                     activated_fallback_count++;
 793                 }
 794             }
 795             ossl_provider_free(prov);
 796         }
 797     }
 798
 799     /*
 800      * We assume that all fallbacks have been added to the store before
 801      * any fallback is activated.
 802      * TODO: We may have to reconsider this, IF we find ourselves adding
 803      * fallbacks after any previous fallback has been activated.
 804      */
 805     if (activated_fallback_count > 0)
 806         store->use_fallbacks = 0;
 807
 808     CRYPTO_THREAD_unlock(store->lock);
 809 }
 810
 811 int ossl_provider_forall_loaded(OSSL_LIB_CTX *ctx,
 812                                 int (*cb)(OSSL_PROVIDER *provider,
 813                                           void *cbdata),
 814                                 void *cbdata)
 815 {
 816     int ret = 1;
 817     struct provider_store_st *store = get_provider_store(ctx);
 818
 819 #ifndef FIPS_MODULE
 820     /*
 821      * Make sure any providers are loaded from config before we try to use
 822      * them.
 823      */
 824     OPENSSL_init_crypto(OPENSSL_INIT_LOAD_CONFIG, NULL);
 825 #endif
 826
 827     if (store != NULL) {
 828         provider_activate_fallbacks(store);
 829
 830         CRYPTO_THREAD_read_lock(store->lock);
 831         /*
 832          * Now, we sweep through all providers
 833          */
 834         ret = provider_forall_loaded(store, NULL, cb, cbdata);
 835
 836         CRYPTO_THREAD_unlock(store->lock);
 837     }
 838
 839     return ret;
 840 }
 841
 842 int ossl_provider_available(OSSL_PROVIDER *prov)
 843 {
 844     if (prov != NULL) {
 845         provider_activate_fallbacks(prov->store);
 846
 847         return prov->flag_activated;
 848     }
 849     return 0;
 850 }
 851
 852 /* Setters of Provider Object data */
 853 int ossl_provider_set_fallback(OSSL_PROVIDER *prov)
 854 {
 855     if (prov == NULL)
 856         return 0;
 857
 858     prov->flag_fallback = 1;
 859     return 1;
 860 }
 861
 862 /* Getters of Provider Object data */
 863 const char *ossl_provider_name(const OSSL_PROVIDER *prov)
 864 {
 865     return prov->name;
 866 }
 867
 868 const DSO *ossl_provider_dso(const OSSL_PROVIDER *prov)
 869 {
 870     return prov->module;
 871 }
 872
 873 const char *ossl_provider_module_name(const OSSL_PROVIDER *prov)
 874 {
 875 #ifdef FIPS_MODULE
 876     return NULL;
 877 #else
 878     return DSO_get_filename(prov->module);
 879 #endif
 880 }
 881
 882 const char *ossl_provider_module_path(const OSSL_PROVIDER *prov)
 883 {
 884 #ifdef FIPS_MODULE
 885     return NULL;
 886 #else
 887     /* FIXME: Ensure it's a full path */
 888     return DSO_get_filename(prov->module);
 889 #endif
 890 }
 891
 892 void *ossl_provider_prov_ctx(const OSSL_PROVIDER *prov)
 893 {
 894     if (prov != NULL)
 895         return prov->provctx;
 896
 897     return NULL;
 898 }
 899
 900 OSSL_LIB_CTX *ossl_provider_libctx(const OSSL_PROVIDER *prov)
 901 {
 902     /* TODO(3.0) just: return prov->libctx; */
 903     return prov != NULL ? prov->libctx : NULL;
 904 }
 905
 906 /* Wrappers around calls to the provider */
 907 void ossl_provider_teardown(const OSSL_PROVIDER *prov)
 908 {
 909     if (prov->teardown != NULL)
 910         prov->teardown(prov->provctx);
 911 }
 912
 913 const OSSL_PARAM *ossl_provider_gettable_params(const OSSL_PROVIDER *prov)
 914 {
 915     return prov->gettable_params == NULL
 916         ? NULL : prov->gettable_params(prov->provctx);
 917 }
 918
 919 int ossl_provider_get_params(const OSSL_PROVIDER *prov, OSSL_PARAM params[])
 920 {
 921     return prov->get_params == NULL
 922         ? 0 : prov->get_params(prov->provctx, params);
 923 }
 924
 925 int ossl_provider_self_test(const OSSL_PROVIDER *prov)
 926 {
 927     int ret;
 928
 929     if (prov->self_test == NULL)
 930         return 1;
 931     ret = prov->self_test(prov->provctx);
 932     if (ret == 0)
 933         evp_method_store_flush(ossl_provider_libctx(prov));
 934     return ret;
 935 }
 936
 937 int ossl_provider_get_capabilities(const OSSL_PROVIDER *prov,
 938                                    const char *capability,
 939                                    OSSL_CALLBACK *cb,
 940                                    void *arg)
 941 {
 942     return prov->get_capabilities == NULL
 943         ? 1 : prov->get_capabilities(prov->provctx, capability, cb, arg);
 944 }
 945
 946 const OSSL_ALGORITHM *ossl_provider_query_operation(const OSSL_PROVIDER *prov,
 947                                                     int operation_id,
 948                                                     int *no_cache)
 949 {
 950     const OSSL_ALGORITHM *res;
 951
 952     if (prov->query_operation == NULL)
 953         return NULL;
 954     res = prov->query_operation(prov->provctx, operation_id, no_cache);
 955 #if defined(OPENSSL_NO_CACHED_FETCH)
 956     /* Forcing the non-caching of queries */
 957     if (no_cache != NULL)
 958         *no_cache = 1;
 959 #endif
 960     return res;
 961 }
 962
 963 void ossl_provider_unquery_operation(const OSSL_PROVIDER *prov,
 964                                      int operation_id,
 965                                      const OSSL_ALGORITHM *algs)
 966 {
 967     if (prov->unquery_operation != NULL)
 968         prov->unquery_operation(prov->provctx, operation_id, algs);
 969 }
 970
 971 int ossl_provider_set_operation_bit(OSSL_PROVIDER *provider, size_t bitnum)
 972 {
 973     size_t byte = bitnum / 8;
 974     unsigned char bit = (1 << (bitnum % 8)) & 0xFF;
 975
 976     CRYPTO_THREAD_write_lock(provider->opbits_lock);
 977     if (provider->operation_bits_sz <= byte) {
 978         unsigned char *tmp = OPENSSL_realloc(provider->operation_bits,
 979                                              byte + 1);
 980
 981         if (tmp == NULL) {
 982             CRYPTO_THREAD_unlock(provider->opbits_lock);
 983             ERR_raise(ERR_LIB_CRYPTO, ERR_R_MALLOC_FAILURE);
 984             return 0;
 985         }
 986         provider->operation_bits = tmp;
 987         memset(provider->operation_bits + provider->operation_bits_sz,
 988                '\0', byte + 1 - provider->operation_bits_sz);
 989         provider->operation_bits_sz = byte + 1;
 990     }
 991     provider->operation_bits[byte] |= bit;
 992     CRYPTO_THREAD_unlock(provider->opbits_lock);
 993     return 1;
 994 }
 995
 996 int ossl_provider_test_operation_bit(OSSL_PROVIDER *provider, size_t bitnum,
 997                                      int *result)
 998 {
 999     size_t byte = bitnum / 8;
1000     unsigned char bit = (1 << (bitnum % 8)) & 0xFF;
1001
1002     if (!ossl_assert(result != NULL)) {
1003         ERR_raise(ERR_LIB_CRYPTO, ERR_R_PASSED_NULL_PARAMETER);
1004         return 0;
1005     }
1006
1007     *result = 0;
1008     CRYPTO_THREAD_read_lock(provider->opbits_lock);
1009     if (provider->operation_bits_sz > byte)
1010         *result = ((provider->operation_bits[byte] & bit) != 0);
1011     CRYPTO_THREAD_unlock(provider->opbits_lock);
1012     return 1;
1013 }
1014
1015 /*-
1016  * Core functions for the provider
1017  * ===============================
1018  *
1019  * This is the set of functions that the core makes available to the provider
1020  */
1021
1022 /*
1023  * This returns a list of Provider Object parameters with their types, for
1024  * discovery.  We do not expect that many providers will use this, but one
1025  * never knows.
1026  */
1027 static const OSSL_PARAM param_types[] = {
1028     OSSL_PARAM_DEFN(OSSL_PROV_PARAM_CORE_VERSION, OSSL_PARAM_UTF8_PTR, NULL, 0),
1029     OSSL_PARAM_DEFN(OSSL_PROV_PARAM_CORE_PROV_NAME, OSSL_PARAM_UTF8_PTR,
1030                     NULL, 0),
1031 #ifndef FIPS_MODULE
1032     OSSL_PARAM_DEFN(OSSL_PROV_PARAM_CORE_MODULE_FILENAME, OSSL_PARAM_UTF8_PTR,
1033                     NULL, 0),
1034 #endif
1035     OSSL_PARAM_END
1036 };
1037
1038 /*
1039  * Forward declare all the functions that are provided aa dispatch.
1040  * This ensures that the compiler will complain if they aren't defined
1041  * with the correct signature.
1042  */
1043 static OSSL_FUNC_core_gettable_params_fn core_gettable_params;
1044 static OSSL_FUNC_core_get_params_fn core_get_params;
1045 static OSSL_FUNC_core_thread_start_fn core_thread_start;
1046 static OSSL_FUNC_core_get_libctx_fn core_get_libctx;
1047 #ifndef FIPS_MODULE
1048 static OSSL_FUNC_core_new_error_fn core_new_error;
1049 static OSSL_FUNC_core_set_error_debug_fn core_set_error_debug;
1050 static OSSL_FUNC_core_vset_error_fn core_vset_error;
1051 static OSSL_FUNC_core_set_error_mark_fn core_set_error_mark;
1052 static OSSL_FUNC_core_clear_last_error_mark_fn core_clear_last_error_mark;
1053 static OSSL_FUNC_core_pop_error_to_mark_fn core_pop_error_to_mark;
1054 #endif
1055
1056 static const OSSL_PARAM *core_gettable_params(const OSSL_CORE_HANDLE *handle)
1057 {
1058     return param_types;
1059 }
1060
1061 static int core_get_params(const OSSL_CORE_HANDLE *handle, OSSL_PARAM params[])
1062 {
1063     int i;
1064     OSSL_PARAM *p;
1065     /*
1066      * We created this object originally and we know it is actually an
1067      * OSSL_PROVIDER *, so the cast is safe
1068      */
1069     OSSL_PROVIDER *prov = (OSSL_PROVIDER *)handle;
1070
1071     if ((p = OSSL_PARAM_locate(params, OSSL_PROV_PARAM_CORE_VERSION)) != NULL)
1072         OSSL_PARAM_set_utf8_ptr(p, OPENSSL_VERSION_STR);
1073     if ((p = OSSL_PARAM_locate(params, OSSL_PROV_PARAM_CORE_PROV_NAME)) != NULL)
1074         OSSL_PARAM_set_utf8_ptr(p, prov->name);
1075
1076 #ifndef FIPS_MODULE
1077     if ((p = OSSL_PARAM_locate(params,
1078                                OSSL_PROV_PARAM_CORE_MODULE_FILENAME)) != NULL)
1079         OSSL_PARAM_set_utf8_ptr(p, ossl_provider_module_path(prov));
1080 #endif
1081
1082     if (prov->parameters == NULL)
1083         return 1;
1084
1085     for (i = 0; i < sk_INFOPAIR_num(prov->parameters); i++) {
1086         INFOPAIR *pair = sk_INFOPAIR_value(prov->parameters, i);
1087
1088         if ((p = OSSL_PARAM_locate(params, pair->name)) != NULL)
1089             OSSL_PARAM_set_utf8_ptr(p, pair->value);
1090     }
1091     return 1;
1092 }
1093
1094 static OPENSSL_CORE_CTX *core_get_libctx(const OSSL_CORE_HANDLE *handle)
1095 {
1096     /*
1097      * We created this object originally and we know it is actually an
1098      * OSSL_PROVIDER *, so the cast is safe
1099      */
1100     OSSL_PROVIDER *prov = (OSSL_PROVIDER *)handle;
1101
1102     return (OPENSSL_CORE_CTX *)ossl_provider_libctx(prov);
1103 }
1104
1105 static int core_thread_start(const OSSL_CORE_HANDLE *handle,
1106                              OSSL_thread_stop_handler_fn handfn)
1107 {
1108     /*
1109      * We created this object originally and we know it is actually an
1110      * OSSL_PROVIDER *, so the cast is safe
1111      */
1112     OSSL_PROVIDER *prov = (OSSL_PROVIDER *)handle;
1113
1114     return ossl_init_thread_start(prov, prov->provctx, handfn);
1115 }
1116
1117 /*
1118  * The FIPS module inner provider doesn't implement these.  They aren't
1119  * needed there, since the FIPS module upcalls are always the outer provider
1120  * ones.
1121  */
1122 #ifndef FIPS_MODULE
1123 /*
1124  * TODO(3.0) These error functions should use |handle| to select the proper
1125  * library context to report in the correct error stack, at least if error
1126  * stacks become tied to the library context.
1127  * We cannot currently do that since there's no support for it in the
1128  * ERR subsystem.
1129  */
1130 static void core_new_error(const OSSL_CORE_HANDLE *handle)
1131 {
1132     ERR_new();
1133 }
1134
1135 static void core_set_error_debug(const OSSL_CORE_HANDLE *handle,
1136                                  const char *file, int line, const char *func)
1137 {
1138     ERR_set_debug(file, line, func);
1139 }
1140
1141 static void core_vset_error(const OSSL_CORE_HANDLE *handle,
1142                             uint32_t reason, const char *fmt, va_list args)
1143 {
1144     /*
1145      * We created this object originally and we know it is actually an
1146      * OSSL_PROVIDER *, so the cast is safe
1147      */
1148     OSSL_PROVIDER *prov = (OSSL_PROVIDER *)handle;
1149
1150     /*
1151      * If the uppermost 8 bits are non-zero, it's an OpenSSL library
1152      * error and will be treated as such.  Otherwise, it's a new style
1153      * provider error and will be treated as such.
1154      */
1155     if (ERR_GET_LIB(reason) != 0) {
1156         ERR_vset_error(ERR_GET_LIB(reason), ERR_GET_REASON(reason), fmt, args);
1157     } else {
1158         ERR_vset_error(prov->error_lib, (int)reason, fmt, args);
1159     }
1160 }
1161
1162 static int core_set_error_mark(const OSSL_CORE_HANDLE *handle)
1163 {
1164     return ERR_set_mark();
1165 }
1166
1167 static int core_clear_last_error_mark(const OSSL_CORE_HANDLE *handle)
1168 {
1169     return ERR_clear_last_mark();
1170 }
1171
1172 static int core_pop_error_to_mark(const OSSL_CORE_HANDLE *handle)
1173 {
1174     return ERR_pop_to_mark();
1175 }
1176 #endif /* FIPS_MODULE */
1177
1178 /*
1179  * Functions provided by the core.
1180  */
1181 static const OSSL_DISPATCH core_dispatch_[] = {
1182     { OSSL_FUNC_CORE_GETTABLE_PARAMS, (void (*)(void))core_gettable_params },
1183     { OSSL_FUNC_CORE_GET_PARAMS, (void (*)(void))core_get_params },
1184     { OSSL_FUNC_CORE_GET_LIBCTX, (void (*)(void))core_get_libctx },
1185     { OSSL_FUNC_CORE_THREAD_START, (void (*)(void))core_thread_start },
1186 #ifndef FIPS_MODULE
1187     { OSSL_FUNC_CORE_NEW_ERROR, (void (*)(void))core_new_error },
1188     { OSSL_FUNC_CORE_SET_ERROR_DEBUG, (void (*)(void))core_set_error_debug },
1189     { OSSL_FUNC_CORE_VSET_ERROR, (void (*)(void))core_vset_error },
1190     { OSSL_FUNC_CORE_SET_ERROR_MARK, (void (*)(void))core_set_error_mark },
1191     { OSSL_FUNC_CORE_CLEAR_LAST_ERROR_MARK,
1192       (void (*)(void))core_clear_last_error_mark },
1193     { OSSL_FUNC_CORE_POP_ERROR_TO_MARK, (void (*)(void))core_pop_error_to_mark },
1194     { OSSL_FUNC_BIO_NEW_FILE, (void (*)(void))BIO_new_file },
1195     { OSSL_FUNC_BIO_NEW_MEMBUF, (void (*)(void))BIO_new_mem_buf },
1196     { OSSL_FUNC_BIO_READ_EX, (void (*)(void))BIO_read_ex },
1197     { OSSL_FUNC_BIO_WRITE_EX, (void (*)(void))BIO_write_ex },
1198     { OSSL_FUNC_BIO_GETS, (void (*)(void))BIO_gets },
1199     { OSSL_FUNC_BIO_PUTS, (void (*)(void))BIO_puts },
1200     { OSSL_FUNC_BIO_CTRL, (void (*)(void))BIO_ctrl },
1201     { OSSL_FUNC_BIO_FREE, (void (*)(void))BIO_free },
1202     { OSSL_FUNC_BIO_VPRINTF, (void (*)(void))BIO_vprintf },
1203     { OSSL_FUNC_BIO_VSNPRINTF, (void (*)(void))BIO_vsnprintf },
1204     { OSSL_FUNC_SELF_TEST_CB, (void (*)(void))OSSL_SELF_TEST_get_callback },
1205     { OSSL_FUNC_GET_ENTROPY, (void (*)(void))ossl_rand_get_entropy },
1206     { OSSL_FUNC_CLEANUP_ENTROPY, (void (*)(void))ossl_rand_cleanup_entropy },
1207     { OSSL_FUNC_GET_NONCE, (void (*)(void))ossl_rand_get_nonce },
1208     { OSSL_FUNC_CLEANUP_NONCE, (void (*)(void))ossl_rand_cleanup_nonce },
1209 #endif
1210     { OSSL_FUNC_CRYPTO_MALLOC, (void (*)(void))CRYPTO_malloc },
1211     { OSSL_FUNC_CRYPTO_ZALLOC, (void (*)(void))CRYPTO_zalloc },
1212     { OSSL_FUNC_CRYPTO_FREE, (void (*)(void))CRYPTO_free },
1213     { OSSL_FUNC_CRYPTO_CLEAR_FREE, (void (*)(void))CRYPTO_clear_free },
1214     { OSSL_FUNC_CRYPTO_REALLOC, (void (*)(void))CRYPTO_realloc },
1215     { OSSL_FUNC_CRYPTO_CLEAR_REALLOC, (void (*)(void))CRYPTO_clear_realloc },
1216     { OSSL_FUNC_CRYPTO_SECURE_MALLOC, (void (*)(void))CRYPTO_secure_malloc },
1217     { OSSL_FUNC_CRYPTO_SECURE_ZALLOC, (void (*)(void))CRYPTO_secure_zalloc },
1218     { OSSL_FUNC_CRYPTO_SECURE_FREE, (void (*)(void))CRYPTO_secure_free },
1219     { OSSL_FUNC_CRYPTO_SECURE_CLEAR_FREE,
1220         (void (*)(void))CRYPTO_secure_clear_free },
1221     { OSSL_FUNC_CRYPTO_SECURE_ALLOCATED,
1222         (void (*)(void))CRYPTO_secure_allocated },
1223     { OSSL_FUNC_OPENSSL_CLEANSE, (void (*)(void))OPENSSL_cleanse },
1224
1225     { 0, NULL }
1226 };
1227 static const OSSL_DISPATCH *core_dispatch = core_dispatch_;