]>
Commit | Line | Data |
---|---|---|
7753be74 RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | OSSL_PARAM - a structure to pass or request object parameters | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/core.h> | |
10 | ||
11 | typedef struct ossl_param_st OSSL_PARAM; | |
12 | struct ossl_param_st { | |
13 | const char *key; /* the name of the parameter */ | |
8c4412ed RL |
14 | unsigned char data_type; /* declare what kind of content is in data */ |
15 | void *data; /* value being passed in or out */ | |
16 | size_t data_size; /* data size */ | |
4e7991b4 | 17 | size_t return_size; /* returned size */ |
7753be74 RL |
18 | }; |
19 | ||
20 | =head1 DESCRIPTION | |
21 | ||
d3ed4ded | 22 | B<OSSL_PARAM> is a type that allows passing arbitrary data for some |
7753be74 RL |
23 | object between two parties that have no or very little shared |
24 | knowledge about their respective internal structures for that object. | |
25 | ||
26 | A typical usage example could be an application that wants to set some | |
27 | parameters for an object, or wants to find out some parameters of an | |
28 | object. | |
29 | ||
3efe1914 | 30 | Arrays of this type can be used for the following purposes: |
7753be74 RL |
31 | |
32 | =over 4 | |
33 | ||
3efe1914 | 34 | =item * Setting parameters for some object |
7753be74 | 35 | |
d3ed4ded | 36 | The caller sets up the B<OSSL_PARAM> array and calls some function |
7753be74 | 37 | (the I<setter>) that has intimate knowledge about the object that can |
d3ed4ded | 38 | take the data from the B<OSSL_PARAM> array and assign them in a |
7753be74 RL |
39 | suitable form for the internal structure of the object. |
40 | ||
3efe1914 | 41 | =item * Request parameters of some object |
7753be74 | 42 | |
d3ed4ded | 43 | The caller (the I<requestor>) sets up the B<OSSL_PARAM> array and |
7753be74 RL |
44 | calls some function (the I<responder>) that has intimate knowledge |
45 | about the object, which can take the internal data of the object and | |
8c4412ed | 46 | copy (possibly convert) that to the memory prepared by the |
d3ed4ded | 47 | I<requestor> and pointed at with the B<OSSL_PARAM> I<data>. |
7753be74 | 48 | |
3efe1914 RL |
49 | =item * Request parameter descriptors |
50 | ||
d3ed4ded | 51 | The caller gets an array of constant B<OSSL_PARAM>, which describe |
3efe1914 RL |
52 | available parameters and some of their properties; name, data type and |
53 | expected data size. | |
54 | For a detailed description of each field for this use, see the field | |
55 | descriptions below. | |
56 | ||
57 | The caller may then use the information from this descriptor array to | |
d3ed4ded | 58 | build up its own B<OSSL_PARAM> array to pass down to a I<setter> or |
3efe1914 RL |
59 | I<responder>. |
60 | ||
7753be74 RL |
61 | =back |
62 | ||
45211c56 RL |
63 | Normally, the order of the an B<OSSL_PARAM> array is not relevant. |
64 | However, if the I<responder> can handle multiple elements with the | |
65 | same key, those elements must be handled in the order they are in. | |
66 | ||
c589c149 RL |
67 | An B<OSSL_PARAM> array must have a terminating element, where I<key> |
68 | is NULL. The usual full terminating template is: | |
69 | ||
70 | { NULL, 0, NULL, 0, 0 } | |
71 | ||
72 | This can also be specified using L<OSSL_PARAM_END(3)>. | |
73 | ||
355e1f04 RL |
74 | =head2 Functional support |
75 | ||
76 | Libcrypto offers a limited set of helper functions to handle | |
77 | B<OSSL_PARAM> items and arrays, please see L<OSSL_PARAM_get_int(3)>. | |
78 | Developers are free to extend or replace those as they see fit. | |
79 | ||
d3ed4ded | 80 | =head2 B<OSSL_PARAM> fields |
7753be74 RL |
81 | |
82 | =over 4 | |
83 | ||
d3ed4ded | 84 | =item I<key> |
7753be74 RL |
85 | |
86 | The identity of the parameter in the form of a string. | |
87 | ||
c589c149 RL |
88 | In an B<OSSL_PARAM> array, an item with this field set to NULL is |
89 | considered a terminating item. | |
90 | ||
d3ed4ded | 91 | =item I<data_type> |
7753be74 | 92 | |
d3ed4ded | 93 | The I<data_type> is a value that describes the type and organization of |
7753be74 RL |
94 | the data. |
95 | See L</Supported types> below for a description of the types. | |
96 | ||
d3ed4ded | 97 | =item I<data> |
7753be74 | 98 | |
d3ed4ded | 99 | =item I<data_size> |
7753be74 | 100 | |
d3ed4ded | 101 | I<data> is a pointer to the memory where the parameter data is (when |
7753be74 | 102 | setting parameters) or shall (when requesting parameters) be stored, |
d3ed4ded | 103 | and I<data_size> is its size in bytes. |
7753be74 RL |
104 | The organization of the data depends on the parameter type and flag. |
105 | ||
247a1786 RL |
106 | The I<data_size> needs special attention with the parameter type |
107 | B<OSSL_PARAM_UTF8_STRING> in relation to C strings. When setting | |
108 | parameters, the size should be set to the length of the string, not | |
109 | counting the terminating NUL byte. When requesting parameters, the | |
110 | size should be set to the size of the buffer to be populated, which | |
111 | should accomodate enough space for a terminating NUL byte. | |
112 | ||
d4d28783 RL |
113 | When I<requesting parameters>, it's acceptable for I<data> to be NULL. |
114 | This can be used by the I<requestor> to figure out dynamically exactly | |
115 | how much buffer space is needed to store the parameter data. | |
116 | In this case, I<data_size> is ignored. | |
117 | ||
d3ed4ded | 118 | When the B<OSSL_PARAM> is used as a parameter descriptor, I<data> |
3efe1914 | 119 | should be ignored. |
d3ed4ded | 120 | If I<data_size> is zero, it means that an arbitrary data size is |
3efe1914 RL |
121 | accepted, otherwise it specifies the maximum size allowed. |
122 | ||
d3ed4ded | 123 | =item I<return_size> |
7753be74 | 124 | |
d3ed4ded | 125 | When an array of B<OSSL_PARAM> is used to request data, the |
909ef4de RL |
126 | I<responder> must set this field to indicate size of the parameter |
127 | data, including padding as the case may be. | |
128 | In case the I<data_size> is an unsuitable size for the data, the | |
129 | I<responder> must still set this field to indicate the minimum data | |
130 | size required. | |
131 | (further notes on this in L</NOTES> below). | |
7753be74 | 132 | |
d3ed4ded RL |
133 | When the B<OSSL_PARAM> is used as a parameter descriptor, |
134 | I<return_size> should be ignored. | |
3efe1914 | 135 | |
7753be74 RL |
136 | =back |
137 | ||
138 | B<NOTE:> | |
139 | ||
140 | The key names and associated types are defined by the entity that | |
141 | offers these parameters, i.e. names for parameters provided by the | |
142 | OpenSSL libraries are defined by the libraries, and names for | |
143 | parameters provided by providers are defined by those providers, | |
144 | except for the pointer form of strings (see data type descriptions | |
145 | below). | |
146 | Entities that want to set or request parameters need to know what | |
147 | those keys are and of what type, any functionality between those two | |
d3ed4ded | 148 | entities should remain oblivious and just pass the B<OSSL_PARAM> array |
7753be74 RL |
149 | along. |
150 | ||
151 | =head2 Supported types | |
152 | ||
d3ed4ded | 153 | The I<data_type> field can be one of the following types: |
7753be74 RL |
154 | |
155 | =over 4 | |
156 | ||
d3ed4ded | 157 | =item B<OSSL_PARAM_INTEGER> |
7753be74 | 158 | |
d3ed4ded | 159 | =item B<OSSL_PARAM_UNSIGNED_INTEGER> |
7753be74 RL |
160 | |
161 | The parameter data is an integer (signed or unsigned) of arbitrary | |
162 | length, organized in native form, i.e. most significant byte first on | |
163 | Big-Endian systems, and least significant byte first on Little-Endian | |
164 | systems. | |
165 | ||
d3ed4ded | 166 | =item B<OSSL_PARAM_REAL> |
7753be74 | 167 | |
7753be74 RL |
168 | The parameter data is a floating point value in native form. |
169 | ||
d3ed4ded | 170 | =item B<OSSL_PARAM_UTF8_STRING> |
7753be74 RL |
171 | |
172 | The parameter data is a printable string. | |
173 | ||
d3ed4ded | 174 | =item B<OSSL_PARAM_OCTET_STRING> |
7753be74 RL |
175 | |
176 | The parameter data is an arbitrary string of bytes. | |
177 | ||
d3ed4ded | 178 | =item B<OSSL_PARAM_UTF8_PTR> |
7753be74 | 179 | |
7ffbd7ca | 180 | The parameter data is a pointer to a printable string. |
7753be74 | 181 | |
d3ed4ded | 182 | The difference between this and B<OSSL_PARAM_UTF8_STRING> is that I<data> |
7ffbd7ca | 183 | doesn't point directly at the data, but to a pointer that points to the data. |
7753be74 | 184 | |
82e1fc1b P |
185 | If there is any uncertainty about which to use, B<OSSL_PARAM_UTF8_STRING> is |
186 | almost certainly the correct choice. | |
187 | ||
7ffbd7ca | 188 | This is used to indicate that constant data is or will be passed, |
7753be74 RL |
189 | and there is therefore no need to copy the data that is passed, just |
190 | the pointer to it. | |
191 | ||
d3ed4ded | 192 | I<data_size> must be set to the size of the data, not the size of the |
7ffbd7ca P |
193 | pointer to the data. |
194 | If this is used in a parameter request, | |
d3ed4ded RL |
195 | I<data_size> is not relevant. However, the I<responder> will set |
196 | I<return_size> to the size of the data. | |
7753be74 | 197 | |
7ffbd7ca | 198 | Note that the use of this type is B<fragile> and can only be safely |
7753be74 RL |
199 | used for data that remains constant and in a constant location for a |
200 | long enough duration (such as the life-time of the entity that | |
201 | offers these parameters). | |
202 | ||
d3ed4ded | 203 | =item B<OSSL_PARAM_OCTET_PTR> |
7753be74 | 204 | |
7ffbd7ca | 205 | The parameter data is a pointer to an arbitrary string of bytes. |
7753be74 | 206 | |
d3ed4ded RL |
207 | The difference between this and B<OSSL_PARAM_OCTET_STRING> is that |
208 | I<data> doesn't point directly at the data, but to a pointer that | |
7ffbd7ca | 209 | points to the data. |
7753be74 | 210 | |
82e1fc1b P |
211 | If there is any uncertainty about which to use, B<OSSL_PARAM_OCTET_STRING> is |
212 | almost certainly the correct choice. | |
213 | ||
7ffbd7ca P |
214 | This is used to indicate that constant data is or will be passed, and |
215 | there is therefore no need to copy the data that is passed, just the | |
216 | pointer to it. | |
7753be74 | 217 | |
d3ed4ded | 218 | I<data_size> must be set to the size of the data, not the size of the |
7ffbd7ca P |
219 | pointer to the data. |
220 | If this is used in a parameter request, | |
d3ed4ded RL |
221 | I<data_size> is not relevant. However, the I<responder> will set |
222 | I<return_size> to the size of the data. | |
7753be74 | 223 | |
7ffbd7ca P |
224 | Note that the use of this type is B<fragile> and can only be safely |
225 | used for data that remains constant and in a constant location for a | |
226 | long enough duration (such as the life-time of the entity that | |
227 | offers these parameters). | |
7753be74 RL |
228 | |
229 | =back | |
230 | ||
231 | =head1 NOTES | |
232 | ||
233 | Both when setting and requesting parameters, the functions that are | |
234 | called will have to decide what is and what is not an error. | |
235 | The recommended behaviour is: | |
236 | ||
237 | =over 4 | |
238 | ||
239 | =item * | |
240 | ||
241 | Keys that a I<setter> or I<responder> doesn't recognise should simply | |
242 | be ignored. | |
243 | That in itself isn't an error. | |
244 | ||
245 | =item * | |
246 | ||
247 | If the keys that a called I<setter> recognises form a consistent | |
248 | enough set of data, that call should succeed. | |
249 | ||
250 | =item * | |
251 | ||
d3ed4ded RL |
252 | Apart from the I<return_size>, a I<responder> must never change the fields |
253 | of an B<OSSL_PARAM>. | |
4e7991b4 | 254 | To return a value, it should change the contents of the memory that |
d3ed4ded | 255 | I<data> points at. |
7753be74 RL |
256 | |
257 | =item * | |
258 | ||
259 | If the data type for a key that it's associated with is incorrect, | |
260 | the called function may return an error. | |
261 | ||
262 | The called function may also try to convert the data to a suitable | |
263 | form (for example, it's plausible to pass a large number as an octet | |
264 | string, so even though a given key is defined as an | |
d3ed4ded RL |
265 | B<OSSL_PARAM_UNSIGNED_INTEGER>, is plausible to pass the value as an |
266 | B<OSSL_PARAM_OCTET_STRING>), but this is in no way mandatory. | |
7753be74 RL |
267 | |
268 | =item * | |
269 | ||
8c4412ed | 270 | If a I<responder> finds that some data sizes are too small for the |
d3ed4ded | 271 | requested data, it must set I<return_size> for each such |
909ef4de RL |
272 | B<OSSL_PARAM> item to the minimum required size, and eventually return |
273 | an error. | |
274 | ||
275 | =item * | |
276 | ||
277 | For the integer type parameters (B<OSSL_PARAM_UNSIGNED_INTEGER> and | |
278 | B<OSSL_PARAM_INTEGER>), a I<responder> may choose to return an error | |
279 | if the I<data_size> isn't a suitable size (even if I<data_size> is | |
280 | bigger than needed). If the I<responder> finds the size suitable, it | |
281 | must fill all I<data_size> bytes and ensure correct padding for the | |
282 | native endianness, and set I<return_size> to the same value as | |
283 | I<data_size>. | |
7753be74 RL |
284 | |
285 | =back | |
286 | ||
287 | =begin comment RETURN VALUES doesn't make sense for a manual that only | |
288 | describes a type, but document checkers still want that section, and | |
289 | to have more than just the section title. | |
290 | ||
291 | =head1 RETURN VALUES | |
292 | ||
293 | txt | |
294 | ||
295 | =end comment | |
296 | ||
297 | =head1 EXAMPLES | |
298 | ||
d3ed4ded | 299 | A couple of examples to just show how B<OSSL_PARAM> arrays could be |
7753be74 RL |
300 | set up. |
301 | ||
302 | =head3 Example 1 | |
303 | ||
304 | This example is for setting parameters on some object: | |
305 | ||
306 | #include <openssl/core.h> | |
307 | ||
308 | const char *foo = "some string"; | |
309 | size_t foo_l = strlen(foo) + 1; | |
310 | const char bar[] = "some other string"; | |
4e7991b4 P |
311 | OSSL_PARAM set[] = { |
312 | { "foo", OSSL_PARAM_UTF8_STRING_PTR, &foo, foo_l, 0 }, | |
313 | { "bar", OSSL_PARAM_UTF8_STRING, &bar, sizeof(bar), 0 }, | |
c589c149 | 314 | { NULL, 0, NULL, 0, 0 } |
7753be74 RL |
315 | }; |
316 | ||
317 | =head3 Example 2 | |
318 | ||
319 | This example is for requesting parameters on some object: | |
320 | ||
321 | const char *foo = NULL; | |
322 | size_t foo_l; | |
323 | char bar[1024]; | |
324 | size_t bar_l; | |
4e7991b4 P |
325 | OSSL_PARAM request[] = { |
326 | { "foo", OSSL_PARAM_UTF8_STRING_PTR, &foo, 0 /*irrelevant*/, 0 }, | |
327 | { "bar", OSSL_PARAM_UTF8_STRING, &bar, sizeof(bar), 0 }, | |
c589c149 | 328 | { NULL, 0, NULL, 0, 0 } |
7753be74 RL |
329 | }; |
330 | ||
d3ed4ded | 331 | A I<responder> that receives this array (as I<params> in this example) |
7753be74 RL |
332 | could fill in the parameters like this: |
333 | ||
4e7991b4 | 334 | /* OSSL_PARAM *params */ |
7753be74 RL |
335 | |
336 | int i; | |
337 | ||
338 | for (i = 0; params[i].key != NULL; i++) { | |
339 | if (strcmp(params[i].key, "foo") == 0) { | |
8c4412ed | 340 | *(char **)params[i].data = "foo value"; |
4e7991b4 | 341 | params[i].return_size = 10; /* size of "foo value" */ |
7753be74 | 342 | } else if (strcmp(params[i].key, "bar") == 0) { |
c79b6b87 | 343 | memcpy(params[i].data, "bar value", 10); |
4e7991b4 | 344 | params[i].return_size = 10; /* size of "bar value" */ |
7753be74 RL |
345 | } |
346 | /* Ignore stuff we don't know */ | |
347 | } | |
348 | ||
349 | =head1 SEE ALSO | |
350 | ||
884314ca | 351 | L<openssl-core.h(7)>, L<OSSL_PARAM_get_int(3)>, L<OSSL_PARAM_dup(3)> |
7753be74 RL |
352 | |
353 | =head1 HISTORY | |
354 | ||
d3ed4ded | 355 | B<OSSL_PARAM> was added in OpenSSL 3.0. |
7753be74 RL |
356 | |
357 | =head1 COPYRIGHT | |
358 | ||
8020d79b | 359 | Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. |
7753be74 RL |
360 | |
361 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
362 | this file except in compliance with the License. You can obtain a copy | |
363 | in the file LICENSE in the source distribution or at | |
364 | L<https://www.openssl.org/source/license.html>. | |
365 | ||
366 | =cut |