doc: suggestions for OSSL_PROVIDER_load_ex design document

Late review comments for pull request #21604, sort of.

Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/22029)

1 files changed, 20 insertions, 21 deletions

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 <https://github.com/latchset/pkcs11-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
 ---------------------