diff options
author | Pauli <paul.dale@oracle.com> | 2020-03-24 14:58:57 +1000 |
---|---|---|
committer | Pauli <paul.dale@oracle.com> | 2020-03-28 12:27:20 +1000 |
commit | 110bff618b5bd3c700f2f0a290612ca642672ce6 (patch) | |
tree | 48a183a9f54b95c847f1e0222b82eaafec53da1a /doc/man3 | |
parent | 9e885a707d604e9528b5491b78fb9c00f41193fc (diff) |
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)
Diffstat (limited to 'doc/man3')
-rw-r--r-- | doc/man3/OSSL_PARAM_BLD_init.pod | 197 |
1 files changed, 197 insertions, 0 deletions
diff --git a/doc/man3/OSSL_PARAM_BLD_init.pod b/doc/man3/OSSL_PARAM_BLD_init.pod new file mode 100644 index 0000000000..0b61ece8bc --- /dev/null +++ b/doc/man3/OSSL_PARAM_BLD_init.pod @@ -0,0 +1,197 @@ +=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 "openssl/param_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 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. +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 |