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