diff options
author | Pauli <paul.dale@oracle.com> | 2020-03-26 09:28:01 +1000 |
---|---|---|
committer | Pauli <paul.dale@oracle.com> | 2020-03-28 12:27:22 +1000 |
commit | 6d4e6009d27712a405e1e3a4c33fb8a8566f134a (patch) | |
tree | 09d94a8c8f8f6f493cc758b6fd704837be82cb8c /doc | |
parent | be19d3caf0724b786ecc97ec4207c07cff63c745 (diff) |
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)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/OSSL_PARAM_BLD_new.pod | 39 |
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 */ |