NEWS: note OSSL_PARAM_BLD API as public.
authorPauli <paul.dale@oracle.com>
Tue, 24 Mar 2020 05:08:00 +0000 (15:08 +1000)
committerPauli <paul.dale@oracle.com>
Sat, 28 Mar 2020 02:27:22 +0000 (12:27 +1000)
Reviewed-by: Nicola Tuveri <nic.tuv@gmail.com>
(Merged from https://github.com/openssl/openssl/pull/11390)

CHANGES.md
NEWS.md
doc/man3/OSSL_PARAM_BLD_new.pod [moved from doc/man3/OSSL_PARAM_BLD_init.pod with 92% similarity]
util/libcrypto.num

index 82c186a..8f7d7ee 100644 (file)
@@ -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.
diff --git a/NEWS.md b/NEWS.md
index 10a38b2..9f29a59 100644 (file)
--- a/NEWS.md
+++ b/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.
similarity index 92%
rename from doc/man3/OSSL_PARAM_BLD_init.pod
rename to doc/man3/OSSL_PARAM_BLD_new.pod
index 0b61ece..8aeb0aa 100644 (file)
@@ -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
 
index 1650884..1f8be71 100644 (file)
@@ -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