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