Param build: make structures opaque.

Since this is public, it is best to make the underlying structure opaque.
This means converting from stack allocation to dynamic allocation for all
usages.

Reviewed-by: Nicola Tuveri <nic.tuv@gmail.com>
(Merged from https://github.com/openssl/openssl/pull/11390)

1 files changed, 15 insertions, 24 deletions

diff --git a/doc/man3/OSSL_PARAM_BLD_new.pod b/doc/man3/OSSL_PARAM_BLD_new.pod
index 8aeb0aadf0..72b2ff87a3 100644
--- a/doc/man3/OSSL_PARAM_BLD_new.pod
+++ b/doc/man3/OSSL_PARAM_BLD_new.pod
@@ -19,10 +19,9 @@ OSSL_PARAM_BLD_push_octet_string, OSSL_PARAM_BLD_push_octet_ptr
 
  #include "openssl/param_build.h"
 
- #define OSSL_PARAM_BLD_MAX 10
- typedef struct { ... } OSSL_PARAM_BLD;
+ typedef struct OSSL_PARAM_BLD;
 
- void OSSL_PARAM_BLD_init(OSSL_PARAM_BLD *bld);
+ OSSL_PARAM_BLD *OSSL_PARAM_BLD_new(void);
  OSSL_PARAM *OSSL_PARAM_BLD_to_param(OSSL_PARAM_BLD *bld);
  void OSSL_PARAM_BLD_free_params(OSSL_PARAM *params);
  void OSSL_PARAM_BLD_free(OSSL_PARAM_BLD *bld);
@@ -49,8 +48,8 @@ OSSL_PARAM_BLD_push_octet_string, OSSL_PARAM_BLD_push_octet_ptr
 A collection of utility functions that simplify the creation of OSSL_PARAM
 arrays.  The B<I<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.
+OSSL_PARAM_BLD_new() allocates and initialises a new 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().
@@ -117,23 +116,15 @@ scope until the OSSL_PARAM array is freed.
 
 =head1 RETURN VALUES
 
+OSSL_PARAM_BLD_new() returns the allocated OSSL_PARAM_BLD structure, or NULL
+on error.
+
 OSSL_PARAM_BLD_to_param() returns 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 define used for this will always be at least 10 but otherwise no assumption
-should be made about it's specific value.
-
-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.
@@ -149,11 +140,11 @@ For both, the predefined key variables are:
 This example shows how to create an OSSL_PARAM array that contains an RSA
 private key.
 
-    OSSL_PARAM_BLD bld;
+    OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new();
     OSSL_PARAM *params;
 
-    OSSL_PARAM_BLD_init(&bld, &secure);
-    if (!OSSL_PARAM_BLD_push_BN(&bld, "p", p)
+    if (bld == NULL
+        || !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)
@@ -170,13 +161,13 @@ private key.
 This example shows how to create an OSSL_PARAM array that contains an RSA
 public key.
 
-    OSSL_PARAM_BLD bld;
+    OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new();
     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)
+    if (nld == NULL
+        || !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;
     OSSL_PARAM_BLD_free(bld);
     /* Use params */