Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)

Standard preamble:
========================================================================
..

..

.. Set up some character translations and predefined strings. \*(-- will
give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
double quote, and \*(R" will give a right double quote. \*(C+ will
give a nicer C++. Capital omega is used to do unbreakable dashes and
therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
nothing in troff, for use with C<>.
.tr \(*W- . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\}
Escape single quotes in literal strings from groff's Unicode transform.

If the F register is >0, we'll generate index entries on stderr for
titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
entries marked with X<> in POD. Of course, you'll have to process the
output yourself in some meaningful fashion.

Avoid warning from groff about undefined register 'F'.
.. .nr rF 0 . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF
Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] .\} . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents . \" corrections for vroff . \" for low resolution devices (crt and lpr) \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} ========================================================================

Title "OSSL_PARAM_BLD 3" For nroff, turn off justification. Always turn off hyphenation; it makes
way too many mistakes in technical documents.
OSSL_PARAM_BLD, OSSL_PARAM_BLD_new, 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_time_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 Header "SYNOPSIS" .Vb 1 #include <openssl/param_build.h> \& typedef struct OSSL_PARAM_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(OSSL_PARAM_BLD *bld); \& 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); .Ve Header "DESCRIPTION" A collection of utility functions that simplify the creation of \s-1OSSL_PARAM\s0 arrays. The \f(BI\s-1TYPE\s0 names are as per OSSL_PARAM_int\|(3).

\fBOSSL_PARAM_BLD_new() allocates and initialises a new \s-1OSSL_PARAM_BLD\s0 structure so that values can be added. Any existing values are cleared.

\fBOSSL_PARAM_BLD_free() deallocates the memory allocates by OSSL_PARAM_BLD_new().

\fBOSSL_PARAM_BLD_to_param() converts a built up \s-1OSSL_PARAM_BLD\s0 structure \fIbld into an allocated \s-1OSSL_PARAM\s0 array. The \s-1OSSL_PARAM\s0 array and all associated storage must be freed by calling \fBOSSL_PARAM_free() with the functions return value. \fBOSSL_PARAM_BLD_free() can safely be called any time after this function is.

\fBOSSL_PARAM_BLD_push_\f(BI\s-1TYPE\s0() are a series of functions which will create \s-1OSSL_PARAM\s0 objects of the specified size and correct type for the val argument. \fIval is stored by value and an expression or auto variable can be used.

\fBOSSL_PARAM_BLD_push_BN() is a function that will create an \s-1OSSL_PARAM\s0 object that holds the specified \s-1BIGNUM\s0 bn. If bn is marked as being securely allocated, its \s-1OSSL_PARAM\s0 representation will also be securely allocated. The bn argument is stored by reference and the underlying \s-1BIGNUM\s0 object must exist until after OSSL_PARAM_BLD_to_param() has been called.

\fBOSSL_PARAM_BLD_push_BN_pad() is a function that will create an \s-1OSSL_PARAM\s0 object that holds the specified \s-1BIGNUM\s0 bn. The object will be padded to occupy exactly sz bytes, if insufficient space is specified an error results. If bn is marked as being securely allocated, its \s-1OSSL_PARAM\s0 representation will also be securely allocated. The bn argument is stored by reference and the underlying \s-1BIGNUM\s0 object must exist until after OSSL_PARAM_BLD_to_param() has been called.

\fBOSSL_PARAM_BLD_push_utf8_string() is a function that will create an \s-1OSSL_PARAM\s0 object that references the \s-1UTF8\s0 string specified by buf. The length of the string bsize should not include the terminating \s-1NUL\s0 byte. If it is zero then it will be calculated. The string that buf points to is stored by reference and must remain in scope until after OSSL_PARAM_BLD_to_param() has been called.

\fBOSSL_PARAM_BLD_push_octet_string() is a function that will create an \s-1OSSL_PARAM\s0 object that references the octet string specified by buf and <bsize>. The memory that buf points to is stored by reference and must remain in scope until after OSSL_PARAM_BLD_to_param() has been called.

\fBOSSL_PARAM_BLD_push_utf8_ptr() is a function that will create an \s-1OSSL_PARAM\s0 object that references the \s-1UTF8\s0 string specified by buf. The length of the string bsize should not include the terminating \s-1NUL\s0 byte. If it is zero then it will be calculated. The string buf points to is stored by reference and must remain in scope until the \s-1OSSL_PARAM\s0 array is freed.

\fBOSSL_PARAM_BLD_push_octet_ptr() is a function that will create an \s-1OSSL_PARAM\s0 object that references the octet string specified by buf. The memory buf points to is stored by reference and must remain in scope until the \s-1OSSL_PARAM\s0 array is freed.

Header "RETURN VALUES" \fBOSSL_PARAM_BLD_new() returns the allocated \s-1OSSL_PARAM_BLD\s0 structure, or \s-1NULL\s0 on error.

\fBOSSL_PARAM_BLD_to_param() returns the allocated \s-1OSSL_PARAM\s0 array, or \s-1NULL\s0 on error.

All of the OSSL_PARAM_BLD_push_TYPE functions return 1 on success and 0 on error.

Header "NOTES" \fBOSSL_PARAM_BLD_push_BN() and OSSL_PARAM_BLD_push_BN_pad() currently only support nonnegative \s-1BIGNUM\s0s. They return an error on negative \s-1BIGNUM\s0s. Header "EXAMPLES" Both examples creating an \s-1OSSL_PARAM\s0 array that contains an \s-1RSA\s0 key. For both, the predefined key variables are:

.Vb 6 BIGNUM *n; /* modulus */ unsigned int e; /* public exponent */ BIGNUM *d; /* private exponent */ BIGNUM *p, *q; /* first two prime factors */ BIGNUM *dmp1, *dmq1; /* first two CRT exponents */ BIGNUM *iqmp; /* first CRT coefficient */ .Ve

Subsection "Example 1" This example shows how to create an \s-1OSSL_PARAM\s0 array that contains an \s-1RSA\s0 private key.

.Vb 2 OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new(); OSSL_PARAM *params = NULL; \& if (bld == NULL || !OSSL_PARAM_BLD_push_BN(bld, "n", n) || !OSSL_PARAM_BLD_push_uint(bld, "e", e) || !OSSL_PARAM_BLD_push_BN(bld, "d", d) || !OSSL_PARAM_BLD_push_BN(bld, "rsa-factor1", p) || !OSSL_PARAM_BLD_push_BN(bld, "rsa-factor2", q) || !OSSL_PARAM_BLD_push_BN(bld, "rsa-exponent1", dmp1) || !OSSL_PARAM_BLD_push_BN(bld, "rsa-exponent2", dmq1) || !OSSL_PARAM_BLD_push_BN(bld, "rsa-coefficient1", iqmp) || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL) goto err; OSSL_PARAM_BLD_free(bld); /* Use params */ ... OSSL_PARAM_free(params); .Ve

Subsection "Example 2" This example shows how to create an \s-1OSSL_PARAM\s0 array that contains an \s-1RSA\s0 public key.

.Vb 2 OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new(); OSSL_PARAM *params = NULL; \& if (nld == NULL || !OSSL_PARAM_BLD_push_BN(bld, "n", n) || !OSSL_PARAM_BLD_push_uint(bld, "e", e) || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL) goto err; OSSL_PARAM_BLD_free(bld); /* Use params */ ... OSSL_PARAM_free(params); .Ve

Header "SEE ALSO" \fBOSSL_PARAM_int\|(3), \s-1OSSL_PARAM\s0\|(3), OSSL_PARAM_free\|(3) Header "HISTORY" The functions described here were all added in OpenSSL 3.0. Header "COPYRIGHT" Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at <https://www.openssl.org/source/license.html>.