diff --git a/doc/designs/prov_loadex.md b/doc/designs/prov_loadex.md index 818f5cce2d..f28f6d2f4d 100644 --- a/doc/designs/prov_loadex.md +++ b/doc/designs/prov_loadex.md @@ -1,12 +1,12 @@ Providers run-time configuration ================================ -Currently any provider run-time activation requires presence of the +Currently any provider run-time activation requires the presence of the initialization parameters in the OpenSSL configuration file. Otherwise the -provider will be activated with some "default" settings, that may or may not +provider will be activated with some default settings, that may or may not work for a particular application. For real-world systems it may require -providing a specially designed OpenSSL config and passing it somehow (e.g. via -environment) that has its obvious drawbacks. +providing a specially designed OpenSSL configuration file and passing it somehow +(e.g. via environment), which has obvious drawbacks. We need a possibility to initialize providers on per-application level according to per-application parameters. It's necessary for example for PKCS#11 @@ -21,23 +21,23 @@ OSSL_PROVIDER *OSSL_PROVIDER_load_ex(OSSL_LIB_CTX *libctx, const char *name, OSSL_PARAM params[]); ``` -intended to configure the provider in load time. +intended to configure the provider at load time. It accepts only parameters of type `OSSL_PARAM_UTF8_STRING` because any provider can be initialized from the config file where the values are represented as strings and provider init function has to deal with it. -Explicitly configured parameters can contradict the parameters named in the +Explicitly configured parameters can differ from the parameters named in the configuration file. Here are the current design decisions and some possible future steps. Real-world cases ---------------- -Many applications use PKCS#11 API with a specific drivers. OpenSSL PKCS#11 +Many applications use PKCS#11 API with specific drivers. OpenSSL PKCS#11 provider also provides a set of -tweaks usable in particular situations. So there are at least several scenarios -I have in mind: +tweaks usable in particular situations. So there are several scenarios for which +the new API can be used: 1. Configure a provider in the config file, activate on demand 2. Load/activate a provider run-time with parameters @@ -45,26 +45,25 @@ I have in mind: Current design -------------- -When the provider is loaded in the current library context and activated, the -currently loaded provider will be returned as the result of -`OSSL_PROVIDER_load_ex` call. +When the provider is already loaded an activated in the current library context, +the `OSSL_PROVIDER_load_ex` call simply returns the active provider and the +extra parameters are ignored. -When the provider is loaded in the current library context and NOT activated, -the parameters provided int the `OSSL_PROVIDER_load_ex` call will have the -preference. +In all other cases, the extra parameters provided by the `OSSL_PROVIDER_load_ex` +call are applied and the values from the config file are ignored. Separate instances of the provider can be loaded in the separate library contexts. -Several instances of the same provider in the same context using different -section names, module names (e.g. via symlinks) and provider names. But unless -the provider does not support some configuration options, the algorithms in +Several instances of the same provider can be loaded in the same context using +different section names, module names (e.g. via symlinks) and provider names. +But unless the provider supports some configuration options, the algorithms in this case will have the same `provider` property and the result of fetching is not determined. We strongly discourage against this trick. -The run-time change of the loaded provider configuration is not supported. If -it is necessary, the calls to `OSSL_PROVIDER_unload` with the following call to -the `OSSL_PROVIDER_load` or `OSSL_PROVIDER_load_ex` should be used. +Changing the loaded provider configuration at runtime is not supported. If +it is necessary, the provider needs to be unloaded using `OSSL_PROVIDER_unload` +and reloaded using `OSSL_PROVIDER_load` or `OSSL_PROVIDER_load_ex` should be used. Possible future steps ---------------------