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