OSSL_PARAM_BLD_to_param(3ossl)

1OSSL_PARAM_BLD(3ossl)               OpenSSL              OSSL_PARAM_BLD(3ossl)
2
3
4

NAME

6       OSSL_PARAM_BLD, OSSL_PARAM_BLD_new, OSSL_PARAM_BLD_to_param,
7       OSSL_PARAM_BLD_free, OSSL_PARAM_BLD_push_int, OSSL_PARAM_BLD_push_uint,
8       OSSL_PARAM_BLD_push_long, OSSL_PARAM_BLD_push_ulong,
9       OSSL_PARAM_BLD_push_int32, OSSL_PARAM_BLD_push_uint32,
10       OSSL_PARAM_BLD_push_int64, OSSL_PARAM_BLD_push_uint64,
11       OSSL_PARAM_BLD_push_size_t, OSSL_PARAM_BLD_push_time_t,
12       OSSL_PARAM_BLD_push_double, OSSL_PARAM_BLD_push_BN,
13       OSSL_PARAM_BLD_push_BN_pad, OSSL_PARAM_BLD_push_utf8_string,
14       OSSL_PARAM_BLD_push_utf8_ptr, OSSL_PARAM_BLD_push_octet_string,
15       OSSL_PARAM_BLD_push_octet_ptr - functions to assist in the creation of
16       OSSL_PARAM arrays
17

SYNOPSIS

19        #include <openssl/param_build.h>
20
21        typedef struct OSSL_PARAM_BLD;
22
23        OSSL_PARAM_BLD *OSSL_PARAM_BLD_new(void);
24        OSSL_PARAM *OSSL_PARAM_BLD_to_param(OSSL_PARAM_BLD *bld);
25        void OSSL_PARAM_BLD_free(OSSL_PARAM_BLD *bld);
26
27        int OSSL_PARAM_BLD_push_TYPE(OSSL_PARAM_BLD *bld, const char *key, TYPE val);
28
29        int OSSL_PARAM_BLD_push_BN(OSSL_PARAM_BLD *bld, const char *key,
30                                   const BIGNUM *bn);
31        int OSSL_PARAM_BLD_push_BN_pad(OSSL_PARAM_BLD *bld, const char *key,
32                                       const BIGNUM *bn, size_t sz);
33
34        int OSSL_PARAM_BLD_push_utf8_string(OSSL_PARAM_BLD *bld, const char *key,
35                                            const char *buf, size_t bsize);
36        int OSSL_PARAM_BLD_push_utf8_ptr(OSSL_PARAM_BLD *bld, const char *key,
37                                         char *buf, size_t bsize);
38        int OSSL_PARAM_BLD_push_octet_string(OSSL_PARAM_BLD *bld, const char *key,
39                                             const void *buf, size_t bsize);
40        int OSSL_PARAM_BLD_push_octet_ptr(OSSL_PARAM_BLD *bld, const char *key,
41                                          void *buf, size_t bsize);
42

DESCRIPTION

44       A collection of utility functions that simplify the creation of
45       OSSL_PARAM arrays.  The TYPE names are as per OSSL_PARAM_int(3).
46
47       OSSL_PARAM_BLD_new() allocates and initialises a new OSSL_PARAM_BLD
48       structure so that values can be added.  Any existing values are
49       cleared.
50
51       OSSL_PARAM_BLD_free() deallocates the memory allocates by
52       OSSL_PARAM_BLD_new().
53
54       OSSL_PARAM_BLD_to_param() converts a built up OSSL_PARAM_BLD structure
55       bld into an allocated OSSL_PARAM array.  The OSSL_PARAM array and all
56       associated storage must be freed by calling OSSL_PARAM_free() with the
57       functions return value.  OSSL_PARAM_BLD_free() can safely be called any
58       time after this function is.
59
60       OSSL_PARAM_BLD_push_TYPE() are a series of functions which will create
61       OSSL_PARAM objects of the specified size and correct type for the val
62       argument.  val is stored by value and an expression or auto variable
63       can be used.
64
65       OSSL_PARAM_BLD_push_BN() is a function that will create an OSSL_PARAM
66       object that holds the specified BIGNUM bn.  If bn is marked as being
67       securely allocated, its OSSL_PARAM representation will also be securely
68       allocated.  The bn argument is stored by reference and the underlying
69       BIGNUM object must exist until after OSSL_PARAM_BLD_to_param() has been
70       called.
71
72       OSSL_PARAM_BLD_push_BN_pad() is a function that will create an
73       OSSL_PARAM object that holds the specified BIGNUM bn.  The object will
74       be padded to occupy exactly sz bytes, if insufficient space is
75       specified an error results.  If bn is marked as being securely
76       allocated, its OSSL_PARAM representation will also be securely
77       allocated.  The bn argument is stored by reference and the underlying
78       BIGNUM object must exist until after OSSL_PARAM_BLD_to_param() has been
79       called.
80
81       OSSL_PARAM_BLD_push_utf8_string() is a function that will create an
82       OSSL_PARAM object that references the UTF8 string specified by buf.
83       The length of the string bsize should not include the terminating NUL
84       byte.  If it is zero then it will be calculated.  The string that buf
85       points to is stored by reference and must remain in scope until after
86       OSSL_PARAM_BLD_to_param() has been called.
87
88       OSSL_PARAM_BLD_push_octet_string() is a function that will create an
89       OSSL_PARAM object that references the octet string specified by buf and
90       <bsize>.  The memory that buf points to is stored by reference and must
91       remain in scope until after OSSL_PARAM_BLD_to_param() has been called.
92
93       OSSL_PARAM_BLD_push_utf8_ptr() is a function that will create an
94       OSSL_PARAM object that references the UTF8 string specified by buf.
95       The length of the string bsize should not include the terminating NUL
96       byte.  If it is zero then it will be calculated.  The string buf points
97       to is stored by reference and must remain in scope until the OSSL_PARAM
98       array is freed.
99
100       OSSL_PARAM_BLD_push_octet_ptr() is a function that will create an
101       OSSL_PARAM object that references the octet string specified by buf.
102       The memory buf points to is stored by reference and must remain in
103       scope until the OSSL_PARAM array is freed.
104

RETURN VALUES

106       OSSL_PARAM_BLD_new() returns the allocated OSSL_PARAM_BLD structure, or
107       NULL on error.
108
109       OSSL_PARAM_BLD_to_param() returns the allocated OSSL_PARAM array, or
110       NULL on error.
111
112       All of the OSSL_PARAM_BLD_push_TYPE functions return 1 on success and 0
113       on error.
114

NOTES

116       OSSL_PARAM_BLD_push_BN() and OSSL_PARAM_BLD_push_BN_pad() currently
117       only support nonnegative BIGNUMs.  They return an error on negative
118       BIGNUMs.
119

EXAMPLES

121       Both examples creating an OSSL_PARAM array that contains an RSA key.
122       For both, the predefined key variables are:
123
124           BIGNUM *p, *q;  /* both prime */
125           BIGNUM *n;      /* = p * q */
126           unsigned int e; /* exponent, usually 65537 */
127           BIGNUM *d;      /* e^-1 */
128
129   Example 1
130       This example shows how to create an OSSL_PARAM array that contains an
131       RSA private key.
132
133           OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new();
134           OSSL_PARAM *params = NULL;
135
136           if (bld == NULL
137               || !OSSL_PARAM_BLD_push_BN(bld, "p", p)
138               || !OSSL_PARAM_BLD_push_BN(bld, "q", q)
139               || !OSSL_PARAM_BLD_push_uint(bld, "e", e)
140               || !OSSL_PARAM_BLD_push_BN(bld, "n", n)
141               || !OSSL_PARAM_BLD_push_BN(bld, "d", d)
142               || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL)
143               goto err;
144           OSSL_PARAM_BLD_free(bld);
145           /* Use params */
146           ...
147           OSSL_PARAM_free(params);
148
149   Example 2
150       This example shows how to create an OSSL_PARAM array that contains an
151       RSA public key.
152
153           OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new();
154           OSSL_PARAM *params = NULL;
155
156           if (nld == NULL
157               || !OSSL_PARAM_BLD_push_BN(bld, "n", n)
158               || !OSSL_PARAM_BLD_push_BN(bld, "e", e)
159               || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL)
160               goto err;
161           OSSL_PARAM_BLD_free(bld);
162           /* Use params */
163           ...
164           OSSL_PARAM_free(params);
165

HISTORY

170       The functions described here were all added in OpenSSL 3.0.
171

COPYRIGHT

173       Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.
174
175       Licensed under the Apache License 2.0 (the "License").  You may not use
176       this file except in compliance with the License.  You can obtain a copy
177       in the file LICENSE in the source distribution or at
178       <https://www.openssl.org/source/license.html>.
179
180
181
1823.0.5                             2022-07-05             OSSL_PARAM_BLD(3ossl)