diff options
author | Dmitry Belyavskiy <beldmit@gmail.com> | 2023-08-15 14:46:26 +0200 |
---|---|---|
committer | Dmitry Belyavskiy <beldmit@gmail.com> | 2023-08-30 21:55:47 +0200 |
commit | 9f5102bffc8bb3a9b02a0a5e3c1de4326622fe04 (patch) | |
tree | 29a08b78d46bf3359a5c0d03d38d47c230d6bd2e /doc | |
parent | 4f3e3d9d3cb9632a8263cfe27ff11f342bf93351 (diff) | |
download | openssl-9f5102bffc8bb3a9b02a0a5e3c1de4326622fe04.tar.gz |
Design document of the run-time parameters activation
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tim Hudson <tjh@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/21604)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/designs/prov_loadex.md | 78 |
1 files changed, 78 insertions, 0 deletions
diff --git a/doc/designs/prov_loadex.md b/doc/designs/prov_loadex.md new file mode 100644 index 0000000000..818f5cce2d --- /dev/null +++ b/doc/designs/prov_loadex.md @@ -0,0 +1,78 @@ +Providers run-time configuration +================================ + +Currently any provider run-time activation requires 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 +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. + +We need a possibility to initialize providers on per-application level +according to per-application parameters. It's necessary for example for PKCS#11 +provider (where different applications may use different devices with different +drivers) and will be useful for some other providers. In case of Red Hat it is +also usable for FIPS provider. + +OpenSSL 3.2 introduces the API + +```C +OSSL_PROVIDER *OSSL_PROVIDER_load_ex(OSSL_LIB_CTX *libctx, const char *name, + OSSL_PARAM params[]); +``` + +intended to configure the provider in 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 +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 +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: + +1. Configure a provider in the config file, activate on demand +2. Load/activate a provider run-time with parameters + +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 loaded in the current library context and NOT activated, +the parameters provided int the `OSSL_PROVIDER_load_ex` call will have the +preference. + +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 +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. + +Possible future steps +--------------------- + +1. We should provide some API function accessing the configuration parameters + of a particular provider. Having it, the application will be able to combine + some default values with the app-specific ones in more or less intellectual + way. + +2. We probably should remove the `INFOPAIR` structure and use the `OSSL_PARAM` + one instead. |