1=pod 2 3=head1 NAME 4 5ossl_provider_find, ossl_provider_new, ossl_provider_up_ref, 6ossl_provider_free, 7ossl_provider_set_fallback, ossl_provider_set_module_path, 8ossl_provider_add_parameter, ossl_provider_set_child, ossl_provider_get_parent, 9ossl_provider_up_ref_parent, ossl_provider_free_parent, 10ossl_provider_default_props_update, ossl_provider_get0_dispatch, 11ossl_provider_init_as_child, ossl_provider_deinit_child, 12ossl_provider_activate, ossl_provider_deactivate, ossl_provider_add_to_store, 13ossl_provider_ctx, 14ossl_provider_doall_activated, 15ossl_provider_name, ossl_provider_dso, 16ossl_provider_module_name, ossl_provider_module_path, 17ossl_provider_libctx, 18ossl_provider_teardown, ossl_provider_gettable_params, 19ossl_provider_get_params, 20ossl_provider_query_operation, ossl_provider_unquery_operation, 21ossl_provider_set_operation_bit, ossl_provider_test_operation_bit, 22ossl_provider_get_capabilities 23- internal provider routines 24 25=head1 SYNOPSIS 26 27 #include "internal/provider.h" 28 29 OSSL_PROVIDER *ossl_provider_find(OSSL_LIB_CTX *libctx, const char *name, 30 int noconfig); 31 OSSL_PROVIDER *ossl_provider_new(OSSL_LIB_CTX *libctx, const char *name, 32 ossl_provider_init_fn *init_function 33 int noconfig); 34 int ossl_provider_up_ref(OSSL_PROVIDER *prov); 35 void ossl_provider_free(OSSL_PROVIDER *prov); 36 37 /* Setters */ 38 int ossl_provider_set_fallback(OSSL_PROVIDER *prov); 39 int ossl_provider_set_module_path(OSSL_PROVIDER *prov, const char *path); 40 int ossl_provider_add_parameter(OSSL_PROVIDER *prov, const char *name, 41 const char *value); 42 43 /* Child Providers */ 44 int ossl_provider_set_child(OSSL_PROVIDER *prov, 45 const OSSL_CORE_HANDLE *handle); 46 const OSSL_CORE_HANDLE *ossl_provider_get_parent(OSSL_PROVIDER *prov); 47 int ossl_provider_up_ref_parent(OSSL_PROVIDER *prov, int activate); 48 int ossl_provider_free_parent(OSSL_PROVIDER *prov, int deactivate); 49 int ossl_provider_default_props_update(OSSL_LIB_CTX *libctx, 50 const char *props); 51 52 /* 53 * Activate the Provider 54 * If the Provider is a module, the module will be loaded 55 */ 56 int ossl_provider_activate(OSSL_PROVIDER *prov, int upcalls, int aschild); 57 int ossl_provider_deactivate(OSSL_PROVIDER *prov, int removechildren); 58 int ossl_provider_add_to_store(OSSL_PROVIDER *prov, OSSL_PROVIDER **actualprov, 59 int retain_fallbacks); 60 61 /* Return pointer to the provider's context */ 62 void *ossl_provider_ctx(const OSSL_PROVIDER *prov); 63 64 const OSSL_DISPATCH *ossl_provider_get0_dispatch(const OSSL_PROVIDER *prov); 65 66 /* Iterate over all loaded providers */ 67 int ossl_provider_doall_activated(OSSL_LIB_CTX *, 68 int (*cb)(OSSL_PROVIDER *provider, 69 void *cbdata), 70 void *cbdata); 71 72 /* Getters for other library functions */ 73 const char *ossl_provider_name(OSSL_PROVIDER *prov); 74 const DSO *ossl_provider_dso(OSSL_PROVIDER *prov); 75 const char *ossl_provider_module_name(OSSL_PROVIDER *prov); 76 const char *ossl_provider_module_path(OSSL_PROVIDER *prov); 77 OSSL_LIB_CTX *ossl_provider_libctx(const OSSL_PROVIDER *prov); 78 79 /* Thin wrappers around calls to the provider */ 80 void ossl_provider_teardown(const OSSL_PROVIDER *prov); 81 const OSSL_PARAM *ossl_provider_gettable_params(const OSSL_PROVIDER *prov); 82 int ossl_provider_get_params(const OSSL_PROVIDER *prov, OSSL_PARAM params[]); 83 int ossl_provider_get_capabilities(const OSSL_PROVIDER *prov, 84 const char *capability, 85 OSSL_CALLBACK *cb, 86 void *arg); 87 const OSSL_ALGORITHM *ossl_provider_query_operation(const OSSL_PROVIDER *prov, 88 int operation_id, 89 int *no_cache); 90 void ossl_provider_unquery_operation(const OSSL_PROVIDER *prov, 91 int operation_id, 92 const OSSL_ALGORITHM *algs); 93 94 int ossl_provider_set_operation_bit(OSSL_PROVIDER *provider, size_t bitnum); 95 int ossl_provider_test_operation_bit(OSSL_PROVIDER *provider, size_t bitnum, 96 int *result); 97 98 int ossl_provider_init_as_child(OSSL_LIB_CTX *ctx, 99 const OSSL_CORE_HANDLE *handle, 100 const OSSL_DISPATCH *in); 101 void ossl_provider_deinit_child(OSSL_LIB_CTX *ctx); 102 103=head1 DESCRIPTION 104 105I<OSSL_PROVIDER> is a type that holds all the necessary information 106to handle a provider, regardless of if it's built in to the 107application or the OpenSSL libraries, or if it's a loadable provider 108module. 109Instances of this type are commonly referred to as "provider objects". 110 111A provider object is always stored in a set of provider objects 112in the library context. 113 114Provider objects are reference counted. 115 116Provider objects are initially inactive, i.e. they are only recorded 117in the store, but are not used. 118They are activated with the first call to ossl_provider_activate(), 119and are deactivated with the last call to ossl_provider_deactivate(). 120Activation affects a separate counter. 121 122=head2 Functions 123 124ossl_provider_find() finds an existing provider object in the provider 125object store by I<name>. 126The config file will be automatically loaded unless I<noconfig> is set. 127Typically I<noconfig> should be 0. 128We set I<noconfig> to 1 only when calling these functions while processing a 129config file in order to avoid recursively attempting to load the file. 130The provider object it finds has its reference count incremented. 131 132ossl_provider_new() creates a new provider object named I<name> and 133stores it in the provider object store, unless there already is one 134there with the same name. 135If there already is one with the same name, it's returned with its 136reference count incremented. 137The config file will be automatically loaded unless I<noconfig> is set. 138Typically I<noconfig> should be 0. 139We set I<noconfig> to 1 only when calling these functions while processing a 140config file in order to avoid recursively attempting to load the file. 141The reference count of a newly created provider object will always 142be 2; one for being added to the store, and one for the returned 143reference. 144If I<init_function> is NULL, the provider is assumed to be a 145dynamically loadable module, with the symbol B<OSSL_provider_init> as 146its initialisation function. 147If I<init_function> isn't NULL, the provider is assumed to be built 148in, with I<init_function> being the pointer to its initialisation 149function. 150For further description of the initialisation function, see the 151description of ossl_provider_activate() below. 152 153ossl_provider_up_ref() increments the provider object I<prov>'s 154reference count. 155 156ossl_provider_free() decrements the provider object I<prov>'s 157reference count; when it drops to zero, the provider object is assumed 158to have fallen out of use and will be deinitialized (its I<teardown> 159function is called), and the associated module will be unloaded if one 160was loaded, and I<prov> itself will be freed. 161 162ossl_provider_set_fallback() marks an available provider I<prov> as 163fallback. 164Note that after this call, the provider object pointer that was 165used can simply be dropped, but not freed. 166 167ossl_provider_set_module_path() sets the module path to load the 168provider module given the provider object I<prov>. 169This will be used in preference to automatically trying to figure out 170the path from the provider name and the default module directory (more 171on this in L</NOTES>). 172 173ossl_provider_libctx() returns the library context the given 174provider I<prov> is registered in. 175 176ossl_provider_add_parameter() adds a global parameter for the provider 177to retrieve as it sees fit. 178The parameters are a combination of I<name> and I<value>, and the 179provider will use the name to find the value it wants. 180Only text parameters can be given, and it's up to the provider to 181interpret them. 182 183ossl_provider_set_child() marks this provider as a child of a provider in the 184parent library context. I<handle> is the B<OSSL_CORE_HANDLE> object passed to 185the provider's B<OSSL_provider_init> function. 186 187ossl_provider_get_parent() obtains the handle on the parent provider. 188 189ossl_provider_up_ref_parent() increases the reference count on the parent 190provider. If I<activate> is nonzero then the parent provider is also activated. 191 192ossl_provider_free_parent() decreases the reference count on the parent 193provider. If I<deactivate> is nonzero then the parent provider is also 194deactivated. 195 196ossl_provider_default_props_update() is responsible for informing any child 197providers of an update to the default properties. The new properties are 198supplied in the I<props> string. 199 200ossl_provider_activate() "activates" the provider for the given 201provider object I<prov> by incrementing its activation count, flagging 202it as activated, and initializing it if it isn't already initialized. 203Initializing means one of the following: 204 205=over 4 206 207=item * 208 209If an initialization function was given with ossl_provider_new(), that 210function will get called. 211 212=item * 213 214If no initialization function was given with ossl_provider_new(), a 215loadable module with the I<name> that was given to ossl_provider_new() 216will be located and loaded, then the symbol B<OSSL_provider_init> will 217be located in that module, and called. 218 219=back 220 221If I<upcalls> is nonzero then, if this is a child provider, upcalls to the 222parent libctx will be made to inform it of an up-ref. If I<aschild> is nonzero 223then the provider will only be activated if it is a child provider. Otherwise 224no action is taken and ossl_provider_activate() returns success. 225 226ossl_provider_deactivate() "deactivates" the provider for the given 227provider object I<prov> by decrementing its activation count. When 228that count reaches zero, the activation flag is cleared. If the 229I<removechildren> parameter is 0 then no attempt is made to remove any 230associated child providers. 231 232ossl_provider_add_to_store() adds the provider I<prov> to the provider store and 233makes it available to other threads. This will prevent future automatic loading 234of fallback providers, unless I<retain_fallbacks> is true. If a provider of the 235same name already exists in the store then it is not added but this function 236still returns success. On success the I<actualprov> value is populated with a 237pointer to the provider of the given name that is now in the store. The 238reference passed in the I<prov> argument is consumed by this function. A 239reference to the provider that should be used is passed back in the 240I<actualprov> argument. 241 242ossl_provider_ctx() returns a context created by the provider. 243Outside of the provider, it's completely opaque, but it needs to be 244passed back to some of the provider functions. 245 246ossl_provider_get0_dispatch() returns the dispatch table that the provider 247initially returned in the I<out> parameter of its B<OSSL_provider_init> 248function. 249 250ossl_provider_doall_activated() iterates over all the currently 251"activated" providers, and calls I<cb> for each of them. 252If no providers have been "activated" yet, it tries to activate all 253available fallback providers before iterating over them. 254 255ossl_provider_name() returns the name that was given with 256ossl_provider_new(). 257 258ossl_provider_dso() returns a reference to the module, for providers 259that come in the form of loadable modules. 260 261ossl_provider_module_name() returns the filename of the module, for 262providers that come in the form of loadable modules. 263 264ossl_provider_module_path() returns the full path of the module file, 265for providers that come in the form of loadable modules. 266 267ossl_provider_teardown() calls the provider's I<teardown> function, if 268the provider has one. 269 270ossl_provider_gettable_params() calls the provider's I<gettable_params> 271function, if the provider has one. 272It should return an array of I<OSSL_PARAM> to describe all the 273parameters that the provider has for the provider object. 274 275ossl_provider_get_params() calls the provider's parameter request 276responder. 277It should treat the given I<OSSL_PARAM> array as described in 278L<OSSL_PARAM(3)>. 279 280ossl_provider_get_capabilities() calls the provider's I<get_capabilities> function, 281if the provider has one. It provides the name of the I<capability> and a 282callback I<cb> parameter to call for each capability that has a matching name in 283the provider. The callback gets passed OSSL_PARAM details about the capability as 284well as the caller supplied argument I<arg>. 285 286ossl_provider_query_operation() calls the provider's 287I<query_operation> function, if the provider has one. 288It should return an array of I<OSSL_ALGORITHM> for the given 289I<operation_id>. 290 291ossl_provider_unquery_operation() informs the provider that the result of 292ossl_provider_query_operation() is no longer going to be directly accessed and 293that all relevant information has been copied. 294 295ossl_provider_set_operation_bit() registers a 1 for operation I<bitnum> 296in a bitstring that's internal to I<provider>. 297 298ossl_provider_test_operation_bit() checks if the bit operation I<bitnum> 299is set (1) or not (0) in the internal I<provider> bitstring, and sets 300I<*result> to 1 or 0 accorddingly. 301 302ossl_provider_init_as_child() stores in the library context I<ctx> references to 303the necessary upcalls for managing child providers. The I<handle> and I<in> 304parameters are the B<OSSL_CORE_HANDLE> and L<OSSL_DISPATCH(3)> pointers that were 305passed to the provider's B<OSSL_provider_init> function. 306 307ossl_provider_deinit_child() deregisters callbacks from the parent library 308context about provider creation or removal events for the child library context 309I<ctx>. Must only be called if I<ctx> is a child library context. 310 311=head1 NOTES 312 313Locating a provider module happens as follows: 314 315=over 4 316 317=item 1. 318 319If a path was given with ossl_provider_set_module_path(), use that as 320module path. 321Otherwise, use the provider object's name as module path, with 322platform specific standard extensions added. 323 324=item 2. 325 326If the environment variable B<OPENSSL_MODULES> is defined, assume its 327value is a directory specification and merge it with the module path. 328Otherwise, merge the value of the OpenSSL built in macro B<MODULESDIR> 329with the module path. 330 331=back 332 333When this process is done, the result is used when trying to load the 334provider module. 335 336The command C<openssl version -m> can be used to find out the value 337of the built in macro B<MODULESDIR>. 338 339=head1 RETURN VALUES 340 341ossl_provider_find() and ossl_provider_new() return a pointer to a 342provider object (I<OSSL_PROVIDER>) on success, or NULL on error. 343 344ossl_provider_up_ref() returns the value of the reference count after 345it has been incremented. 346 347ossl_provider_free() doesn't return any value. 348 349ossl_provider_doall_activated() returns 1 if the callback was called for all 350activated providers. A return value of 0 means that the callback was not 351called for any activated providers. 352 353ossl_provider_set_module_path(), ossl_provider_set_fallback(), 354ossl_provider_activate(), ossl_provider_activate_leave_fallbacks() and 355ossl_provider_deactivate(), ossl_provider_add_to_store(), 356ossl_provider_default_props_update() return 1 on success, or 0 on error. 357 358ossl_provider_name(), ossl_provider_dso(), 359ossl_provider_module_name(), and ossl_provider_module_path() return a 360pointer to their respective data if it's available, otherwise NULL 361is returned. 362 363ossl_provider_libctx() return a pointer to the library context. 364This may be NULL, and is perfectly valid, as it denotes the default 365global library context. 366 367ossl_provider_teardown() doesn't return any value. 368 369ossl_provider_gettable_params() returns a pointer to a constant 370I<OSSL_PARAM> array if this function is available in the provider, 371otherwise NULL. 372 373ossl_provider_get_params() returns 1 on success, or 0 on error. 374If this function isn't available in the provider, 0 is returned. 375 376ossl_provider_set_operation_bit() and ossl_provider_test_operation_bit() 377return 1 on success, or 0 on error. 378 379ossl_provider_get_capabilities() returns 1 on success, or 0 on error. 380If this function isn't available in the provider or the provider does not 381support the requested capability then 0 is returned. 382 383=head1 SEE ALSO 384 385L<OSSL_PROVIDER(3)>, L<provider(7)>, L<openssl(1)> 386 387=head1 HISTORY 388 389The functions described here were all added in OpenSSL 3.0. 390 391=head1 COPYRIGHT 392 393Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved. 394 395Licensed under the Apache License 2.0 (the "License"). You may not use 396this file except in compliance with the License. You can obtain a copy 397in the file LICENSE in the source distribution or at 398L<https://www.openssl.org/source/license.html>. 399 400=cut 401