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