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