Latest update

doc/internal/man3/evp_generic_fetch.pod

@@ -13,7 +13,7 @@ evp_generic_fetch - generic algorithm fetcher and method creator for EVP
                          const char *name, const char *properties,
                          void *(*new_method)(const OSSL_DISPATCH *fns,
                                              OSSL_PROVIDER *prov),
-                         int (*upref_method)(void *),
+                         int (*up_ref_method)(void *),
                          void (*free_method)(void *));
 
 =head1 DESCRIPTION
@@ -21,7 +21,7 @@ evp_generic_fetch - generic algorithm fetcher and method creator for EVP
 evp_generic_fetch() calls ossl_method_construct() with the given
 C<libctx>, C<operation_id>, C<name>, and C<properties> and uses
 it to create an EVP method with the help of the functions
-C<new_method>, C<upref_method>, and C<free_method>.
+C<new_method>, C<up_ref_method>, and C<free_method>.
 
 The three functions are supposed to:
 
@@ -32,7 +32,7 @@ The three functions are supposed to:
 creates an internal method from function pointers found in the
 dispatch table C<fns>.
 
-=item upref_method()
+=item up_ref_method()
 
 increments the reference counter for the given method, if there is
 one.
@@ -116,7 +116,7 @@ And here's the implementation of the FOO method fetcher:
         }
         foo->prov = prov;
         if (prov)
-            ossl_provider_upref(prov);
+            ossl_provider_up_ref(prov);
 
         return foo;
     }
@@ -137,7 +137,7 @@ And here's the implementation of the FOO method fetcher:
         return EVP_FOO_meth_from_dispatch(fns, prov);
     }
 
-    static int foo_upref(void *vfoo)
+    static int foo_up_ref(void *vfoo)
     {
         EVP_FOO *foo = vfoo;
         int ref = 0;
@@ -157,7 +157,7 @@ And here's the implementation of the FOO method fetcher:
     {
         EVP_FOO *foo =
             evp_generic_fetch(ctx, OSSL_OP_FOO, name, properties,
-                              foo_from_dispatch, foo_upref, foo_free);
+                              foo_from_dispatch, foo_up_ref, foo_free);
 
         /*
          * If this method exists in legacy form, with a constant NID for the

doc/internal/man3/openssl_ctx_get_data.pod

@@ -29,7 +29,7 @@ as a C<CRYPTO_EX_DATA>, which allows data from diverse parts of the
 library to be added and removed dynamically.
 Each such data item must have a corresponding CRYPTO_EX_DATA index
 associated with it. Unlike normal CRYPTO_EX_DATA objects we use static indexes
-to identify data items. These are mapped transparetnly to CRYPTO_EX_DATA dynamic
+to identify data items. These are mapped transparently to CRYPTO_EX_DATA dynamic
 indexes internally to the implementation.
 See the example further down to see how that's done.
 

doc/internal/man3/ossl_init_thread_deregister.pod

@@ -0,0 +1,66 @@
+=pod
+
+=head1 NAME
+
+OSSL_thread_stop_handler_fn,
+ossl_init_thread_start,
+ossl_init_thread_deregister
+- internal thread routines
+
+=head1 SYNOPSIS
+
+ #include "internal/cryptlib_int.h"
+ #include <openssl/core.h>
+
+ typedef void (*OSSL_thread_stop_handler_fn)(void *arg);
+
+ int ossl_init_thread_start(const void *index, void *arg,
+                            OSSL_thread_stop_handler_fn handfn);
+ int ossl_init_thread_deregister(void *index);
+
+=head1 DESCRIPTION
+
+Thread aware code may be informed about when a thread is stopping, typically to
+perform some cleanup operation.
+Thread stop events may be detected by OpenSSL either automatically (using the
+capabilities of the underlying threading library) where possible or explicitly
+by the application calling OPENSSL_thread_stop() or OPENSSL_thread_stop_ex().
+
+Thread aware code registers a "stop handler" for each new thread that it uses.
+Typically, when a new thread is being used, code will add a new value to some
+thread local variable and then register a stop handler. When the thread is
+stopping the stop handler is called (while on that thread) and the code can
+clean up the value stored in the thread local variable.
+
+A new stop handler is registerd using the function ossl_init_thread_start().
+The B<index> parameter should be a unique value that can be used to identify a
+set of common stop handlers and is passed in a later call to
+ossl_init_thread_deregister. If no later call to ossl_init_thread_deregister is
+made then NULL can be passed for this parameter. The B<arg> parameter is passed
+back as an argument to the stop handler when it is later invoked. Finally the
+B<handfn> is a function pointer to the stop handler itself.
+
+In the event that previously registered stop handlers need to be deregistered
+then this can be done using the function ossl_init_thread_deregister().
+This will deregister all stop handlers (no matter which thread they were
+registered for) which the same B<index> value.
+
+=head1 RETURN VALUES
+
+ossl_init_thread_start() and ossl_init_thread_deregister() return 1 for success
+or 0 on error.
+
+=head1 HISTORY
+
+The functions described here were all added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut

doc/internal/man3/ossl_method_construct.pod

@@ -15,11 +15,13 @@ OSSL_METHOD_CONSTRUCT_METHOD, ossl_method_construct
      /* Remove a store */
      void (*dealloc_tmp_store)(void *store);
      /* Get an already existing method from a store */
-     void *(*get)(OPENSSL_CTX *libctx, void *store, const char *name,
-                  const char *propquery, void *data);
+     void *(*get)(OPENSSL_CTX *libctx, void *store,
+                  int operation_id, const char *name, const char *propquery,
+                  void *data);
      /* Store a method in a store */
      int (*put)(OPENSSL_CTX *libctx, void *store, void *method,
-                const char *name, const char *propdef, void *data);
+                int operation_id, const char *name, const char *propdef,
+                void *data);
      /* Construct a new method */
      void *(*construct)(const char *name, const OSSL_DISPATCH *fns,
                         OSSL_PROVIDER *prov, void *data);
@@ -41,13 +43,25 @@ on provider dispatch tables need to do so in exactly the same way.
 ossl_method_construct() does this while leaving it to the sub-systems
 to define more precisely how the methods are created, stored, etc.
 
+It's important to keep in mind that a method is identified by three things:
+
+=over 4
+
+=item The operation identity
+
+=item The name of the algorithm
+
+=item The properties associated with the algorithm implementation
+
+=back
+
 =head2 Functions
 
 ossl_method_construct() creates a method by asking all available
-providers for a dispatch table given an C<operation_id>, an algorithm
-C<name> and a set of C<properties>, and then calling appropriate
+providers for a dispatch table given an I<operation_id>, an algorithm
+I<name> and a set of I<properties>, and then calling the appropriate
 functions given by the sub-system specific method creator through
-C<mcm> and the data in C<mcm_data> (which is passed by
+I<mcm> and the data in I<mcm_data> (which is passed by
 ossl_method_construct()).
 
 This function assumes that the sub-system method creator implements
@@ -59,14 +73,14 @@ appropriate).
 
 A central part of constructing a sub-system specific method is to give
 ossl_method_construct a set of functions, all in the
-C<OSSL_METHOD_CONSTRUCT_METHOD> structure, which holds the following
+B<OSSL_METHOD_CONSTRUCT_METHOD> structure, which holds the following
 function pointers:
 
 =over 4
 
 =item alloc_tmp_store()
 
-Create a temporary method store in the scope of the library context C<ctx>.
+Create a temporary method store in the scope of the library context I<ctx>.
 This store is used to temporarily store methods for easier lookup, for
 when the provider doesn't want its dispatch table stored in a longer
 term cache.
@@ -79,50 +93,51 @@ Remove a temporary store.
 
 Look up an already existing method from a store by name.
 
-The store may be given with C<store>.
+The store may be given with I<store>.
 B<NULL> is a valid value and means that a sub-system default store
 must be used.
-This default store should be stored in the library context C<libctx>.
+This default store should be stored in the library context I<libctx>.
 
-The method to be looked up should be identified with the given C<name> and
-data from C<data>
-(which is the C<mcm_data> that was passed to ossl_construct_method())
-and the provided property query C<propquery>.
+The method to be looked up should be identified with the given
+I<operation_id>, I<name>, the provided property query I<propquery>
+and data from I<data> (which is the I<mcm_data> that was passed to
+ossl_construct_method()).
 
 This function is expected to increment the method's reference count.
 
 =item put()
 
-Places the C<method> created by the construct() function (see below)
+Places the I<method> created by the construct() function (see below)
 in a store.
 
-The store may be given with C<store>.
+The store may be given with I<store>.
 B<NULL> is a valid value and means that a sub-system default store
 must be used.
-This default store should be stored in the library context C<libctx>.
+This default store should be stored in the library context I<libctx>.
 
-The method should be associated with the given C<name> and property definition
-C<propdef> as well as any identification data given through C<data> (which is
-the C<mcm_data> that was passed to ossl_construct_method()).
+The method should be associated with the given I<operation_id>,
+I<name> and property definition I<propdef> as well as any
+identification data given through I<data> (which is the I<mcm_data>
+that was passed to ossl_construct_method()).
 
-This function is expected to increment the C<method>'s reference count.
+This function is expected to increment the I<method>'s reference count.
 
 =item construct()
 
-Constructs a sub-system method for the given C<name> and the given
-dispatch table C<fns>.
+Constructs a sub-system method for the given I<name> and the given
+dispatch table I<fns>.
 
-The associated I<provider object> C<prov> is passed as well, to make
+The associated provider object I<prov> is passed as well, to make
 it possible for the sub-system constructor to keep a reference, which
 is recommended.
 If such a reference is kept, the I<provider object> reference counter
-must be incremented, using ossl_provider_upref().
+must be incremented, using ossl_provider_up_ref().
 
 This function is expected to set the method's reference count to 1.
 
-=item desctruct()
+=item destruct()
 
-Decrement the C<method>'s reference count, and destruct it when
+Decrement the I<method>'s reference count, and destruct it when
 the reference count reaches zero.
 
 =back

doc/internal/man3/ossl_namemap_new.pod

@@ -3,7 +3,7 @@
 =head1 NAME
 
 ossl_namemap_new, ossl_namemap_free, ossl_namemap_stored,
-ossl_namemap_add, ossl_namemap_name, ossl_namemap_number
+ossl_namemap_add, ossl_namemap_name2num, ossl_namemap_doall_names
 - internal number E<lt>-E<gt> name map
 
 =head1 SYNOPSIS
@@ -15,15 +15,18 @@ ossl_namemap_add, ossl_namemap_name, ossl_namemap_number
  OSSL_NAMEMAP *ossl_namemap_new(void);
  void ossl_namemap_free(OSSL_NAMEMAP *namemap);
 
- int ossl_namemap_add(OSSL_NAMEMAP *namemap, const char *name);
- const char *ossl_namemap_name(const OSSL_NAMEMAP *namemap, int number);
- int ossl_namemap_number(const OSSL_NAMEMAP *namemap, const char *name);
+ int ossl_namemap_add(OSSL_NAMEMAP *namemap, int number, const char *name);
+
+ int ossl_namemap_name2num(const OSSL_NAMEMAP *namemap, const char *name);
+ void ossl_namemap_doall_names(const OSSL_NAMEMAP *namemap, int number,
+                               void (*fn)(const char *name, void *data),
+                               void *data);
 
 =head1 DESCRIPTION
 
-A B<OSSL_NAMEMAP> is a simple number E<lt>-E<gt> name map, which can
-be used to give any arbitrary name (any string) a unique dynamic
-identity that is valid throughout the lifetime of the associated
+A B<OSSL_NAMEMAP> is a one-to-many number E<lt>-E<gt> names map, which
+can be used to give any arbitrary set of names (any string) a unique
+dynamic identity that is valid throughout the lifetime of the associated
 library context.
 
 ossl_namemap_new() and ossl_namemap_free() construct and destruct a
@@ -38,11 +41,19 @@ ossl_namemap_free().
 
 ossl_namemap_add() adds a new name to the namemap if it's not already
 present.
+If the given I<number> is zero, a new number will be allocated to
+identify this I<name>.
+If the given I<number> is non-zero, the I<name> is added to the set of
+names already associated with that number.
 
-ossl_namemap_name() finds the name corresponding to the given number.
+ossl_namemap_name2num() finds the number corresponding to the given
+I<name>.
 
-ossl_namemap_number() finds the number corresponding to the given
-name.
+ossl_namemap_doall_names() walks through all names associated with
+I<number> in the given I<namemap> and calls the function I<fn> for
+each of them.
+I<fn> is also passed the I<data> argument, which allows any caller to
+pass extra data for that function to use.
 
 =head1 RETURN VALUES
 
@@ -52,12 +63,21 @@ B<OSSL_NAMEMAP>, or NULL on error.
 ossl_namemap_add() returns the number associated with the added
 string, or zero on error.
 
-ossl_namemap_name() returns a pointer to the name corresponding to the
-given number, or NULL if it's undefined in the given B<OSSL_NAMEMAP>.
+ossl_namemap_num2names() returns a pointer to a NULL-terminated list of
+pointers to the names corresponding to the given number, or NULL if
+it's undefined in the given B<OSSL_NAMEMAP>.
 
-ossl_namemap_number() returns the number corresponding to the given
+ossl_namemap_name2num() returns the number corresponding to the given
 name, or 0 if it's undefined in the given B<OSSL_NAMEMAP>.
 
+=head1 NOTES
+
+The result from ossl_namemap_num2names() isn't thread safe, other threads
+dealing with the same namemap may cause the list of names to change
+location.
+It is therefore strongly recommended to only use the result in code
+guarded by a thread lock.
+
 =head1 HISTORY
 
 The functions described here were all added in OpenSSL 3.0.

doc/internal/man3/ossl_prov_util_nid_to_name.pod

@@ -0,0 +1,35 @@
+=pod
+
+=head1 NAME
+
+ossl_prov_util_nid_to_name
+- provider utility functions
+
+=head1 SYNOPSIS
+
+ #include "internal/providercommon.h"
+
+ const char *ossl_prov_util_nid_to_name(int nid);
+
+=head1 DESCRIPTION
+
+The ossl_prov_util_nid_to_name() returns the name of an algorithm given a NID
+in the B<nid> parameter. For the default and legacy providers it is equivalent
+to calling OBJ_nid2sn(). The FIPS provider does not have the object database
+code available to it (because that code relies on the ASN.1 code), so this
+function is a static lookup of all known FIPS algorithm NIDs.
+
+=head1 RETURN VALUES
+
+Returns a pointer to the algorithm name, or NULL on error.
+
+=head1 COPYRIGHT
+
+Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut

doc/internal/man3/ossl_provider_add_conf_module.pod

@@ -0,0 +1,41 @@
+=pod
+
+=head1 NAME
+
+ossl_provider_add_conf_module - internal standard configuration module
+
+=head1 SYNOPSIS
+
+ #include "internal/provider.h"
+
+ /* Configuration */
+ void ossl_provider_add_conf_module(void);
+
+=head1 DESCRIPTION
+
+ossl_provider_add_conf_module() adds the standard configuration module
+for providers.
+This allows providers to be configured with an OpenSSL L<config(5)> file.
+
+=head1 RETURN VALUES
+
+ossl_provider_add_conf_module() doesn't return any value.
+
+=head1 SEE ALSO
+
+L<OSSL_PROVIDER(3)>, L<ossl_provider_new(3)>
+
+=head1 HISTORY
+
+The functions described here were all added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut

doc/internal/man3/ossl_provider_new.pod

@@ -2,10 +2,13 @@
 
 =head1 NAME
 
-ossl_provider_find, ossl_provider_new, ossl_provider_upref,
-ossl_provider_free, ossl_provider_add_module_location,
-ossl_provider_set_fallback, ossl_provider_activate,
-ossl_provider_ctx, ossl_provider_forall_loaded,
+ossl_provider_find, ossl_provider_new, ossl_provider_up_ref,
+ossl_provider_free,
+ossl_provider_set_fallback, ossl_provider_set_module_path,
+ossl_provider_add_parameter,
+ossl_provider_activate,
+ossl_provider_ctx,
+ossl_provider_forall_loaded,
 ossl_provider_name, ossl_provider_dso,
 ossl_provider_module_name, ossl_provider_module_path,
 ossl_provider_teardown, ossl_provider_get_param_types,
@@ -19,12 +22,14 @@ ossl_provider_get_params, ossl_provider_query_operation
  OSSL_PROVIDER *ossl_provider_find(OPENSSL_CTX *libctx, const char *name);
  OSSL_PROVIDER *ossl_provider_new(OPENSSL_CTX *libctx, const char *name,
                                   ossl_provider_init_fn *init_function);
- int ossl_provider_upref(OSSL_PROVIDER *prov);
+ int ossl_provider_up_ref(OSSL_PROVIDER *prov);
  void ossl_provider_free(OSSL_PROVIDER *prov);
 
  /* Setters */
- int ossl_provider_add_module_location(OSSL_PROVIDER *prov, const char *loc);
  int ossl_provider_set_fallback(OSSL_PROVIDER *prov);
+ int ossl_provider_set_module_path(OSSL_PROVIDER *prov, const char *path);
+ int ossl_provider_add_parameter(OSSL_PROVIDER *prov, const char *name,
+                                 const char *value);
 
  /* Load and initialize the Provider */
  int ossl_provider_activate(OSSL_PROVIDER *prov);
@@ -47,65 +52,84 @@ ossl_provider_get_params, ossl_provider_query_operation
  /* Thin wrappers around calls to the provider */
  void ossl_provider_teardown(const OSSL_PROVIDER *prov);
  const OSSL_ITEM *ossl_provider_get_param_types(const OSSL_PROVIDER *prov);
- int ossl_provider_get_params(const OSSL_PROVIDER *prov,
-                              const OSSL_PARAM params[]);
+ int ossl_provider_get_params(const OSSL_PROVIDER *prov, OSSL_PARAM params[]);
  const OSSL_ALGORITHM *ossl_provider_query_operation(const OSSL_PROVIDER *prov,
                                                      int operation_id,
                                                      int *no_cache);
 
 =head1 DESCRIPTION
 
-C<OSSL_PROVIDER> is a type that holds all the necessary information
+I<OSSL_PROVIDER> is a type that holds all the necessary information
 to handle a provider, regardless of if it's built in to the
 application or the OpenSSL libraries, or if it's a loadable provider
 module.
-Instances of this type are commonly refered to as I<provider object>s.
+Instances of this type are commonly referred to as "provider objects".
 
-A I<provider object> is always stored in a set of I<provider object>s
+A provider object is always stored in a set of provider objects
 in the library context.
 
-I<provider object>s are reference counted.
+Provider objects are reference counted.
 
-I<provider object>s are initially inactive, i.e. they are only
-recorded in the store, but are not used.
+Provider objects are initially inactive, i.e. they are only recorded
+in the store, but are not used.
 They are activated with the first call to ossl_provider_activate(),
 and are inactivated when ossl_provider_free() has been called as many
 times as ossl_provider_activate() has.
 
 =head2 Functions
 
-ossl_provider_find() finds an existing I<provider object> in the
-I<provider object> store by C<name>.
-The I<provider object> it finds gets its reference count
-incremented.
+ossl_provider_find() finds an existing provider object in the provider
+object store by I<name>. 
+The provider object it finds has its reference count incremented.
 
-ossl_provider_new() creates a new I<provider object> and stores it in
-the I<provider object> store, unless there already is one there with
-the same name.
-The reference counter of a newly created I<provider object> will
-always be 2; one for being added to the store, and one for the
-returned reference.
-To indicate a built-in provider, the C<init_function> argument must
-point at the provider initialization function for that provider.
+ossl_provider_new() creates a new provider object named I<name> and
+stores it in the provider object store, unless there already is one
+there with the same name.
+If there already is one with the same name, it's returned with its
+reference count incremented.
+The reference count of a newly created provider object will always
+be 2; one for being added to the store, and one for the returned
+reference.
+If I<init_function> is NULL, the provider is assumed to be a
+dynamically loadable module, with the symbol B<OSSL_provider_init> as
+its initialisation function.
+If I<init_function> isn't NULL, the provider is assumed to be built
+in, with I<init_function> being the pointer to its initialisation
+function.
+For further description of the initialisation function, see the
+description of ossl_provider_activate() below.
 
-ossl_provider_free() decrements a I<provider object>'s reference
-counter; if it drops below 2, the I<provider object> is assumed to
-have fallen out of use and will be inactivated (its teardown function
-is called); if it drops down to zero, the I<provider object> is
-assumed to have been taken out of the store, and the associated module
-will be unloaded if one was loaded, and the I<provider object> will be
-freed.
+ossl_provider_up_ref() increments the provider object I<prov>'s
+reference count.
 
-ossl_provider_add_module_location() adds a location to look for a
-provider module.
+ossl_provider_free() decrements the provider object I<prov>'s
+reference count; if it drops below 2, the provider object is assumed
+to have fallen out of use and will be deactivated (its I<teardown>
+function is called); if it drops down to zero, I<prov> is assumed to
+have been taken out of the store, and the associated module will be
+unloaded if one was loaded, and I<prov> itself will be freed.
 
-ossl_provider_set_fallback() marks an available provider as fallback.
-Note that after this call, the I<provider object> pointer that was
+ossl_provider_set_fallback() marks an available provider I<prov> as
+fallback.
+Note that after this call, the provider object pointer that was
 used can simply be dropped, but not freed.
 
+ossl_provider_set_module_path() sets the module path to load the
+provider module given the provider object I<prov>.
+This will be used in preference to automatically trying to figure out
+the path from the provider name and the default module directory (more
+on this in L</NOTES>).
+
+ossl_provider_add_parameter() adds a global parameter for the provider
+to retrieve as it sees fit.
+The parameters are a combination of I<name> and I<value>, and the
+provider will use the name to find the value it wants.
+Only text parameters can be given, and it's up to the provider to
+interpret them.
+
 ossl_provider_activate() "activates" the provider for the given
-I<provider object>.
-What "activates" means depends on what type of I<provider object> it
+provider object I<prov>.
+What "activates" means depends on what type of provider object it
 is:
 
 =over 4
@@ -117,9 +141,9 @@ function will get called.
 
 =item *
 
-If no intialization function was given with ossl_provider_new(), a
-loadable module with the C<name> that was given to ossl_provider_new()
-will be located and loaded, then the symbol C<OSSL_provider_init> will
+If no initialization function was given with ossl_provider_new(), a
+loadable module with the I<name> that was given to ossl_provider_new()
+will be located and loaded, then the symbol B<OSSL_provider_init> will
 be located in that module, and called.
 
 =back
@@ -129,7 +153,7 @@ Outside of the provider, it's completely opaque, but it needs to be
 passed back to some of the provider functions.
 
 ossl_provider_forall_loaded() iterates over all the currently
-"activated" providers, and calls C<cb> for each of them.
+"activated" providers, and calls I<cb> for each of them.
 If no providers have been "activated" yet, it tries to activate all
 available fallback providers and tries another iteration.
 
@@ -145,23 +169,23 @@ providers that come in the form of loadable modules.
 ossl_provider_module_path() returns the full path of the module file,
 for providers that come in the form of loadable modules.
 
-ossl_provider_teardown() calls the provider's C<teardown> function, if
+ossl_provider_teardown() calls the provider's I<teardown> function, if
 the provider has one.
 
-ossl_provider_get_param_types() calls the provider's C<get_param_types>
+ossl_provider_get_param_types() calls the provider's I<get_param_types>
 function, if the provider has one.
-It should return an array of C<OSSL_ITEM> to describe all the
-parameters that the provider has for the I<provider object>.
+It should return an array of I<OSSL_ITEM> to describe all the
+parameters that the provider has for the provider object.
 
 ossl_provider_get_params() calls the provider's parameter request
 responder.
-It should treat the given C<OSSL_PARAM> array as described in
+It should treat the given I<OSSL_PARAM> array as described in
 L<OSSL_PARAM(3)>.
 
 ossl_provider_query_operation() calls the provider's
-C<query_operation> function, if the provider has one.
-It should return an array of C<OSSL_ALGORITHM> for the given
-C<operation_id>.
+I<query_operation> function, if the provider has one.
+It should return an array of I<OSSL_ALGORITHM> for the given
+I<operation_id>.
 
 =head1 NOTES
 
@@ -171,50 +195,56 @@ Locating a provider module happens as follows:
 
 =item 1.
 
-Look in each directory given by ossl_provider_add_module_location().
+If a path was given with ossl_provider_set_module_path(), use that as
+module path.
+Otherwise, use the provider object's name as module path, with
+platform specific standard extensions added.
 
 =item 2.
 
-Look in the directory given by the environment variable
-B<OPENSSL_MODULES>.
-
-=item 3.
-
-Look in the directory given by the OpenSSL built in macro
-B<MODULESDIR>.
+If the environment variable B<OPENSSL_MODULES> is defined, assume its
+value is a directory specification and merge it with the module path.
+Otherwise, merge the value of the OpenSSL built in macro B<MODULESDIR>
+with the module path.
 
 =back
 
+When this process is done, the result is used when trying to load the
+provider module.
+
+The command C<openssl version -m> can be used to find out the value
+of the built in macro B<MODULESDIR>.
+
 =head1 RETURN VALUES
 
 ossl_provider_find() and ossl_provider_new() return a pointer to a
-I<provider object> (C<OSSL_PROVIDER>) on success, or B<NULL> on error.
+provider object (I<OSSL_PROVIDER>) on success, or NULL on error.
 
-ossl_provider_upref() returns the value of the reference counter after
+ossl_provider_up_ref() returns the value of the reference count after
 it has been incremented.
 
 ossl_provider_free() doesn't return any value.
 
-ossl_provider_add_module_location(), ossl_provider_set_fallback() and
+ossl_provider_set_module_path(), ossl_provider_set_fallback() and
 ossl_provider_activate() return 1 on success, or 0 on error.
 
 ossl_provider_name(), ossl_provider_dso(),
 ossl_provider_module_name(), and ossl_provider_module_path() return a
-pointer to their respective data if it's available, otherwise B<NULL>
+pointer to their respective data if it's available, otherwise NULL
 is returned.
 
 ossl_provider_teardown() doesnt't return any value.
 
-ossl_provider_get_param_types() returns a pointer to an C<OSSL_ITEM>
+ossl_provider_get_param_types() returns a pointer to an I<OSSL_ITEM>
 array if this function is available in the provider, otherwise
-B<NULL>.
+NULL.
 
 ossl_provider_get_params() returns 1 on success, or 0 on error.
 If this function isn't available in the provider, 0 is returned.
 
 =head1 SEE ALSO
 
-L<OSSL_PROVIDER(3)>, L<provider(7)>
+L<OSSL_PROVIDER(3)>, L<provider(7)>, L<openssl(1)>
 
 =head1 HISTORY
 

doc/internal/man3/rand_bytes_ex.pod

@@ -0,0 +1,41 @@
+=pod
+
+=head1 NAME
+
+rand_bytes_ex, rand_priv_bytes_ex
+- internal random number routines
+
+=head1 SYNOPSIS
+
+ #include "internal/rand_int.h"
+
+ int rand_bytes_ex(OPENSSL_CTX *ctx, unsigned char *buf, int num);
+ int rand_priv_bytes_ex(OPENSSL_CTX *ctx, unsigned char *buf, int num);
+
+=head1 DESCRIPTION
+
+rand_bytes_ex() and rand_priv_bytes_ex() are the equivalent of RAND_bytes() and
+RAND_priv_bytes() in the public API except that they both take an additional
+B<ctx> parameter.
+The DRBG used for the operation is the public or private DRBG associated with
+the specified B<ctx>. The parameter can be NULL, in which case
+the default library ctx is used.
+If the default RAND_METHOD has been changed then for compatibility reasons the
+RAND_METHOD will be used in preference and the DRBG of the library context
+ignored.
+
+=head1 RETURN VALUES
+
+rand_bytes_ex() and rand_bytes_priv_ex() return 0 or less on error or 1 on
+success.
+
+=head1 COPYRIGHT
+
+Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut