doc/designs/prov_loadex.md

   1 Providers run-time configuration
   2 ================================
   3
   4 Currently any provider run-time activation requires presence of the
   5 initialization parameters in the OpenSSL configuration file. Otherwise the
   6 provider will be activated with some "default" settings, that may or may not
   7 work for a particular application. For real-world systems it may require
   8 providing a specially designed OpenSSL config and passing it somehow (e.g. via
   9 environment) that has its obvious drawbacks.
  10
  11 We need a possibility to initialize providers on per-application level
  12 according to per-application parameters. It's necessary for example for PKCS#11
  13 provider (where different applications may use different devices with different
  14 drivers) and will be useful for some other providers. In case of Red Hat it is
  15 also usable for FIPS provider.
  16
  17 OpenSSL 3.2 introduces the API
  18
  19 ```C
  20 OSSL_PROVIDER *OSSL_PROVIDER_load_ex(OSSL_LIB_CTX *libctx, const char *name,
  21                                      OSSL_PARAM params[]);
  22 ```
  23
  24 intended to configure the provider in load time.
  25
  26 It accepts only parameters of type `OSSL_PARAM_UTF8_STRING` because any
  27 provider can be initialized from the config file where the values are
  28 represented as strings and provider init function has to deal with it.
  29
  30 Explicitly configured parameters can contradict the parameters named in the
  31 configuration file. Here are the current design decisions and some possible
  32 future steps.
  33
  34 Real-world cases
  35 ----------------
  36
  37 Many applications use PKCS#11 API with a specific drivers. OpenSSL PKCS#11
  38 provider <https://github.com/latchset/pkcs11-provider> also provides a set of
  39 tweaks usable in particular situations. So there are at least several scenarios
  40 I have in mind:
  41
  42 1. Configure a provider in the config file, activate on demand
  43 2. Load/activate a provider run-time with parameters
  44
  45 Current design
  46 --------------
  47
  48 When the provider is loaded in the current library context and activated, the
  49 currently loaded provider will be returned as the result of
  50 `OSSL_PROVIDER_load_ex` call.
  51
  52 When the provider is loaded in the current library context and NOT activated,
  53 the parameters provided int the `OSSL_PROVIDER_load_ex` call will have the
  54 preference.
  55
  56 Separate instances of the provider can be loaded in the separate library
  57 contexts.
  58
  59 Several instances of the same provider in the same context using different
  60 section names, module names (e.g. via symlinks) and provider names. But unless
  61 the provider does not support some configuration options, the algorithms in
  62 this case will have the same `provider` property and the result of fetching is
  63 not determined. We strongly discourage against this trick.
  64
  65 The run-time change of the loaded provider configuration is not supported. If
  66 it is necessary, the calls to `OSSL_PROVIDER_unload` with the following call to
  67 the `OSSL_PROVIDER_load` or `OSSL_PROVIDER_load_ex` should be used.
  68
  69 Possible future steps
  70 ---------------------
  71
  72 1. We should provide some API function accessing the configuration parameters
  73    of a particular provider. Having it, the application will be able to combine
  74    some default values with the app-specific ones in more or less intellectual
  75    way.
  76
  77 2. We probably should remove the `INFOPAIR` structure and use the `OSSL_PARAM`
  78    one instead.