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().
56If the argument is NULL, nothing is done.
57
58OSSL_PARAM_BLD_to_param() converts a built up OSSL_PARAM_BLD structure
59I<bld> into an allocated OSSL_PARAM array.
60The OSSL_PARAM array and all associated storage must be freed by calling
61OSSL_PARAM_free() with the functions return value.
62OSSL_PARAM_BLD_free() can safely be called any time after this function is.
63
64=begin comment
65
66POD is pretty good at recognising function names and making them appropriately
67bold...  however, when part of the function name is variable, we have to help
68the processor along
69
70=end comment
71
72B<OSSL_PARAM_BLD_push_I<TYPE>>() are a series of functions which will create
73OSSL_PARAM objects of the specified size and correct type for the I<val>
74argument.
75I<val> is stored by value and an expression or auto variable can be used.
76
77OSSL_PARAM_BLD_push_BN() is a function that will create an OSSL_PARAM object
78that holds the specified BIGNUM I<bn>.
79If I<bn> is marked as being securely allocated, its OSSL_PARAM representation
80will also be securely allocated.
81The I<bn> argument is stored by reference and the underlying BIGNUM object
82must exist until after OSSL_PARAM_BLD_to_param() has been called.
83
84OSSL_PARAM_BLD_push_BN_pad() is a function that will create an OSSL_PARAM object
85that holds the specified BIGNUM I<bn>.
86The object will be padded to occupy exactly I<sz> bytes, if insufficient space
87is specified an error results.
88If I<bn> is marked as being securely allocated, its OSSL_PARAM representation
89will also be securely allocated.
90The I<bn> argument is stored by reference and the underlying BIGNUM object
91must exist until after OSSL_PARAM_BLD_to_param() has been called.
92
93OSSL_PARAM_BLD_push_utf8_string() is a function that will create an OSSL_PARAM
94object that references the UTF8 string specified by I<buf>.
95The length of the string I<bsize> should not include the terminating NUL byte.
96If it is zero then it will be calculated.
97The string that I<buf> points to is stored by reference and must remain in
98scope until after OSSL_PARAM_BLD_to_param() has been called.
99
100OSSL_PARAM_BLD_push_octet_string() is a function that will create an OSSL_PARAM
101object that references the octet string specified by I<buf> and <bsize>.
102The memory that I<buf> points to is stored by reference and must remain in
103scope until after OSSL_PARAM_BLD_to_param() has been called.
104
105OSSL_PARAM_BLD_push_utf8_ptr() is a function that will create an OSSL_PARAM
106object that references the UTF8 string specified by I<buf>.
107The length of the string I<bsize> should not include the terminating NUL byte.
108If it is zero then it will be calculated.
109The string I<buf> points to is stored by reference and must remain in
110scope until the OSSL_PARAM array is freed.
111
112OSSL_PARAM_BLD_push_octet_ptr() is a function that will create an OSSL_PARAM
113object that references the octet string specified by I<buf>.
114The memory I<buf> points to is stored by reference and must remain in
115scope until the OSSL_PARAM array is freed.
116
117=head1 RETURN VALUES
118
119OSSL_PARAM_BLD_new() returns the allocated OSSL_PARAM_BLD structure, or NULL
120on error.
121
122OSSL_PARAM_BLD_to_param() returns the allocated OSSL_PARAM array, or NULL
123on error.
124
125All of the OSSL_PARAM_BLD_push_TYPE functions return 1 on success and 0
126on error.
127
128=head1 NOTES
129
130OSSL_PARAM_BLD_push_BN() and OSSL_PARAM_BLD_push_BN_pad() currently only
131support nonnegative B<BIGNUM>s.  They return an error on negative B<BIGNUM>s.
132
133=head1 EXAMPLES
134
135Both examples creating an OSSL_PARAM array that contains an RSA key.
136For both, the predefined key variables are:
137
138    BIGNUM *n;           /* modulus */
139    unsigned int e;      /* public exponent */
140    BIGNUM *d;           /* private exponent */
141    BIGNUM *p, *q;       /* first two prime factors */
142    BIGNUM *dmp1, *dmq1; /* first two CRT exponents */
143    BIGNUM *iqmp;        /* first CRT coefficient */
144
145=head2 Example 1
146
147This example shows how to create an OSSL_PARAM array that contains an RSA
148private key.
149
150    OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new();
151    OSSL_PARAM *params = NULL;
152
153    if (bld == NULL
154        || !OSSL_PARAM_BLD_push_BN(bld, "n", n)
155        || !OSSL_PARAM_BLD_push_uint(bld, "e", e)
156        || !OSSL_PARAM_BLD_push_BN(bld, "d", d)
157        || !OSSL_PARAM_BLD_push_BN(bld, "rsa-factor1", p)
158        || !OSSL_PARAM_BLD_push_BN(bld, "rsa-factor2", q)
159        || !OSSL_PARAM_BLD_push_BN(bld, "rsa-exponent1", dmp1)
160        || !OSSL_PARAM_BLD_push_BN(bld, "rsa-exponent2", dmq1)
161        || !OSSL_PARAM_BLD_push_BN(bld, "rsa-coefficient1", iqmp)
162        || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL)
163        goto err;
164    OSSL_PARAM_BLD_free(bld);
165    /* Use params */
166    ...
167    OSSL_PARAM_free(params);
168
169=head2 Example 2
170
171This example shows how to create an OSSL_PARAM array that contains an RSA
172public key.
173
174    OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new();
175    OSSL_PARAM *params = NULL;
176
177    if (nld == NULL
178        || !OSSL_PARAM_BLD_push_BN(bld, "n", n)
179        || !OSSL_PARAM_BLD_push_uint(bld, "e", e)
180        || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL)
181        goto err;
182    OSSL_PARAM_BLD_free(bld);
183    /* Use params */
184    ...
185    OSSL_PARAM_free(params);
186
187=head1 SEE ALSO
188
189L<OSSL_PARAM_int(3)>, L<OSSL_PARAM(3)>, L<OSSL_PARAM_free(3)>
190
191=head1 HISTORY
192
193The functions described here were all added in OpenSSL 3.0.
194
195=head1 COPYRIGHT
196
197Copyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved.
198
199Licensed under the Apache License 2.0 (the "License").  You may not use
200this file except in compliance with the License.  You can obtain a copy
201in the file LICENSE in the source distribution or at
202L<https://www.openssl.org/source/license.html>.
203
204=cut
205