From 0988de278c2f861e47d63cd284992befa686e4a8 Mon Sep 17 00:00:00 2001 From: "Matthias St. Pierre" Date: Fri, 8 Sep 2023 12:35:57 +0200 Subject: doc: change name of OSSL_PROVIDER_load_ex design document Use dashes instead of underscores, to be more consistent with existing document names. And speaking of consistency, introduce a consistent name transformation, which will scale better when design documents start filling the folder ;-) OSSL_PROVIDER_load_ex -> ossl-provider-load-ex.md Reviewed-by: Dmitry Belyavskiy Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/22029) --- doc/designs/ossl-provider-load-ex.md | 77 ++++++++++++++++++++++++++++++++++++ doc/designs/prov_loadex.md | 77 ------------------------------------ 2 files changed, 77 insertions(+), 77 deletions(-) create mode 100644 doc/designs/ossl-provider-load-ex.md delete mode 100644 doc/designs/prov_loadex.md (limited to 'doc/designs') diff --git a/doc/designs/ossl-provider-load-ex.md b/doc/designs/ossl-provider-load-ex.md new file mode 100644 index 0000000000..62d5c8c327 --- /dev/null +++ b/doc/designs/ossl-provider-load-ex.md @@ -0,0 +1,77 @@ +OSSL_PROVIDER_load_ex - activating providers with run-time configuration +======================================================================== + +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 +work for a particular application. For real-world systems it may require +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 +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 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 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 specific drivers. OpenSSL PKCS#11 +provider also provides a set of +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 + +Current design +-------------- + +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. + +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 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. + +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 +--------------------- + +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. diff --git a/doc/designs/prov_loadex.md b/doc/designs/prov_loadex.md deleted file mode 100644 index f28f6d2f4d..0000000000 --- a/doc/designs/prov_loadex.md +++ /dev/null @@ -1,77 +0,0 @@ -Providers run-time configuration -================================ - -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 -work for a particular application. For real-world systems it may require -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 -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 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 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 specific drivers. OpenSSL PKCS#11 -provider also provides a set of -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 - -Current design --------------- - -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. - -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 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. - -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 ---------------------- - -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. -- cgit v1.2.3