NEWS: note OSSL_PARAM_BLD API as public.

Reviewed-by: Nicola Tuveri <[email protected]>
(Merged from openssl#11390)

Author: paulidale

CHANGES.md

@@ -24,6 +24,14 @@ OpenSSL 3.0
 
 ### Changes between 1.1.1 and 3.0 [xx XXX xxxx] ###
 
+ * Added OSSL_PARAM_BLD to the public interface.  This allows OSSL_PARAM
+   arrays to be more easily constructed via a series of utility functions.
+   Create a parameter builder using OSSL_PARAM_BLD_new(), add parameters using
+   the various push functions and finally convert to a passable OSSL_PARAM
+   array using OSSL_PARAM_BLD_to_param().
+
+   * Paul Dale *
+
  * EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_DH(), and
    EVP_PKEY_get0_EC_KEY() can now handle EVP_PKEYs with provider side
    internal keys, if they correspond to one of those built in types.

NEWS.md

@@ -31,6 +31,7 @@ OpenSSL 3.0
   * enable-crypto-mdebug and enable-crypto-mdebug-backtrace were mostly
     disabled; the project uses address sanitize/leak-detect instead.
   * Added OSSL_SERIALIZER, a generic serializer API.
+  * Added OSSL_PARAM_BLD, an easier to use API to OSSL_PARAM.
   * Added error raising macros, ERR_raise() and ERR_raise_data().
   * Deprecated ERR_put_error().
   * Added OSSL_PROVIDER_available(), to check provider availibility.

doc/man3/OSSL_PARAM_BLD_init.pod doc/man3/OSSL_PARAM_BLD_new.pod

@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-OSSL_PARAM_BLD_init, OSSL_PARAM_BLD_to_param,
+OSSL_PARAM_BLD_new, OSSL_PARAM_BLD_to_param, OSSL_PARAM_BLD_free_params,
 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,
@@ -24,7 +24,8 @@ OSSL_PARAM_BLD_push_octet_string, OSSL_PARAM_BLD_push_octet_ptr
 
  void OSSL_PARAM_BLD_init(OSSL_PARAM_BLD *bld);
  OSSL_PARAM *OSSL_PARAM_BLD_to_param(OSSL_PARAM_BLD *bld);
- void OSSL_PARAM_BLD_free(OSSL_PARAM *params);
+ void OSSL_PARAM_BLD_free_params(OSSL_PARAM *params);
+ void OSSL_PARAM_BLD_free(OSSL_PARAM_BLD *bld);
 
  int OSSL_PARAM_BLD_push_TYPE(OSSL_PARAM_BLD *bld, const char *key, TYPE val);
 
@@ -52,12 +53,15 @@ OSSL_PARAM_BLD_init() initialises the OSSL_PARAM_BLD structure so that values
 can be added.
 Any existing values are cleared.
 
+OSSL_PARAM_BLD_free() deallocates the memory allocates by OSSL_PARAM_BLD_new().
+
 OSSL_PARAM_BLD_to_param() converts a built up OSSL_PARAM_BLD structure
 I<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_params() with the functions return value.
+OSSL_PARAM_BLD_free() can safely be called any time after this function is.
 
-OSSL_PARAM_BLD_free() deallocates the memory allocated by
+OSSL_PARAM_BLD_free_params() deallocates the memory allocated by
 OSSL_PARAM_BLD_to_param().
 
 =begin comment
@@ -156,9 +160,10 @@ private key.
         || !OSSL_PARAM_BLD_push_BN(&bld, "d", d)
         || (params = OSSL_PARAM_BLD_to_param(&bld)) == NULL)
         goto err;
+    OSSL_PARAM_BLD_free(bld);
     /* Use params */
     ...
-    OSSL_PARAM_BLD_free(params);
+    OSSL_PARAM_BLD_free_params(params);
 
 =head2 Example 2
 
@@ -173,9 +178,10 @@ public key.
         || !OSSL_PARAM_BLD_push_BN(&bld, "d", d)
         || (params = OSSL_PARAM_BLD_to_param(&bld)) == NULL)
         goto err;
+    OSSL_PARAM_BLD_free(bld);
     /* Use params */
     ...
-    OSSL_PARAM_BLD_free(params);
+    OSSL_PARAM_BLD_free_params(params);
 
 =head1 SEE ALSO
 

util/libcrypto.num

@@ -5000,6 +5000,25 @@ EVP_PKEY_CTX_set_rsa_keygen_primes      ?	3_0_0	EXIST::FUNCTION:RSA
 NCONF_new_with_libctx                   ?	3_0_0	EXIST::FUNCTION:
 CONF_modules_load_file_with_libctx      ?	3_0_0	EXIST::FUNCTION:
 OPENSSL_CTX_load_config                 ?	3_0_0	EXIST::FUNCTION:
+OSSL_PARAM_BLD_init                     ?	3_0_0	EXIST::FUNCTION:
+OSSL_PARAM_BLD_to_param                 ?	3_0_0	EXIST::FUNCTION:
+OSSL_PARAM_BLD_free                     ?	3_0_0	EXIST::FUNCTION:
+OSSL_PARAM_BLD_push_int                 ?	3_0_0	EXIST::FUNCTION:
+OSSL_PARAM_BLD_push_uint                ?	3_0_0	EXIST::FUNCTION:
+OSSL_PARAM_BLD_push_long                ?	3_0_0	EXIST::FUNCTION:
+OSSL_PARAM_BLD_push_ulong               ?	3_0_0	EXIST::FUNCTION:
+OSSL_PARAM_BLD_push_int32               ?	3_0_0	EXIST::FUNCTION:
+OSSL_PARAM_BLD_push_uint32              ?	3_0_0	EXIST::FUNCTION:
+OSSL_PARAM_BLD_push_int64               ?	3_0_0	EXIST::FUNCTION:
+OSSL_PARAM_BLD_push_uint64              ?	3_0_0	EXIST::FUNCTION:
+OSSL_PARAM_BLD_push_size_t              ?	3_0_0	EXIST::FUNCTION:
+OSSL_PARAM_BLD_push_double              ?	3_0_0	EXIST::FUNCTION:
+OSSL_PARAM_BLD_push_BN                  ?	3_0_0	EXIST::FUNCTION:
+OSSL_PARAM_BLD_push_BN_pad              ?	3_0_0	EXIST::FUNCTION:
+OSSL_PARAM_BLD_push_utf8_string         ?	3_0_0	EXIST::FUNCTION:
+OSSL_PARAM_BLD_push_utf8_ptr            ?	3_0_0	EXIST::FUNCTION:
+OSSL_PARAM_BLD_push_octet_string        ?	3_0_0	EXIST::FUNCTION:
+OSSL_PARAM_BLD_push_octet_ptr           ?	3_0_0	EXIST::FUNCTION:
 EVP_PKEY_set_type_by_keymgmt            ?	3_0_0	EXIST::FUNCTION:
 OCSP_RESPID_set_by_key_ex               ?	3_0_0	EXIST::FUNCTION:OCSP
 OCSP_RESPID_match_ex                    ?	3_0_0	EXIST::FUNCTION:OCSP