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