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