Home | History | Annotate | Line # | Download | only in designs 
      1 OSSL_PROVIDER_load_ex - activating providers with run-time configuration
      2 ========================================================================
      3 
      4 Currently any provider run-time activation requires the 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 configuration file and passing it somehow
      9 (e.g. via environment), which has 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 at 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 differ from 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 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 several scenarios for which
     40 the new API can be used:
     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 already loaded an activated in the current library context,
     49 the `OSSL_PROVIDER_load_ex` call simply returns the active provider and the
     50 extra parameters are ignored.
     51 
     52 In all other cases, the extra parameters provided by the `OSSL_PROVIDER_load_ex`
     53 call are applied and the values from the config file are ignored.
     54 
     55 Separate instances of the provider can be loaded in the separate library
     56 contexts.
     57 
     58 Several instances of the same provider can be loaded in the same context using
     59 different section names, module names (e.g. via symlinks) and provider names.
     60 But unless the provider supports some configuration options, the algorithms in
     61 this case will have the same `provider` property and the result of fetching is
     62 not determined. We strongly discourage against this trick.
     63 
     64 Changing the loaded provider configuration at runtime is not supported. If
     65 it is necessary, the provider needs to be unloaded using `OSSL_PROVIDER_unload`
     66 and reloaded using `OSSL_PROVIDER_load` or `OSSL_PROVIDER_load_ex` should be used.
     67 
     68 Possible future steps
     69 ---------------------
     70 
     71 1. We should provide some API function accessing the configuration parameters
     72    of a particular provider. Having it, the application will be able to combine
     73    some default values with the app-specific ones in more or less intellectual
     74    way.
     75 
     76 2. We probably should remove the `INFOPAIR` structure and use the `OSSL_PARAM`
     77    one instead.
     78