Fix crash and latest update.

doc/internal/man3/ossl_method_construct.pod

@@ -0,0 +1,133 @@
+=pod
+
+=head1 NAME
+
+OSSL_METHOD_CONSTRUCT_METHOD, ossl_method_construct
+- generic method constructor
+
+=head1 SYNOPSIS
+
+ #include "internal/core.h"
+
+ struct ossl_method_construct_method_st {
+     /* Create store */
+     void *(*alloc_tmp_store)(void);
+     /* 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 *propquery,
+                  void *data);
+     /* Store a method in a store */
+     int (*put)(OPENSSL_CTX *libctx, void *store, const char *propdef,
+                void *method, void *data);
+     /* Construct a new method */
+     void *(*construct)(const OSSL_DISPATCH *fns, OSSL_PROVIDER *prov,
+                        void *data);
+     /* Destruct a method */
+     void (*destruct)(void *method);
+ };
+ typedef struct ossl_method_construct_method OSSL_METHOD_CONSTRUCT_METHOD;
+
+ void *ossl_method_construct(OPENSSL_CTX *ctx, int operation_id,
+                             const char *name, const char *properties,
+                             int force_cache,
+                             OSSL_METHOD_CONSTRUCT_METHOD *mcm, void *mcm_data);
+
+=head1 DESCRIPTION
+
+All libcrypto sub-systems that want to create their own methods based
+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.
+
+=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
+functions given by the sub-system specific method creator through
+C<mcm> and the data in C<mcm_data> (which is passed by
+ossl_method_construct()).
+
+=head2 Structures
+
+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
+function pointers:
+
+=over 4
+
+=item alloc_tmp_store()
+
+Create a temporary method store.
+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.
+
+=item dealloc_tmp_store()
+
+Remove a temporary store.
+
+=item get()
+
+Look up an already existing method from a store.
+
+The store may be given with C<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>.
+
+The method to be looked up should be identified with data from C<data>
+(which is the C<mcm_data> that was passed to ossl_construct_method())
+and the provided property query C<propquery>.
+
+=item put()
+
+Places the C<method> created by the construct() function (see below)
+in a store.
+
+The store may be given with C<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>.
+
+The method should be associated with the given property definition
+C<propdef> and any identification data given through C<data> (which is
+the C<mcm_data> that was passed to ossl_construct_method()).
+
+=item construct()
+
+Constructs a sub-system method given a dispatch table C<fns>.
+
+The associated I<provider object> C<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().
+
+=item desctruct()
+
+Destruct the given C<method>.
+
+=back
+
+=head1 RETURN VALUES
+
+ossl_method_construct() returns a constructed method on success, or
+B<NULL> on error.
+
+=head1 HISTORY
+
+This functionality was added to OpenSSL 3.0.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