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