Latest update.

doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod

@@ -108,7 +108,7 @@ ossl_sa_TYPE_free_leaves() do not return values.
 
 =head1 HISTORY
 
-This functionality was added to OpenSSL 3.0.0.
+This functionality was added to OpenSSL 3.0.
 
 =head1 COPYRIGHT
 

doc/internal/man3/OSSL_METHOD_STORE.pod

@@ -19,9 +19,10 @@ ossl_method_store_cache_get, ossl_method_store_cache_set
  void ossl_method_store_free(OSSL_METHOD_STORE *store);
  int ossl_method_store_init(OPENSSL_CTX *ctx);
  void ossl_method_store_cleanup(OPENSSL_CTX *ctx);
- int ossl_method_store_add(OSSL_METHOD_STORE *store,
-                           int nid, const char *properties,
-                           void *method, void (*method_destruct)(void *));
+ int ossl_method_store_add(OSSL_METHOD_STORE *store, const OSSL_PROVIDER *prov,
+                           int nid, const char *properties, void *method,
+                           int (*method_up_ref)(void *),
+                           void (*method_destruct)(void *));
  int ossl_method_store_remove(OSSL_METHOD_STORE *store,
                               int nid, const void *method);
  int ossl_method_store_fetch(OSSL_METHOD_STORE *store,
@@ -62,15 +63,20 @@ B<ctx> to allow access to the required underlying property data.
 
 ossl_method_store_free() frees resources allocated to B<store>.
 
-ossl_method_store_add() adds the B<method> to the B<store> as an instance of an
-algorithm indicated by B<nid> and the property definition B<properties>.
-The optional B<method_destruct> function is called when B<method> is being
-released from B<store>.
+ossl_method_store_add() adds the B<method> constructed from an implementation in
+the provider B<prov> to the B<store> as an instance of an algorithm indicated by
+B<nid> and the property definition B<properties>, unless the B<store> already
+has a method from the same provider with the same B<nid> and B<properties>.
+If the B<method_up_ref> function is given, it's called to increment the
+reference count of the method.
+If the B<method_destruct> function is given, it's called when this function
+fails to add the method to the store, or later on when it is being released from
+the B<store>.
 
 ossl_method_store_remove() removes the B<method> identified by B<nid> from the
 B<store>.
 
-ossl_method_store_fetch() queries B<store> for an method identified by B<nid>
+ossl_method_store_fetch() queries B<store> for a method identified by B<nid>
 that matches the property query B<prop_query>.
 The result, if any, is returned in B<method>.
 
@@ -82,28 +88,28 @@ and the ones passed to the ossl_method_store_free().
 =head2 Cache Functions
 
 ossl_method_store_cache_get() queries the cache associated with the B<store>
-for an method identified by B<nid> that matches the property query
+for a method identified by B<nid> that matches the property query
 B<prop_query>.
 The result, if any, is returned in B<method>.
 
 ossl_method_store_cache_set() sets a cache entry identified by B<nid> with the
 property query B<prop_query> in the B<store>.
-Future cache gets will return the specified B<method>.
+Future calls to ossl_method_store_cache_get() will return the specified B<method>.
 
 =head1 RETURN VALUES
 
-ossl_method_store_new() a new method store object or B<NULL> on failure.
+ossl_method_store_new() returns a new method store object or B<NULL> on failure.
 
 ossl_method_store_free(), ossl_method_store_add(),
 ossl_method_store_remove(), ossl_method_store_fetch(),
 ossl_method_store_set_global_properties(), ossl_method_store_cache_get()
 and ossl_method_store_cache_set() return B<1> on success and B<0> on error.
 
-ossl_method_store_free() and ossl_method_store_cleanup() do not return values.
+ossl_method_store_free() and ossl_method_store_cleanup() do not return any value.
 
 =head1 HISTORY
 
-This functionality was added to OpenSSL 3.0.0.
+This functionality was added to OpenSSL 3.0.
 
 =head1 COPYRIGHT
 

doc/internal/man3/cms_add1_signing_cert.pod

@@ -0,0 +1,46 @@
+=pod
+
+=head1 NAME
+
+cms_add1_signing_cert, cms_add1_signing_cert_v2
+- add ESS signing-certificate signed attribute to a
+CMS_SignerInfo data structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ int cms_add1_signing_cert(CMS_SignerInfo *si, ESS_SIGNING_CERT *sc);
+
+ int cms_add1_signing_cert_v2(CMS_SignerInfo *si, ESS_SIGNING_CERT_V2 *sc2);
+
+=head1 DESCRIPTION
+
+cms_add1_signing_cert() adds an ESS Signing Certificate B<sc> (version 1) signed
+attribute to the CMS_SignerInfo B<si>.
+cms_add1_signing_cert_v2() adds an ESS Signing Certificate B<sc2> (version 2) signed
+attribute to the CMS_SignerInfo B<si>.
+The ESS Signing Certificate attributes version 1 and 2 are defined in RFC 5035
+which updates Section 5.4 of RFC 2634.
+
+=head1 NOTES
+
+This attribute is mandatory to make a CMS compliant with CAdES-BES
+(European Standard ETSI EN 319 122-1 V1.1.1).
+For a fuller description see L<cms(1)>).
+
+=head1 RETURN VALUES
+
+cms_add1_signing_cert() and cms_add1_signing_cert_v2() return 1 if attribute 
+is added or 0 if an error occurred.
+
+=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/evp_generic_fetch.pod

@@ -2,7 +2,8 @@
 
 =head1 NAME
 
-evp_generic_fetch - generic algorithm fetcher and method creator for EVP
+evp_generic_fetch, evp_generic_fetch_by_number
+- generic algorithm fetchers and method creators for EVP
 
 =head1 SYNOPSIS
 
@@ -11,26 +12,50 @@ evp_generic_fetch - generic algorithm fetcher and method creator for EVP
 
  void *evp_generic_fetch(OPENSSL_CTX *libctx, int operation_id,
                          const char *name, const char *properties,
-                         void *(*new_method)(const OSSL_DISPATCH *fns,
-                                             OSSL_PROVIDER *prov),
+                         void *(*new_method)(int name_id,
+                                             const OSSL_DISPATCH *fns,
+                                             OSSL_PROVIDER *prov,
+                                             void *method_data),
+                         void *method_data,
                          int (*up_ref_method)(void *),
                          void (*free_method)(void *));
 
+ void *evp_generic_fetch_by_number(OPENSSL_CTX *ctx, int operation_id,
+                                   int name_id, const char *properties,
+                                   void *(*new_method)(int name_id,
+                                                       const OSSL_DISPATCH *fns,
+                                                       OSSL_PROVIDER *prov,
+                                                       void *method_data),
+                                   void *method_data,
+                                   int (*up_ref_method)(void *),
+                                   void (*free_method)(void *));
+
 =head1 DESCRIPTION
 
 evp_generic_fetch() calls ossl_method_construct() with the given
-C<libctx>, C<operation_id>, C<name>, and C<properties> and uses
+I<libctx>, I<operation_id>, I<name>, and I<properties> and uses
 it to create an EVP method with the help of the functions
-C<new_method>, C<up_ref_method>, and C<free_method>.
+I<new_method>, I<up_ref_method>, and I<free_method>.
 
-The three functions are supposed to:
+evp_generic_fetch_by_number() does the same thing as evp_generic_fetch(), 
+but takes a I<name_id> instead of a number.
+I<name_id> must always be non-zero; as a matter of fact, it being zero
+is considered a programming error.
+This is meant to be used when one method needs to fetch an associated
+other method, and is typically called from inside the given function
+I<new_method>.
+
+The three functions I<new_method>, I<up_ref_method>, and
+I<free_method> are supposed to:
 
 =over 4
 
 =item new_method()
 
 creates an internal method from function pointers found in the
-dispatch table C<fns>.
+dispatch table I<fns>, with name identity I<name_id>.
+The provider I<prov> and I<method_data> are also passed to be used as
+new_method() sees fit.
 
 =item up_ref_method()
 
@@ -50,10 +75,10 @@ evp_generic_fetch() returns a method on success, or B<NULL> on error.
 =head1 EXAMPLES
 
 This is a short example of the fictitious EVP API and operation called
-C<EVP_FOO>.
+B<EVP_FOO>.
 
 To begin with, let's assume something like this in
-C<include/openssl/core_numbers.h>:
+F<include/openssl/core_numbers.h>:
 
     #define OSSL_OP_FOO                         100
 
@@ -75,6 +100,7 @@ And here's the implementation of the FOO method fetcher:
     /* typedef struct evp_foo_st EVP_FOO */
     struct evp_foo_st {
         OSSL_PROVIDER *prov;
+        int name_id;
 	CRYPTO_REF_COUNT refcnt;
         OSSL_OP_foo_newctx_fn *newctx;
         OSSL_OP_foo_init_fn *init;
@@ -87,14 +113,18 @@ And here's the implementation of the FOO method fetcher:
      * In this example, we have a public method creator and destructor.
      * It's not absolutely necessary, but is in the spirit of OpenSSL.
      */
-    EVP_FOO *EVP_FOO_meth_from_dispatch(const OSSL_DISPATCH *fns,
-                                        OSSL_PROVIDER *prov)
+    EVP_FOO *EVP_FOO_meth_from_dispatch(int name_id,
+                                        const OSSL_DISPATCH *fns,
+                                        OSSL_PROVIDER *prov,
+                                        void *data)
     {
         EVP_FOO *foo = NULL;
 
         if ((foo = OPENSSL_zalloc(sizeof(*foo))) == NULL)
             return NULL;
 
+        foo->name_id = name_id;
+
         for (; fns->function_id != 0; fns++) {
             switch (fns->function_id) {
             case OSSL_OP_FOO_NEWCTX_FUNC:

doc/internal/man3/evp_keymgmt_export_to_provider.pod

@@ -0,0 +1,56 @@
+=pod
+
+=head1 NAME
+
+evp_keymgmt_export_to_provider,
+evp_keymgmt_clear_pkey_cache
+- key material provider export for EVP
+
+=head1 SYNOPSIS
+
+ #include "internal/evp_int.h"
+
+ void *evp_keymgmt_export_to_provider(EVP_PKEY *pk, EVP_KEYMGMT *keymgmt);
+ void evp_keymgmt_clear_pkey_cache(EVP_PKEY *pk);
+
+=head1 DESCRIPTION
+
+evp_keymgmt_export_to_provider() exports the key material from the
+given key I<pk> to a provider via a B<EVP_KEYMGMT> interface, if this
+hasn't already been done.
+It maintains a cache of provider key references in I<pk> to keep track
+of all such exports.
+
+If I<pk> has an assigned legacy key, a check is done to see if any of
+its key material has changed since last export, i.e. the legacy key's
+is_dirty() method returns 1.
+If it has, the cache of already exported keys is cleared, and a new
+export is made with the new key material.
+
+evp_keymgmt_clear_pkey_cache() can be used to explicitly clear the
+cache of provider key references.
+
+=head1 RETURN VALUES
+
+evp_keymgmt_export_to_provider() returns a pointer to the appropriate
+provider side key (created or found again), or NULL on error.
+
+=head1 NOTES
+
+"Legacy key" is the term used for any key that has been assigned to an
+B<EVP_PKEY> with EVP_PKEY_assign_RSA() and similar functions.
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_ASN1_METHOD(3)>, L<EVP_PKEY_assign_RSA(3)>
+
+=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/evp_keymgmt_freekey.pod

@@ -0,0 +1,109 @@
+=pod
+
+=head1 NAME
+
+evp_keymgmt_importdomparams, evp_keymgmt_gendomparams,
+evp_keymgmt_freedomparams,
+evp_keymgmt_exportdomparams,
+evp_keymgmt_importdomparams_types, evp_keymgmt_exportdomparams_types,
+evp_keymgmt_importkey, evp_keymgmt_genkey, evp_keymgmt_loadkey,
+evp_keymgmt_freekey,
+evp_keymgmt_exportkey,
+evp_keymgmt_importkey_types, evp_keymgmt_exportkey_types
+- internal KEYMGMT support functions
+
+=head1 SYNOPSIS
+
+ #include "internal/evp_int.h"
+
+ void *evp_keymgmt_importdomparams(const EVP_KEYMGMT *keymgmt,
+                                const OSSL_PARAM params[]);
+ void *evp_keymgmt_gendomparams(const EVP_KEYMGMT *keymgmt,
+                             const OSSL_PARAM params[]);
+ void evp_keymgmt_freedomparams(const EVP_KEYMGMT *keymgmt, void *provdomparams);
+ int evp_keymgmt_exportdomparams(const EVP_KEYMGMT *keymgmt,
+                              void *provdomparams, OSSL_PARAM params[]);
+ const OSSL_PARAM *evp_keymgmt_importdomparams_types(const EVP_KEYMGMT *keymgmt);
+ const OSSL_PARAM *evp_keymgmt_exportdomparams_types(const EVP_KEYMGMT *keymgmt);
+
+ void *evp_keymgmt_importkey(const EVP_KEYMGMT *keymgmt,
+                             const OSSL_PARAM params[]);
+ void *evp_keymgmt_genkey(const EVP_KEYMGMT *keymgmt, void *domparams,
+                          const OSSL_PARAM params[]);
+ void *evp_keymgmt_loadkey(const EVP_KEYMGMT *keymgmt,
+                           void *id, size_t idlen);
+ void evp_keymgmt_freekey(const EVP_KEYMGMT *keymgmt, void *provkey);
+ int evp_keymgmt_exportkey(const EVP_KEYMGMT *keymgmt, void *provkey,
+                           OSSL_PARAM params[]);
+ const OSSL_PARAM *evp_keymgmt_importkey_types(const EVP_KEYMGMT *keymgmt);
+ const OSSL_PARAM *evp_keymgmt_exportkey_types(const EVP_KEYMGMT *keymgmt);
+
+=head1 DESCRIPTION
+
+All these functions are helpers to call the provider's corresponding
+function.
+
+evp_keymgmt_importdomparams() calls the method's importdomparams() function.
+
+evp_keymgmt_gendomparams() calls the method's gendomparams() function.
+
+evp_keymgmt_freedomparams() calls the method's freedomparams() function.
+
+evp_keymgmt_exportdomparams() calls the method's exportdomparams()
+function.
+
+evp_keymgmt_importdomparams_types() calls the method's
+importdomparams_types() function.
+
+evp_keymgmt_exportdomparams_types() calls the method's
+exportdomparams_types() function.
+
+evp_keymgmt_importkey() calls the method's importkey()
+function.
+
+evp_keymgmt_genkey() calls the method's genkey() function.
+
+evp_keymgmt_loadkey() calls the method's loadkey() function.
+
+evp_keymgmt_freekey() calls the method's freekey() function.
+
+evp_keymgmt_exportkey() calls the method's exportkey()
+function.
+
+evp_keymgmt_importkey_types() calls the method's importkey_types() function.
+
+evp_keymgmt_exportkey_types() calls the method's exportkey_types() function.
+
+=head1 RETURN VALUES
+
+evp_keymgmt_importdomparams(), evp_keymgmt_gendomparams() return a pointer
+to a provider owned set of domparams parameters, or NULL on error.
+
+evp_keymgmt_importkey(), evp_keymgmt_genkey(), evp_keymgmt_loadkey() return
+a pointer to a provider owned key, or NULL on error.
+
+evp_keymgmt_exportdomparams() and evp_keymgmt_exportkey() return 1 on success,
+or 0 on error.
+
+evp_keymgmt_importdomparams_types(), evp_keymgmt_exportdomparams_types()
+return parameter descriptor for importing and exporting domparams
+parameters, or NULL if there are no such descriptors.
+
+evp_keymgmt_importkey_types() and evp_keymgmt_exportkey_types()
+return parameter descriptor for importing and exporting keys, or NULL
+if there are no such descriptors.
+
+=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_algorithm_do_all.pod

@@ -0,0 +1,63 @@
+=pod
+
+=head1 NAME
+
+ossl_algorithm_do_all - generic algorithm implementation iterator
+
+=head1 SYNOPSIS
+
+ void ossl_algorithm_do_all(OPENSSL_CTX *libctx, int operation_id,
+                            OSSL_PROVIDER *provider,
+                            void (*fn)(OSSL_PROVIDER *provider,
+                                       const OSSL_ALGORITHM *algo,
+                                       int no_store, void *data),
+                            void *data)
+
+=head1 DESCRIPTION
+
+ossl_algorithm_do_all() looks up every algorithm it can find, given a
+library context I<libctx>, an operation identity I<operation_id> and a
+provider I<provider>.
+I<libctx> may be NULL to signify that the default library context should
+be used.
+I<operation_id> may be zero to signify that all kinds of operations
+will be looked up.
+I<provider> may be NULL to signify that all loaded providers will be
+queried.
+
+For each implementation found, the function I<fn> is called with the
+I<provider> for the implementation, the algorithm descriptor I<algo>,
+the flag I<no_store> indicating whether the algorithm descriptor may
+be remembered or not, and the caller I<data> that was passed to
+ossl_algorithm_do_all().
+
+=head1 RETURN VALUES
+
+ossl_algorithm_do_all() doesn't return any value.
+
+=head1 NOTES
+
+The function described here are mainly useful for discovery, and
+possibly display of what has been discovered, for example an
+application that wants to display the loaded providers and what they
+may offer, but also for constructors, such as
+L<ossl_construct_method(3)>.
+
+=head1 SEE ALSO
+
+L<ossl_construct_method(3)>, L<EVP_MAC_do_all(3)>
+
+=head1 HISTORY
+
+This functionality was added to 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,13 +15,11 @@ 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,
-                  int operation_id, const char *name, const char *propquery,
-                  void *data);
+     void *(*get)(OPENSSL_CTX *libctx, void *store, void *data);
      /* Store a method in a store */
      int (*put)(OPENSSL_CTX *libctx, void *store, void *method,
-                int operation_id, const char *name, const char *propdef,
-                void *data);
+                const OSSL_PROVIDER *prov, 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);
@@ -31,7 +29,6 @@ OSSL_METHOD_CONSTRUCT_METHOD, ossl_method_construct
  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);
 
@@ -58,11 +55,10 @@ It's important to keep in mind that a method is identified by three things:
 =head2 Functions
 
 ossl_method_construct() creates a method by asking all available
-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
-I<mcm> and the data in I<mcm_data> (which is passed by
-ossl_method_construct()).
+providers for a dispatch table given an I<operation_id>, and then
+calling the appropriate functions given by the sub-system specific
+method creator through 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
 reference counting and acts accordingly (i.e. it will call the
@@ -98,10 +94,10 @@ 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 I<libctx>.
 
-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()).
+The method to be looked up should be identified with data found in I<data>
+(which is the I<mcm_data> that was passed to ossl_construct_method()).
+In other words, the ossl_method_construct() caller is entirely responsible
+for ensuring the necesssary data is made available.
 
 This function is expected to increment the method's reference count.
 

doc/internal/man3/ossl_param_bld_init.pod

@@ -0,0 +1,188 @@
+=pod
+
+=head1 NAME
+
+ossl_param_bld_init, ossl_param_bld_to_param, ossl_param_bld_to_param_ex,
+ossl_param_bld_free, ossl_param_bld_push_int, ossl_param_bld_push_uint,
+ossl_param_bld_push_long, ossl_param_bld_push_ulong,
+ossl_param_bld_push_int32, ossl_param_bld_push_uint32,
+ossl_param_bld_push_int64, ossl_param_bld_push_uint64,
+ossl_param_bld_push_size_t, ossl_param_bld_push_double,
+ossl_param_bld_push_BN, ossl_param_bld_push_utf8_string,
+ossl_param_bld_push_utf8_ptr, ossl_param_bld_push_octet_string,
+ossl_param_bld_push_octet_ptr
+- functions to assist in the creation of OSSL_PARAM arrays
+
+=head1 SYNOPSIS
+
+=for comment generic
+
+ #include "internal/params_build.h"
+
+ #define OSSL_PARAM_BLD_MAX 10
+ typedef struct { ... } OSSL_PARAM_BLD;
+
+ void ossl_param_bld_init(OSSL_PARAM_BLD *bld);
+ OSSL_PARAM *ossl_param_bld_to_param(OSSL_PARAM_BLD *bld);
+ OSSL_PARAM *ossl_param_bld_to_param_ex(OSSL_PARAM_BLD *bld,
+                                        OSSL_PARAM *params, size_t param_n,
+                                        void *data, size_t data_n,
+                                        void *secure, size_t secure_n);
+ void ossl_param_bld_free(OSSL_PARAM *params);
+
+ int ossl_param_bld_push_TYPE(OSSL_PARAM_BLD *bld, const char *key, TYPE val);
+
+ int ossl_param_bld_push_BN(OSSL_PARAM_BLD *bld, const char *key,
+                            const BIGNUM *bn);
+
+ int ossl_param_bld_push_utf8_string(OSSL_PARAM_BLD *bld, const char *key,
+                                     const char *buf, size_t bsize);
+ int ossl_param_bld_push_utf8_ptr(OSSL_PARAM_BLD *bld, const char *key,
+                                  char *buf, size_t bsize);
+ int ossl_param_bld_push_octet_string(OSSL_PARAM_BLD *bld, const char *key,
+                                      const void *buf, size_t bsize);
+ int ossl_param_bld_push_octet_ptr(OSSL_PARAM_BLD *bld, const char *key,
+                                   void *buf, size_t bsize);
+
+
+=head1 DESCRIPTION
+
+A collection of utility functions that simplify the creation of OSSL_PARAM
+arrays.  The B<TYPE> names are as per L<OSSL_PARAM_int(3)>.
+
+ossl_param_bld_init() initialises the OSSL_PARAM_BLD structure so that values
+can be added.
+Any existing values are cleared.
+
+ossl_param_bld_to_param() converts a built up OSSL_PARAM_BLD structure
+B<bld> into an allocated OSSL_PARAM array.
+The OSSL_PARAM array and all associated storage must be freed by calling
+ossl_param_bld_free() with the functions return value.
+
+ossl_param_bld_free() deallocates the memory allocated by
+ossl_param_bld_to_param().
+
+ossl_param_bld_to_param_ex() behaves like ossl_param_bld_to_param(), except that
+no additional memory is allocated.
+An OSSL_PARAM array of at least B<param_n> elements is passed in as B<params>.
+The auxiliary storage for the parameters is a block of memory pointed to
+by B<data> of at least B<data_n> bytes in size.
+If required, secure memory for private BIGNUMs should be pointed to by
+B<secure> of at least B<secure_n> bytes in size.
+
+ossl_param_bld_push_TYPE() are a series of functions which will create
+OSSL_PARAM objects of the specified size and correct type for the B<val>
+argument.
+B<val> is stored by value and an expression or auto variable can be used.
+
+ossl_param_bld_push_BN() is a function that will create an OSSL_PARAM object
+that holds the specified BIGNUM B<bn>.
+If B<bn> is marked as being securely allocated, it's OSSL_PARAM representation
+will also be securely allocated.
+The B<bn> argument is stored by reference and the underlying BIGNUM object
+must exist until after ossl_param_bld_to_param() has been called.
+
+ossl_param_bld_push_utf8_string() is a function that will create an OSSL_PARAM
+object that references the UTF8 string specified by B<buf>.
+If the length of the string, B<bsize>, is zero then it will be calculated.
+The string that B<buf> points to is stored by reference and must remain in
+scope until after ossl_param_bld_to_param() has been called.
+
+ossl_param_bld_push_octet_string() is a function that will create an OSSL_PARAM
+object that references the octet string specified by B<buf> and <bsize>.
+The memory that B<buf> points to is stored by reference and must remain in
+scope until after ossl_param_bld_to_param() has been called.
+
+ossl_param_bld_push_utf8_ptr() is a function that will create an OSSL_PARAM
+object that references the UTF8 string specified by B<buf>.
+If the length of the string, B<bsize>, is zero then it will be calculated.
+The string B<buf> points to is stored by reference and must remain in
+scope until the OSSL_PARAM array is freed.
+
+ossl_param_bld_push_octet_ptr() is a function that will create an OSSL_PARAM
+object that references the octet string specified by B<buf>.
+The memory B<buf> points to is stored by reference and must remain in
+scope until the OSSL_PARAM array is freed.
+
+=head1 RETURN VALUES
+
+ossl_param_bld_to_param() and ossl_param_bld_to_param_ex() return the
+allocated OSSL_PARAM array, or NULL on error.
+
+All of the ossl_param_bld_push_TYPE functions return 1 on success and 0
+on error.
+
+=head1 NOTES
+
+The constant B<OSSL_PARAM_BLD_MAX> specifies the maximum number of parameters
+that can be added.
+Exceeding this will result in the push functions returning errors.
+
+The structure B<OSSL_PARAM_BLD> should be considered opaque and subject to
+change between versions.
+
+=head1 EXAMPLES
+
+Both examples creating an OSSL_PARAM array that contains an RSA key.
+For both, the predefined key variables are:
+
+    BIGNUM *p, *q;  /* both prime */
+    BIGNUM *n;      /* = p * q */
+    unsigned int e; /* exponent, usually 65537 */
+    BIGNUM *d;      /* e^-1 */
+
+=head2 Example 1
+
+This example shows how to create an OSSL_PARAM array that contains an RSA
+private key.
+
+    OSSL_PARAM_BLD bld;
+    OSSL_PARAM *params;
+
+    ossl_param_bld_init(&bld, &secure);
+    if (!ossl_param_bld_push_BN(&bld, "p", p)
+        || !ossl_param_bld_push_BN(&bld, "q", q)
+        || !ossl_param_bld_push_uint(&bld, "e", e)
+        || !ossl_param_bld_push_BN(&bld, "n", n)
+        || !ossl_param_bld_push_BN(&bld, "d", d)
+        || (params = ossl_param_bld_to_param(&bld)) == NULL)
+        goto err;
+    /* Use params */
+    ...
+    ossl_param_bld_free(params);
+
+=head2 Example 2
+
+This example shows how to create an OSSL_PARAM array that contains an RSA
+public key.
+
+    OSSL_PARAM_BLD bld;
+    OSSL_PARAM *params;
+
+    ossl_param_bld_init(&bld, &secure);
+    if (!ossl_param_bld_push_BN(&bld, "n", n)
+        || !ossl_param_bld_push_BN(&bld, "d", d)
+        || (params = ossl_param_bld_to_param(&bld)) == NULL)
+        goto err;
+    /* Use params */
+    ...
+    ossl_param_bld_free(params);
+
+=head1 SEE ALSO
+
+L<OSSL_PARAM_int>, L<OSSL_PARAM>
+
+=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

@@ -6,12 +6,13 @@ 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_activate, ossl_provider_available,
 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,
+ossl_provider_library_context,
+ossl_provider_teardown, ossl_provider_gettable_params,
 ossl_provider_get_params, ossl_provider_query_operation
 - internal provider routines
 
@@ -19,9 +20,11 @@ ossl_provider_get_params, ossl_provider_query_operation
 
  #include "internal/provider.h"
 
- OSSL_PROVIDER *ossl_provider_find(OPENSSL_CTX *libctx, const char *name);
+ OSSL_PROVIDER *ossl_provider_find(OPENSSL_CTX *libctx, const char *name,
+                                   int noconfig);
  OSSL_PROVIDER *ossl_provider_new(OPENSSL_CTX *libctx, const char *name,
-                                  ossl_provider_init_fn *init_function);
+                                  ossl_provider_init_fn *init_function
+                                  int noconfig);
  int ossl_provider_up_ref(OSSL_PROVIDER *prov);
  void ossl_provider_free(OSSL_PROVIDER *prov);
 
@@ -33,6 +36,8 @@ ossl_provider_get_params, ossl_provider_query_operation
 
  /* Load and initialize the Provider */
  int ossl_provider_activate(OSSL_PROVIDER *prov);
+ /* Check if provider is available */
+ int ossl_provider_available(OSSL_PROVIDER *prov);
 
  /* Return pointer to the provider's context */
  void *ossl_provider_ctx(const OSSL_PROVIDER *prov);
@@ -48,10 +53,11 @@ ossl_provider_get_params, ossl_provider_query_operation
  const DSO *ossl_provider_dso(OSSL_PROVIDER *prov);
  const char *ossl_provider_module_name(OSSL_PROVIDER *prov);
  const char *ossl_provider_module_path(OSSL_PROVIDER *prov);
+ OPENSSL_CTX *ossl_provider_library_context(const OSSL_PROVIDER *prov);
 
  /* 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);
+ const OSSL_PARAM *ossl_provider_gettable_params(const OSSL_PROVIDER *prov);
  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,
@@ -79,7 +85,11 @@ times as ossl_provider_activate() has.
 =head2 Functions
 
 ossl_provider_find() finds an existing provider object in the provider
-object store by I<name>. 
+object store by I<name>.
+The config file will be automatically loaded unless I<noconfig> is set.
+Typically I<noconfig> should be 0.
+We set I<noconfig> to 1 only when calling these functions while processing a
+config file in order to avoid recursively attempting to load the file.
 The provider object it finds has its reference count incremented.
 
 ossl_provider_new() creates a new provider object named I<name> and
@@ -87,6 +97,10 @@ 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 config file will be automatically loaded unless I<noconfig> is set.
+Typically I<noconfig> should be 0.
+We set I<noconfig> to 1 only when calling these functions while processing a
+config file in order to avoid recursively attempting to load the file.
 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.
@@ -120,6 +134,9 @@ 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_library_context() returns the library context the given
+provider I<prov> is registered in.
+
 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
@@ -148,6 +165,10 @@ be located in that module, and called.
 
 =back
 
+ossl_provider_available() activates all fallbacks if no provider is
+activated yet, then checks if given provider object I<prov> is
+activated.
+
 ossl_provider_ctx() returns a context created by the provider.
 Outside of the provider, it's completely opaque, but it needs to be
 passed back to some of the provider functions.
@@ -172,9 +193,9 @@ for providers that come in the form of loadable modules.
 ossl_provider_teardown() calls the provider's I<teardown> function, if
 the provider has one.
 
-ossl_provider_get_param_types() calls the provider's I<get_param_types>
+ossl_provider_gettable_params() calls the provider's I<gettable_params>
 function, if the provider has one.
-It should return an array of I<OSSL_ITEM> to describe all the
+It should return an array of I<OSSL_PARAM> to describe all the
 parameters that the provider has for the provider object.
 
 ossl_provider_get_params() calls the provider's parameter request
@@ -228,16 +249,23 @@ ossl_provider_free() doesn't return any value.
 ossl_provider_set_module_path(), ossl_provider_set_fallback() and
 ossl_provider_activate() return 1 on success, or 0 on error.
 
+ossl_provider_available() return 1 if the provider is available,
+otherwise 0.
+
 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 NULL
 is returned.
 
+ossl_provider_library_context() return a pointer to the library context.
+This may be NULL, and is perfectly valid, as it denotes the default
+global library context.
+
 ossl_provider_teardown() doesnt't return any value.
 
-ossl_provider_get_param_types() returns a pointer to an I<OSSL_ITEM>
-array if this function is available in the provider, otherwise
-NULL.
+ossl_provider_gettable_params() returns a pointer to a constant
+I<OSSL_PARAM> array if this function is available in the provider,
+otherwise 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.