Param builder: make the OSSL_PARAM_BLD APIs public.

The catalyst for this is the difficult of passing BNs through the other
OSSL_PARAM APIs.

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

1 files changed, 0 insertions, 195 deletions

diff --git a/doc/internal/man3/ossl_param_bld_init.pod b/doc/internal/man3/ossl_param_bld_init.pod
deleted file mode 100644
index 8ae0dccb73..0000000000
--- a/doc/internal/man3/ossl_param_bld_init.pod
+++ /dev/null
@@ -1,195 +0,0 @@
-=pod
-
-=head1 NAME
-
-ossl_param_bld_init, ossl_param_bld_to_param,
-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_BN_pad,
-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 openssl 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);
- 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_BN_pad(OSSL_PARAM_BLD *bld, const char *key,
-                                const BIGNUM *bn, size_t sz);
-
- 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<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.
-Any existing values are cleared.
-
-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() deallocates the memory allocated by
-ossl_param_bld_to_param().
-
-=begin comment
-
-POD is pretty good at recognising function names and making them appropriately
-bold...  however, when part of the function name is variable, we have to help
-the processor along
-
-=end comment
-
-B<ossl_param_bld_push_I<TYPE>>() are a series of functions which will create
-OSSL_PARAM objects of the specified size and correct type for the I<val>
-argument.
-I<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 I<bn>.
-If I<bn> is marked as being securely allocated, its OSSL_PARAM representation
-will also be securely allocated.
-The I<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_BN_pad() is a function that will create an OSSL_PARAM object
-that holds the specified BIGNUM I<bn>.
-The object will be padded to occupy exactly I<sz> bytes, if insufficient space
-is specified an error results.
-If I<bn> is marked as being securely allocated, its OSSL_PARAM representation
-will also be securely allocated.
-The I<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 I<buf>.
-If the length of the string, I<bsize>, is zero then it will be calculated.
-The string that I<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 I<buf> and <bsize>.
-The memory that I<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 I<buf>.
-If the length of the string, I<bsize>, is zero then it will be calculated.
-The string I<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 I<buf>.
-The memory I<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() 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 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(3)>, L<OSSL_PARAM(3)>
-
-=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