1=pod 2 3=head1 NAME 4 5OSSL_PROVIDER_set_default_search_path, 6OSSL_PROVIDER_get0_default_search_path, 7OSSL_PROVIDER, OSSL_PROVIDER_load, OSSL_PROVIDER_try_load, OSSL_PROVIDER_unload, 8OSSL_PROVIDER_load_ex, OSSL_PROVIDER_try_load_ex, 9OSSL_PROVIDER_available, OSSL_PROVIDER_do_all, 10OSSL_PROVIDER_gettable_params, OSSL_PROVIDER_get_params, 11OSSL_PROVIDER_query_operation, OSSL_PROVIDER_unquery_operation, 12OSSL_PROVIDER_get0_provider_ctx, OSSL_PROVIDER_get0_dispatch, 13OSSL_PROVIDER_add_builtin, OSSL_PROVIDER_get0_name, OSSL_PROVIDER_get_capabilities, 14OSSL_PROVIDER_add_conf_parameter, OSSL_PROVIDER_get_conf_parameters, 15OSSL_PROVIDER_conf_get_bool, OSSL_PROVIDER_self_test 16- provider routines 17 18=head1 SYNOPSIS 19 20 #include <openssl/provider.h> 21 22 typedef struct ossl_provider_st OSSL_PROVIDER; 23 24 int OSSL_PROVIDER_set_default_search_path(OSSL_LIB_CTX *libctx, 25 const char *path); 26 const char *OSSL_PROVIDER_get0_default_search_path(OSSL_LIB_CTX *libctx); 27 28 OSSL_PROVIDER *OSSL_PROVIDER_load(OSSL_LIB_CTX *libctx, const char *name); 29 OSSL_PROVIDER *OSSL_PROVIDER_load_ex(OSSL_LIB_CTX *, const char *name, 30 OSSL_PARAM *params); 31 OSSL_PROVIDER *OSSL_PROVIDER_try_load(OSSL_LIB_CTX *libctx, const char *name, 32 int retain_fallbacks); 33 OSSL_PROVIDER *OSSL_PROVIDER_try_load_ex(OSSL_LIB_CTX *, const char *name, 34 OSSL_PARAM *params, 35 int retain_fallbacks); 36 int OSSL_PROVIDER_unload(OSSL_PROVIDER *prov); 37 int OSSL_PROVIDER_available(OSSL_LIB_CTX *libctx, const char *name); 38 int OSSL_PROVIDER_do_all(OSSL_LIB_CTX *ctx, 39 int (*cb)(OSSL_PROVIDER *provider, void *cbdata), 40 void *cbdata); 41 42 const OSSL_PARAM *OSSL_PROVIDER_gettable_params(OSSL_PROVIDER *prov); 43 int OSSL_PROVIDER_get_params(OSSL_PROVIDER *prov, OSSL_PARAM params[]); 44 45 const OSSL_ALGORITHM *OSSL_PROVIDER_query_operation(const OSSL_PROVIDER *prov, 46 int operation_id, 47 int *no_cache); 48 void OSSL_PROVIDER_unquery_operation(const OSSL_PROVIDER *prov, 49 int operation_id, 50 const OSSL_ALGORITHM *algs); 51 void *OSSL_PROVIDER_get0_provider_ctx(const OSSL_PROVIDER *prov); 52 const OSSL_DISPATCH *OSSL_PROVIDER_get0_dispatch(const OSSL_PROVIDER *prov); 53 54 int OSSL_PROVIDER_add_builtin(OSSL_LIB_CTX *libctx, const char *name, 55 ossl_provider_init_fn *init_fn); 56 57 const char *OSSL_PROVIDER_get0_name(const OSSL_PROVIDER *prov); 58 59 int OSSL_PROVIDER_get_capabilities(const OSSL_PROVIDER *prov, 60 const char *capability, 61 OSSL_CALLBACK *cb, 62 void *arg); 63 int OSSL_PROVIDER_add_conf_parameter(OSSL_PROVIDER *prov, const char *name, 64 const char *value); 65 int OSSL_PROVIDER_get_conf_parameters(OSSL_PROVIDER *prov, 66 OSSL_PARAM params[]); 67 int OSSL_PROVIDER_conf_get_bool(const OSSL_PROVIDER *prov, 68 const char *name, int defval); 69 int OSSL_PROVIDER_self_test(const OSSL_PROVIDER *prov); 70 71=head1 DESCRIPTION 72 73B<OSSL_PROVIDER> is a type that holds internal information about 74implementation providers (see L<provider(7)> for information on what a 75provider is). 76A provider can be built in to the application or the OpenSSL 77libraries, or can be a loadable module. 78The functions described here handle both forms. 79 80Some of these functions operate within a library context, please see 81L<OSSL_LIB_CTX(3)> for further details. 82 83=head2 Functions 84 85OSSL_PROVIDER_set_default_search_path() specifies the default search I<path> 86that is to be used for looking for providers in the specified I<libctx>. 87If left unspecified, an environment variable and a fall back default value will 88be used instead. 89 90OSSL_PROVIDER_get0_default_search_path() retrieves the default search I<path> 91that is to be used for looking for providers in the specified I<libctx>. 92If successful returns the path or empty string; the path is valid until the 93context is released or OSSL_PROVIDER_set_default_search_path() is called. 94 95OSSL_PROVIDER_add_builtin() is used to add a built in provider to 96B<OSSL_PROVIDER> store in the given library context, by associating a 97provider name with a provider initialization function. 98This name can then be used with OSSL_PROVIDER_load(). 99 100OSSL_PROVIDER_load() loads and initializes a provider. 101This may simply initialize a provider that was previously added with 102OSSL_PROVIDER_add_builtin() and run its given initialization function, 103or load a provider module with the given name and run its provider 104entry point, C<OSSL_provider_init>. The I<name> can be a path 105to a provider module, in that case the provider name as returned 106by OSSL_PROVIDER_get0_name() will be the path. Interpretation 107of relative paths is platform dependent and they are relative 108to the configured "MODULESDIR" directory or the path set in 109the environment variable OPENSSL_MODULES if set. 110 111OSSL_PROVIDER_try_load() functions like OSSL_PROVIDER_load(), except that 112it does not disable the fallback providers if the provider cannot be 113loaded and initialized or if I<retain_fallbacks> is nonzero. 114If the provider loads successfully and I<retain_fallbacks> is zero, the 115fallback providers are disabled. 116 117OSSL_PROVIDER_load_ex() and OSSL_PROVIDER_try_load_ex() are the variants 118of the previous functions accepting an C<OSSL_PARAM> array of the parameters 119that are passed as the configuration of the loaded provider. The parameters 120of any type but C<OSSL_PARAM_UTF8_STRING> are silently ignored. If the 121parameters are provided, they replace B<all> the ones specified in the 122configuration file. 123 124OSSL_PROVIDER_unload() unloads the given provider. 125For a provider added with OSSL_PROVIDER_add_builtin(), this simply 126runs its teardown function. 127 128OSSL_PROVIDER_available() checks if a named provider is available 129for use. 130 131OSSL_PROVIDER_do_all() iterates over all loaded providers, calling 132I<cb> for each one, with the current provider in I<provider> and the 133I<cbdata> that comes from the caller. If no other provider has been loaded 134before calling this function, the default provider is still available as 135fallback. 136See L<OSSL_PROVIDER-default(7)> for more information on this fallback 137behaviour. 138 139OSSL_PROVIDER_gettable_params() is used to get a provider parameter 140descriptor set as a constant L<OSSL_PARAM(3)> array. 141 142OSSL_PROVIDER_get_params() is used to get provider parameter values. 143The caller must prepare the L<OSSL_PARAM(3)> array before calling this 144function, and the variables acting as buffers for this parameter array 145should be filled with data when it returns successfully. 146 147OSSL_PROVIDER_add_conf_parameter() sets the provider configuration parameter 148I<name> to I<value>. 149Provider configuration parameters are managed by the OpenSSL core and normally 150set in the configuration file, but can also be set early in the main program 151before a provider is in use by multiple threads. 152Parameters that only affect provider initialisation must, for now, be set in 153the configuration file, only parameters that are also queried later have any 154affect when set via this interface. 155Only text parameters can be given, and it's up to the provider to 156interpret them. 157 158OSSL_PROVIDER_get_conf_parameters() retrieves global configuration parameters 159associated with I<prov>. 160These configuration parameters are stored for each provider by the OpenSSL core, 161not the provider itself, parameters managed by the provider are queried via 162B<OSSL_PROVIDER_get_params()> described above. 163The parameters are returned by reference, not as copies, and so the elements of 164the I<param> array must have B<OSSL_PARAM_UTF8_PTR> as their B<data_type>. 165 166OSSL_PROVIDER_conf_get_bool() parses the global configuration parameter I<name> 167associated with provider I<prov> as a boolean value, returning a default value 168I<defval> when unable to retrieve or parse the parameter. 169Parameter values equal (case-insensitively) to C<1>, C<on>, C<yes>, or C<true> 170yield a true (nonzero) result. 171Parameter values equal (case-insensitively) to C<0>, C<off>, C<no>, or C<false> 172yield a false (zero) result. 173 174OSSL_PROVIDER_self_test() is used to run a provider's self tests on demand. 175If the self tests fail then the provider will fail to provide any further 176services and algorithms. L<OSSL_SELF_TEST_set_callback(3)> may be called 177beforehand in order to display diagnostics for the running self tests. 178 179OSSL_PROVIDER_query_operation() calls the provider's I<query_operation> 180function (see L<provider(7)>), if the provider has one. It returns an 181array of I<OSSL_ALGORITHM> for the given I<operation_id> terminated by an all 182NULL OSSL_ALGORITHM entry. This is considered a low-level function that most 183applications should not need to call. 184 185OSSL_PROVIDER_unquery_operation() calls the provider's I<unquery_operation> 186function (see L<provider(7)>), if the provider has one. This is considered a 187low-level function that most applications should not need to call. 188 189OSSL_PROVIDER_get0_provider_ctx() returns the provider context for the given 190provider. The provider context is an opaque handle set by the provider itself 191and is passed back to the provider by libcrypto in various function calls. 192 193OSSL_PROVIDER_get0_dispatch() returns the provider's dispatch table as it was 194returned in the I<out> parameter from the provider's init function. See 195L<provider-base(7)>. 196 197If it is permissible to cache references to this array then I<*no_store> is set 198to 0 or 1 otherwise. If the array is not cacheable then it is assumed to 199have a short lifetime. 200 201OSSL_PROVIDER_get0_name() returns the name of the given provider. 202 203OSSL_PROVIDER_get_capabilities() provides information about the capabilities 204supported by the provider specified in I<prov> with the capability name 205I<capability>. For each capability of that name supported by the provider it 206will call the callback I<cb> and supply a set of L<OSSL_PARAM(3)>s describing the 207capability. It will also pass back the argument I<arg>. For more details about 208capabilities and what they can be used for please see 209L<provider-base(7)/CAPABILTIIES>. 210 211=head1 RETURN VALUES 212 213OSSL_PROVIDER_set_default_search_path(), OSSL_PROVIDER_add(), 214OSSL_PROVIDER_unload(), OSSL_PROVIDER_get_params(), 215OSSL_PROVIDER_add_conf_parameter(), OSSL_PROVIDER_get_conf_parameters() 216and 217OSSL_PROVIDER_get_capabilities() return 1 on success, or 0 on error. 218 219OSSL_PROVIDER_get0_default_search_path() returns a pointer to a path on success, 220or NULL on error or if the path has not previously been set. 221 222OSSL_PROVIDER_load() and OSSL_PROVIDER_try_load() return a pointer to a 223provider object on success, or NULL on error. 224 225OSSL_PROVIDER_do_all() returns 1 if the callback I<cb> returns 1 for every 226provider it is called with, or 0 if any provider callback invocation returns 0; 227callback processing stops at the first callback invocation on a provider 228that returns 0. 229 230OSSL_PROVIDER_available() returns 1 if the named provider is available, 231otherwise 0. 232 233OSSL_PROVIDER_gettable_params() returns a pointer to an array 234of constant L<OSSL_PARAM(3)>, or NULL if none is provided. 235 236OSSL_PROVIDER_get_params() and returns 1 on success, or 0 on error. 237 238OSSL_PROVIDER_query_operation() returns an array of OSSL_ALGORITHM or NULL on 239error. 240 241OSSL_PROVIDER_self_test() returns 1 if the self tests pass, or 0 on error. 242 243=head1 EXAMPLES 244 245This demonstrates how to load the provider module "foo" and ask for 246its build information. 247 248 #include <openssl/params.h> 249 #include <openssl/provider.h> 250 #include <openssl/err.h> 251 252 OSSL_PROVIDER *prov = NULL; 253 const char *build = NULL; 254 OSSL_PARAM request[] = { 255 { "buildinfo", OSSL_PARAM_UTF8_PTR, &build, 0, 0 }, 256 { NULL, 0, NULL, 0, 0 } 257 }; 258 259 if ((prov = OSSL_PROVIDER_load(NULL, "foo")) != NULL 260 && OSSL_PROVIDER_get_params(prov, request)) 261 printf("Provider 'foo' buildinfo: %s\n", build); 262 else 263 ERR_print_errors_fp(stderr); 264 265=head1 SEE ALSO 266 267L<openssl-core.h(7)>, L<OSSL_LIB_CTX(3)>, L<provider(7)> 268 269=head1 HISTORY 270 271The type and functions described here were added in OpenSSL 3.0. 272 273The I<OSSL_PROVIDER_load_ex> and I<OSSL_PROVIDER_try_load_ex> functions were 274added in OpenSSL 3.2. 275 276The 277I<OSSL_PROVIDER_add_conf_parameter>, 278I<OSSL_PROVIDER_get_conf_parameters>, and 279I<OSSL_PROVIDER_conf_get_bool> functions 280were added in OpenSSL 3.5. 281 282=head1 COPYRIGHT 283 284Copyright 2019-2025 The OpenSSL Project Authors. All Rights Reserved. 285 286Licensed under the Apache License 2.0 (the "License"). You may not use 287this file except in compliance with the License. You can obtain a copy 288in the file LICENSE in the source distribution or at 289L<https://www.openssl.org/source/license.html>. 290 291=cut 292