xref: /openssl/doc/man3/OSSL_PARAM_BLD.pod (revision be92036b) 
1=pod
2
3=head1 NAME
4
5OSSL_PARAM_BLD, OSSL_PARAM_BLD_new, OSSL_PARAM_BLD_to_param,
6OSSL_PARAM_BLD_free, OSSL_PARAM_BLD_push_int,
7OSSL_PARAM_BLD_push_uint, OSSL_PARAM_BLD_push_long,
8OSSL_PARAM_BLD_push_ulong, OSSL_PARAM_BLD_push_int32,
9OSSL_PARAM_BLD_push_uint32, OSSL_PARAM_BLD_push_int64,
10OSSL_PARAM_BLD_push_uint64, OSSL_PARAM_BLD_push_size_t,
11OSSL_PARAM_BLD_push_time_t, OSSL_PARAM_BLD_push_double,
12OSSL_PARAM_BLD_push_BN, OSSL_PARAM_BLD_push_BN_pad,
13OSSL_PARAM_BLD_push_utf8_string, OSSL_PARAM_BLD_push_utf8_ptr,
14OSSL_PARAM_BLD_push_octet_string, OSSL_PARAM_BLD_push_octet_ptr
15- functions to assist in the creation of OSSL_PARAM arrays
16
17=head1 SYNOPSIS
18
19=for openssl generic
20
21 #include <openssl/param_build.h>
22
23 typedef struct OSSL_PARAM_BLD;
24
25 OSSL_PARAM_BLD *OSSL_PARAM_BLD_new(void);
26 OSSL_PARAM *OSSL_PARAM_BLD_to_param(OSSL_PARAM_BLD *bld);
27 void OSSL_PARAM_BLD_free(OSSL_PARAM_BLD *bld);
28
29 int OSSL_PARAM_BLD_push_TYPE(OSSL_PARAM_BLD *bld, const char *key, TYPE val);
30
31 int OSSL_PARAM_BLD_push_BN(OSSL_PARAM_BLD *bld, const char *key,
32                            const BIGNUM *bn);
33 int OSSL_PARAM_BLD_push_BN_pad(OSSL_PARAM_BLD *bld, const char *key,
34                                const BIGNUM *bn, size_t sz);
35
36 int OSSL_PARAM_BLD_push_utf8_string(OSSL_PARAM_BLD *bld, const char *key,
37                                     const char *buf, size_t bsize);
38 int OSSL_PARAM_BLD_push_utf8_ptr(OSSL_PARAM_BLD *bld, const char *key,
39                                  char *buf, size_t bsize);
40 int OSSL_PARAM_BLD_push_octet_string(OSSL_PARAM_BLD *bld, const char *key,
41                                      const void *buf, size_t bsize);
42 int OSSL_PARAM_BLD_push_octet_ptr(OSSL_PARAM_BLD *bld, const char *key,
43                                   void *buf, size_t bsize);
44
45
46=head1 DESCRIPTION
47
48A collection of utility functions that simplify the creation of OSSL_PARAM
49arrays.  The B<I<TYPE>> names are as per L<OSSL_PARAM_int(3)>.
50
51OSSL_PARAM_BLD_new() allocates and initialises a new OSSL_PARAM_BLD structure
52so that values can be added.
53Any existing values are cleared.
54
55OSSL_PARAM_BLD_free() deallocates the memory allocates by OSSL_PARAM_BLD_new().
56
57OSSL_PARAM_BLD_to_param() converts a built up OSSL_PARAM_BLD structure
58I<bld> into an allocated OSSL_PARAM array.
59The OSSL_PARAM array and all associated storage must be freed by calling
60OSSL_PARAM_free() with the functions return value.
61OSSL_PARAM_BLD_free() can safely be called any time after this function is.
62
63=begin comment
64
65POD is pretty good at recognising function names and making them appropriately
66bold...  however, when part of the function name is variable, we have to help
67the processor along
68
69=end comment
70
71B<OSSL_PARAM_BLD_push_I<TYPE>>() are a series of functions which will create
72OSSL_PARAM objects of the specified size and correct type for the I<val>
73argument.
74I<val> is stored by value and an expression or auto variable can be used.
75
76When B<I<TYPE>> denotes an integer type, signed integer types will normally
77get the OSSL_PARAM type B<OSSL_PARAM_INTEGER> params.
78When B<I<TYPE>> denotes an unsigned integer type will get the OSSL_PARAM type
79B<OSSL_PARAM_UNSIGNED_INTEGER>.
80
81OSSL_PARAM_BLD_push_BN() is a function that will create an OSSL_PARAM object
82that holds the specified BIGNUM I<bn>.
83When the I<bn> is zero or positive, its OSSL_PARAM type becomes
84B<OSSL_PARAM_UNSIGNED_INTEGER>.
85When the I<bn> is negative, its OSSL_PARAM type becomes B<OSSL_PARAM_INTEGER>.
86If I<bn> is marked as being securely allocated, its OSSL_PARAM representation
87will also be securely allocated.
88The I<bn> argument is stored by reference and the underlying BIGNUM object
89must exist until after OSSL_PARAM_BLD_to_param() has been called.
90
91OSSL_PARAM_BLD_push_BN_pad() is a function that will create an OSSL_PARAM object
92that holds the specified BIGNUM I<bn>.
93The object will be padded to occupy exactly I<sz> bytes, if insufficient space
94is specified an error results.
95When the I<bn> is zero or positive, its OSSL_PARAM type becomes
96B<OSSL_PARAM_UNSIGNED_INTEGER>.
97When the I<bn> is negative, its OSSL_PARAM type becomes B<OSSL_PARAM_INTEGER>.
98If I<bn> is marked as being securely allocated, its OSSL_PARAM representation
99will also be securely allocated.
100The I<bn> argument is stored by reference and the underlying BIGNUM object
101must exist until after OSSL_PARAM_BLD_to_param() has been called.
102
103OSSL_PARAM_BLD_push_utf8_string() is a function that will create an OSSL_PARAM
104object that references the UTF8 string specified by I<buf>.
105The length of the string I<bsize> should not include the terminating NUL byte.
106If it is zero then it will be calculated.
107The string that I<buf> points to is stored by reference and must remain in
108scope until after OSSL_PARAM_BLD_to_param() has been called.
109
110OSSL_PARAM_BLD_push_octet_string() is a function that will create an OSSL_PARAM
111object that references the octet string specified by I<buf> and <bsize>.
112The memory that I<buf> points to is stored by reference and must remain in
113scope until after OSSL_PARAM_BLD_to_param() has been called.
114
115OSSL_PARAM_BLD_push_utf8_ptr() is a function that will create an OSSL_PARAM
116object that references the UTF8 string specified by I<buf>.
117The length of the string I<bsize> should not include the terminating NUL byte.
118If it is zero then it will be calculated.
119The string I<buf> points to is stored by reference and must remain in
120scope until the OSSL_PARAM array is freed.
121
122OSSL_PARAM_BLD_push_octet_ptr() is a function that will create an OSSL_PARAM
123object that references the octet string specified by I<buf>.
124The memory I<buf> points to is stored by reference and must remain in
125scope until the OSSL_PARAM array is freed.
126
127=head1 RETURN VALUES
128
129OSSL_PARAM_BLD_new() returns the allocated OSSL_PARAM_BLD structure, or NULL
130on error.
131
132OSSL_PARAM_BLD_to_param() returns the allocated OSSL_PARAM array, or NULL
133on error.
134
135All of the OSSL_PARAM_BLD_push_TYPE functions return 1 on success and 0
136on error.
137
138=head1 NOTES
139
140OSSL_PARAM_BLD_push_BN() and OSSL_PARAM_BLD_push_BN_pad() only
141support nonnegative B<BIGNUM>s.  They return an error on negative
142B<BIGNUM>s.
143To pass signed B<BIGNUM>s, use OSSL_PARAM_BLD_push_signed_BN().
144
145=head1 EXAMPLES
146
147Both examples creating an OSSL_PARAM array that contains an RSA key.
148For both, the predefined key variables are:
149
150    BIGNUM *p, *q;  /* both prime */
151    BIGNUM *n;      /* = p * q */
152    unsigned int e; /* exponent, usually 65537 */
153    BIGNUM *d;      /* e^-1 */
154
155=head2 Example 1
156
157This example shows how to create an OSSL_PARAM array that contains an RSA
158private key.
159
160    OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new();
161    OSSL_PARAM *params = NULL;
162
163    if (bld == NULL
164        || !OSSL_PARAM_BLD_push_BN(bld, "p", p)
165        || !OSSL_PARAM_BLD_push_BN(bld, "q", q)
166        || !OSSL_PARAM_BLD_push_uint(bld, "e", e)
167        || !OSSL_PARAM_BLD_push_BN(bld, "n", n)
168        || !OSSL_PARAM_BLD_push_BN(bld, "d", d)
169        || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL)
170        goto err;
171    OSSL_PARAM_BLD_free(bld);
172    /* Use params */
173    ...
174    OSSL_PARAM_free(params);
175
176=head2 Example 2
177
178This example shows how to create an OSSL_PARAM array that contains an RSA
179public key.
180
181    OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new();
182    OSSL_PARAM *params = NULL;
183
184    if (nld == NULL
185        || !OSSL_PARAM_BLD_push_BN(bld, "n", n)
186        || !OSSL_PARAM_BLD_push_BN(bld, "e", e)
187        || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL)
188        goto err;
189    OSSL_PARAM_BLD_free(bld);
190    /* Use params */
191    ...
192    OSSL_PARAM_free(params);
193
194=head1 SEE ALSO
195
196L<OSSL_PARAM_int(3)>, L<OSSL_PARAM(3)>, L<OSSL_PARAM_free(3)>
197
198=head1 HISTORY
199
200The functions described here were all added in OpenSSL 3.0.
201
202=head1 COPYRIGHT
203
204Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.
205
206Licensed under the Apache License 2.0 (the "License").  You may not use
207this file except in compliance with the License.  You can obtain a copy
208in the file LICENSE in the source distribution or at
209L<https://www.openssl.org/source/license.html>.
210
211=cut
212