]>
Commit | Line | Data |
---|---|---|
7ffbd7ca P |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
1313e37a P |
5 | OSSL_PARAM_double, OSSL_PARAM_int, OSSL_PARAM_int32, OSSL_PARAM_int64, |
6 | OSSL_PARAM_long, OSSL_PARAM_size_t, OSSL_PARAM_uint, OSSL_PARAM_uint32, | |
4e7991b4 | 7 | OSSL_PARAM_uint64, OSSL_PARAM_ulong, OSSL_PARAM_BN, OSSL_PARAM_utf8_string, |
1313e37a | 8 | OSSL_PARAM_octet_string, OSSL_PARAM_utf8_ptr, OSSL_PARAM_octet_ptr, |
a1c5cefa RL |
9 | OSSL_PARAM_END, |
10 | OSSL_PARAM_construct_double, OSSL_PARAM_construct_int, | |
11 | OSSL_PARAM_construct_int32, OSSL_PARAM_construct_int64, | |
12 | OSSL_PARAM_construct_long, OSSL_PARAM_construct_size_t, | |
13 | OSSL_PARAM_construct_uint, OSSL_PARAM_construct_uint32, | |
14 | OSSL_PARAM_construct_uint64, OSSL_PARAM_construct_ulong, | |
15 | OSSL_PARAM_construct_BN, OSSL_PARAM_construct_utf8_string, | |
16 | OSSL_PARAM_construct_utf8_ptr, OSSL_PARAM_construct_octet_string, | |
17 | OSSL_PARAM_construct_octet_ptr, OSSL_PARAM_construct_end, | |
18 | OSSL_PARAM_locate, OSSL_PARAM_locate_const, | |
4e7991b4 P |
19 | OSSL_PARAM_get_double, OSSL_PARAM_get_int, OSSL_PARAM_get_int32, |
20 | OSSL_PARAM_get_int64, OSSL_PARAM_get_long, OSSL_PARAM_get_size_t, | |
21 | OSSL_PARAM_get_uint, OSSL_PARAM_get_uint32, OSSL_PARAM_get_uint64, | |
a1c5cefa RL |
22 | OSSL_PARAM_get_ulong, OSSL_PARAM_get_BN, OSSL_PARAM_get_utf8_string, |
23 | OSSL_PARAM_get_octet_string, OSSL_PARAM_get_utf8_ptr, | |
24 | OSSL_PARAM_get_octet_ptr, | |
25 | OSSL_PARAM_set_double, OSSL_PARAM_set_int, OSSL_PARAM_set_int32, | |
26 | OSSL_PARAM_set_int64, OSSL_PARAM_set_long, OSSL_PARAM_set_size_t, | |
27 | OSSL_PARAM_set_uint, OSSL_PARAM_set_uint32, OSSL_PARAM_set_uint64, | |
28 | OSSL_PARAM_set_ulong, OSSL_PARAM_set_BN, OSSL_PARAM_set_utf8_string, | |
29 | OSSL_PARAM_set_octet_string, OSSL_PARAM_set_utf8_ptr, | |
8d5fb648 | 30 | OSSL_PARAM_set_octet_ptr, OSSL_PARAM_UNMODIFIED |
7ffbd7ca P |
31 | - OSSL_PARAM helpers |
32 | ||
33 | =head1 SYNOPSIS | |
34 | ||
bb82531f | 35 | =for openssl generic |
1313e37a | 36 | |
7ffbd7ca P |
37 | #include <openssl/params.h> |
38 | ||
a1c5cefa RL |
39 | /* |
40 | * TYPE in function names is one of: | |
41 | * double, int, int32, int64, long, size_t, uint, uint32, uint64, ulong | |
42 | * Corresponding TYPE in function arguments is one of: | |
43 | * double, int, int32_t, int64_t, long, size_t, unsigned int, uint32_t, | |
44 | * uint64_t, unsigned long | |
45 | */ | |
46 | ||
7ffbd7ca | 47 | #define OSSL_PARAM_TYPE(key, address) |
a1c5cefa | 48 | #define OSSL_PARAM_BN(key, address, size) |
7ffbd7ca P |
49 | #define OSSL_PARAM_utf8_string(key, address, size) |
50 | #define OSSL_PARAM_octet_string(key, address, size) | |
51 | #define OSSL_PARAM_utf8_ptr(key, address, size) | |
52 | #define OSSL_PARAM_octet_ptr(key, address, size) | |
7ffbd7ca P |
53 | #define OSSL_PARAM_END |
54 | ||
8d5fb648 P |
55 | #define OSSL_PARAM_UNMODIFIED |
56 | ||
a1c5cefa | 57 | OSSL_PARAM OSSL_PARAM_construct_TYPE(const char *key, TYPE *buf); |
7ffbd7ca | 58 | OSSL_PARAM OSSL_PARAM_construct_BN(const char *key, unsigned char *buf, |
4e7991b4 | 59 | size_t bsize); |
7ffbd7ca | 60 | OSSL_PARAM OSSL_PARAM_construct_utf8_string(const char *key, char *buf, |
4e7991b4 | 61 | size_t bsize); |
7ffbd7ca | 62 | OSSL_PARAM OSSL_PARAM_construct_octet_string(const char *key, void *buf, |
4e7991b4 | 63 | size_t bsize); |
7ffbd7ca | 64 | OSSL_PARAM OSSL_PARAM_construct_utf8_ptr(const char *key, char **buf, |
4e7991b4 | 65 | size_t bsize); |
7ffbd7ca | 66 | OSSL_PARAM OSSL_PARAM_construct_octet_ptr(const char *key, void **buf, |
4e7991b4 | 67 | size_t bsize); |
195852fe | 68 | OSSL_PARAM OSSL_PARAM_construct_end(void); |
7ffbd7ca P |
69 | |
70 | OSSL_PARAM *OSSL_PARAM_locate(OSSL_PARAM *array, const char *key); | |
4e7991b4 P |
71 | const OSSL_PARAM *OSSL_PARAM_locate_const(const OSSL_PARAM *array, |
72 | const char *key); | |
7ffbd7ca | 73 | |
a1c5cefa RL |
74 | int OSSL_PARAM_get_TYPE(const OSSL_PARAM *p, TYPE *val); |
75 | int OSSL_PARAM_set_TYPE(OSSL_PARAM *p, TYPE val); | |
7ffbd7ca | 76 | |
a1c5cefa RL |
77 | int OSSL_PARAM_get_BN(const OSSL_PARAM *p, BIGNUM **val); |
78 | int OSSL_PARAM_set_BN(OSSL_PARAM *p, const BIGNUM *val); | |
7ffbd7ca P |
79 | |
80 | int OSSL_PARAM_get_utf8_string(const OSSL_PARAM *p, char **val, | |
81 | size_t max_len); | |
4e7991b4 | 82 | int OSSL_PARAM_set_utf8_string(OSSL_PARAM *p, const char *val); |
7ffbd7ca P |
83 | |
84 | int OSSL_PARAM_get_octet_string(const OSSL_PARAM *p, void **val, | |
85 | size_t max_len, size_t *used_len); | |
4e7991b4 | 86 | int OSSL_PARAM_set_octet_string(OSSL_PARAM *p, const void *val, size_t len); |
7ffbd7ca | 87 | |
a1c5cefa RL |
88 | int OSSL_PARAM_get_utf8_ptr(const OSSL_PARAM *p, const char **val); |
89 | int OSSL_PARAM_set_utf8_ptr(OSSL_PARAM *p, const char *val); | |
7ffbd7ca | 90 | |
a1c5cefa | 91 | int OSSL_PARAM_get_octet_ptr(const OSSL_PARAM *p, const void **val, |
7ffbd7ca | 92 | size_t *used_len); |
a1c5cefa RL |
93 | int OSSL_PARAM_set_octet_ptr(OSSL_PARAM *p, const void *val, |
94 | size_t used_len); | |
7ffbd7ca | 95 | |
3873887e P |
96 | int OSSL_PARAM_modified(const OSSL_PARAM *param); |
97 | void OSSL_PARAM_set_all_unmodified(OSSL_PARAM *params); | |
8d5fb648 | 98 | |
7ffbd7ca P |
99 | =head1 DESCRIPTION |
100 | ||
101 | A collection of utility functions that simplify and add type safety to the | |
102 | OSSL_PARAM arrays. The following B<TYPE> names are supported: | |
103 | ||
104 | =over 1 | |
105 | ||
106 | =item * | |
107 | ||
108 | double | |
109 | ||
110 | =item * | |
111 | ||
112 | int | |
113 | ||
114 | =item * | |
115 | ||
116 | int32 (int32_t) | |
117 | ||
118 | =item * | |
119 | ||
120 | int64 (int64_t) | |
121 | ||
122 | =item * | |
123 | ||
124 | long int (long) | |
125 | ||
126 | =item * | |
127 | ||
128 | size_t | |
129 | ||
130 | =item * | |
131 | ||
132 | uint32 (uint32_t) | |
133 | ||
134 | =item * | |
135 | ||
136 | uint64 (uint64_t) | |
137 | ||
138 | =item * | |
139 | ||
140 | unsigned int (uint) | |
141 | ||
142 | =item * | |
143 | ||
144 | unsigned long int (ulong) | |
145 | ||
146 | =back | |
147 | ||
148 | OSSL_PARAM_TYPE() are a series of macros designed to assist initialising an | |
149 | array of OSSL_PARAM structures. | |
150 | Each of these macros defines a parameter of the specified B<TYPE> with the | |
151 | provided B<key> and parameter variable B<address>. | |
152 | ||
153 | OSSL_PARAM_utf8_string(), OSSL_PARAM_octet_string(), OSSL_PARAM_utf8_ptr(), | |
4e7991b4 P |
154 | OSSL_PARAM_octet_ptr(), OSSL_PARAM_BN() are macros that provide support |
155 | for defining UTF8 strings, OCTET strings and big numbers. | |
7ffbd7ca P |
156 | A parameter with name B<key> is defined. |
157 | The storage for this parameter is at B<address> and is of B<size> bytes. | |
158 | ||
7ffbd7ca P |
159 | OSSL_PARAM_END provides an end of parameter list marker. |
160 | This should terminate all OSSL_PARAM arrays. | |
161 | ||
162 | OSSL_PARAM_construct_TYPE() are a series of functions that create OSSL_PARAM | |
163 | records dynamically. | |
164 | A parameter with name B<key> is created. | |
165 | The parameter will use storage pointed to by B<buf> and return size of B<ret>. | |
166 | ||
167 | OSSL_PARAM_construct_BN() is a function that constructs a large integer | |
168 | OSSL_PARAM structure. | |
169 | A parameter with name B<key>, storage B<buf>, size B<bsize> and return | |
170 | size B<rsize> is created. | |
171 | ||
172 | OSSL_PARAM_construct_utf8_string() is a function that constructs a UTF8 | |
173 | string OSSL_PARAM structure. | |
7f588d20 | 174 | A parameter with name B<key>, storage B<buf> and size B<bsize> is created. |
8b6ffd40 P |
175 | If B<bsize> is zero, the string length is determined using strlen(3) + 1 for the |
176 | null termination byte. | |
177 | Generally pass zero for B<bsize> instead of calling strlen(3) yourself. | |
7ffbd7ca P |
178 | |
179 | OSSL_PARAM_construct_octet_string() is a function that constructs an OCTET | |
180 | string OSSL_PARAM structure. | |
7f588d20 | 181 | A parameter with name B<key>, storage B<buf> and size B<bsize> is created. |
7ffbd7ca P |
182 | |
183 | OSSL_PARAM_construct_utf8_ptr() is a function that constructes a UTF string | |
184 | pointer OSSL_PARAM structure. | |
7f588d20 P |
185 | A parameter with name B<key>, storage pointer B<*buf> and size B<bsize> |
186 | is created. | |
7ffbd7ca P |
187 | |
188 | OSSL_PARAM_construct_octet_ptr() is a function that constructes an OCTET string | |
189 | pointer OSSL_PARAM structure. | |
7f588d20 P |
190 | A parameter with name B<key>, storage pointer B<*buf> and size B<bsize> |
191 | is created. | |
7ffbd7ca | 192 | |
195852fe RL |
193 | OSSL_PARAM_construct_end() is a function that constructs the terminating |
194 | OSSL_PARAM structure. | |
195 | ||
7ffbd7ca P |
196 | OSSL_PARAM_locate() is a function that searches an B<array> of parameters for |
197 | the one matching the B<key> name. | |
198 | ||
4e7991b4 P |
199 | OSSL_PARAM_locate_const() behaves exactly like OSSL_PARAM_locate() except for |
200 | the presence of I<const> for the B<array> argument and its return value. | |
201 | ||
7ffbd7ca P |
202 | OSSL_PARAM_get_TYPE() retrieves a value of type B<TYPE> from the parameter B<p>. |
203 | The value is copied to the address B<val>. | |
204 | Type coercion takes place as discussed in the NOTES section. | |
205 | ||
c2969ff6 | 206 | OSSL_PARAM_set_TYPE() stores a value B<val> of type B<TYPE> into the parameter |
7ffbd7ca | 207 | B<p>. |
8f3b8fd6 RL |
208 | If the parameter's I<data> field is NULL, then only its I<return_size> field |
209 | will be assigned the size the parameter's I<data> buffer should have. | |
7ffbd7ca P |
210 | Type coercion takes place as discussed in the NOTES section. |
211 | ||
212 | OSSL_PARAM_get_BN() retrieves a BIGNUM from the parameter pointed to by B<p>. | |
213 | The BIGNUM referenced by B<val> is updated and is allocated if B<*val> is | |
214 | B<NULL>. | |
215 | ||
c2969ff6 | 216 | OSSL_PARAM_set_BN() stores the BIGNUM B<val> into the parameter B<p>. |
8f3b8fd6 RL |
217 | If the parameter's I<data> field is NULL, then only its I<return_size> field |
218 | will be assigned the size the parameter's I<data> buffer should have. | |
7ffbd7ca P |
219 | |
220 | OSSL_PARAM_get_utf8_string() retrieves a UTF8 string from the parameter | |
221 | pointed to by B<p>. | |
222 | The string is either stored into B<*val> with a length limit of B<max_len> or, | |
223 | in the case when B<*val> is B<NULL>, memory is allocated for the string and | |
224 | B<max_len> is ignored. | |
225 | If memory is allocated by this function, it must be freed by the caller. | |
226 | ||
227 | OSSL_PARAM_set_utf8_string() sets a UTF8 string from the parameter pointed to | |
228 | by B<p> to the value referenced by B<val>. | |
8f3b8fd6 RL |
229 | If the parameter's I<data> field is NULL, then only its I<return_size> field |
230 | will be assigned the size the parameter's I<data> buffer should have. | |
7ffbd7ca P |
231 | |
232 | OSSL_PARAM_get_octet_string() retrieves an OCTET string from the parameter | |
233 | pointed to by B<p>. | |
234 | The OCTETs are either stored into B<*val> with a length limit of B<max_len> or, | |
235 | in the case when B<*val> is B<NULL>, memory is allocated and | |
236 | B<max_len> is ignored. | |
237 | If memory is allocated by this function, it must be freed by the caller. | |
238 | ||
239 | OSSL_PARAM_set_octet_string() sets an OCTET string from the parameter | |
240 | pointed to by B<p> to the value referenced by B<val>. | |
8f3b8fd6 RL |
241 | If the parameter's I<data> field is NULL, then only its I<return_size> field |
242 | will be assigned the size the parameter's I<data> buffer should have. | |
7ffbd7ca P |
243 | |
244 | OSSL_PARAM_get_utf8_ptr() retrieves the UTF8 string pointer from the parameter | |
245 | referenced by B<p> and stores it in B<*val>. | |
246 | ||
247 | OSSL_PARAM_set_utf8_ptr() sets the UTF8 string pointer in the parameter | |
248 | referenced by B<p> to the values B<val>. | |
249 | ||
250 | OSSL_PARAM_get_octet_ptr() retrieves the OCTET string pointer from the parameter | |
251 | referenced by B<p> and stores it in B<*val>. | |
252 | The length of the OCTET string is stored in B<*used_len>. | |
253 | ||
254 | OSSL_PARAM_set_octet_ptr() sets the OCTET string pointer in the parameter | |
255 | referenced by B<p> to the values B<val>. | |
256 | The length of the OCTET string is provided by B<used_len>. | |
257 | ||
8d5fb648 P |
258 | The OSSL_PARAM_UNMODIFIED macro is used to detect if a parameter was set. On |
259 | creation, via either the macros or construct calls, the I<return_size> field | |
260 | is set to this. If the parameter is set using the calls defined herein, the | |
261 | I<return_size> field is changed. | |
262 | ||
3873887e P |
263 | OSSL_PARAM_modified() queries if the parameter B<param> has been set or not |
264 | using the calls defined herein. | |
8d5fb648 | 265 | |
3873887e P |
266 | OSSL_PARAM_set_all_unmodified() resets the unused indicator for all parameters |
267 | in the array B<params>. | |
8d5fb648 | 268 | |
7ffbd7ca P |
269 | =head1 RETURN VALUES |
270 | ||
271 | OSSL_PARAM_construct_TYPE(), OSSL_PARAM_construct_BN(), | |
272 | OSSL_PARAM_construct_utf8_string(), OSSL_PARAM_construct_octet_string(), | |
273 | OSSL_PARAM_construct_utf8_ptr() and OSSL_PARAM_construct_octet_ptr() | |
274 | return a populated OSSL_PARAM structure. | |
275 | ||
4e7991b4 P |
276 | OSSL_PARAM_locate() and OSSL_PARAM_locate_const() return a pointer to |
277 | the matching OSSL_PARAM object. They return B<NULL> on error or when | |
278 | no object matching B<key> exists in the B<array>. | |
7ffbd7ca | 279 | |
8d5fb648 P |
280 | OSSL_PARAM_modified() returns B<1> if the parameter was set and B<0> otherwise. |
281 | ||
7ffbd7ca P |
282 | All other functions return B<1> on success and B<0> on failure. |
283 | ||
284 | =head1 NOTES | |
285 | ||
9830e7ea P |
286 | Native types will be converted as required only if the value is exactly |
287 | representable by the target type or parameter. | |
7ffbd7ca P |
288 | Apart from that, the functions must be used appropriately for the |
289 | expected type of the parameter. | |
290 | ||
8f3b8fd6 RL |
291 | For OSSL_PARAM_construct_utf8_ptr() and OSSL_PARAM_consstruct_octet_ptr(), |
292 | B<bsize> is not relevant if the purpose is to send the B<OSSL_PARAM> array | |
293 | to a I<responder>, i.e. to get parameter data back. | |
f55ed701 RL |
294 | In that case, B<bsize> can safely be given zero. |
295 | See L<OSSL_PARAM(3)/DESCRIPTION> for further information on the | |
296 | possible purposes. | |
297 | ||
7ffbd7ca P |
298 | =head1 EXAMPLES |
299 | ||
300 | Reusing the examples from L<OSSL_PARAM(3)> to just show how | |
301 | C<OSSL_PARAM> arrays can be handled using the macros and functions | |
302 | defined herein. | |
303 | ||
304 | =head2 Example 1 | |
305 | ||
306 | This example is for setting parameters on some object: | |
307 | ||
308 | #include <openssl/core.h> | |
309 | ||
310 | const char *foo = "some string"; | |
311 | size_t foo_l = strlen(foo) + 1; | |
312 | const char bar[] = "some other string"; | |
313 | const OSSL_PARAM set[] = { | |
314 | OSSL_PARAM_utf8_ptr("foo", foo, foo_l), | |
315 | OSSL_PARAM_utf8_string("bar", bar, sizeof(bar)), | |
316 | OSSL_PARAM_END | |
317 | }; | |
318 | ||
319 | =head2 Example 2 | |
320 | ||
16bfe6ce RL |
321 | This example is for requesting parameters on some object, and also |
322 | demonstrates that the requestor isn't obligated to request all | |
323 | available parameters: | |
7ffbd7ca P |
324 | |
325 | const char *foo = NULL; | |
7ffbd7ca | 326 | char bar[1024]; |
4e7991b4 P |
327 | OSSL_PARAM request[] = { |
328 | OSSL_PARAM_utf8_ptr("foo", foo, 0), | |
329 | OSSL_PARAM_utf8_string("bar", bar, sizeof(bar)), | |
7ffbd7ca P |
330 | OSSL_PARAM_END |
331 | }; | |
332 | ||
333 | A I<responder> that receives this array (as C<params> in this example) | |
334 | could fill in the parameters like this: | |
335 | ||
4e7991b4 | 336 | /* OSSL_PARAM *params */ |
7ffbd7ca | 337 | |
4e7991b4 | 338 | OSSL_PARAM *p; |
16bfe6ce RL |
339 | |
340 | if ((p = OSSL_PARAM_locate(params, "foo")) == NULL) | |
341 | OSSL_PARAM_set_utf8_ptr(p, "foo value"); | |
342 | if ((p = OSSL_PARAM_locate(params, "bar")) == NULL) | |
343 | OSSL_PARAM_set_utf8_ptr(p, "bar value"); | |
344 | if ((p = OSSL_PARAM_locate(params, "cookie")) == NULL) | |
345 | OSSL_PARAM_set_utf8_ptr(p, "cookie value"); | |
7ffbd7ca P |
346 | |
347 | =head1 SEE ALSO | |
348 | ||
349 | L<openssl-core.h(7)>, L<OSSL_PARAM(3)> | |
350 | ||
351 | =head1 HISTORY | |
352 | ||
4674aaf4 | 353 | These APIs were introduced in OpenSSL 3.0. |
7ffbd7ca P |
354 | |
355 | =head1 COPYRIGHT | |
356 | ||
33388b44 | 357 | Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved. |
7ffbd7ca P |
358 | |
359 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
360 | this file except in compliance with the License. You can obtain a copy | |
361 | in the file LICENSE in the source distribution or at | |
362 | L<https://www.openssl.org/source/license.html>. | |
363 | ||
364 | =cut |