5 OSSL_PARAM - a structure to pass or request object parameters
9 #include <openssl/core.h>
11 typedef struct ossl_param_st OSSL_PARAM;
12 struct ossl_param_st {
13 const char *key; /* the name of the parameter */
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 */
17 size_t return_size; /* returned size */
22 B<OSSL_PARAM> is a type that allows passing arbitrary data for some
23 object between two parties that have no or very little shared
24 knowledge about their respective internal structures for that object.
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
30 Arrays of this type can be used for the following purposes:
34 =item * Setting parameters for some object
36 The caller sets up the B<OSSL_PARAM> array and calls some function
37 (the I<setter>) that has intimate knowledge about the object that can
38 take the data from the B<OSSL_PARAM> array and assign them in a
39 suitable form for the internal structure of the object.
41 =item * Request parameters of some object
43 The caller (the I<requestor>) sets up the B<OSSL_PARAM> array and
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
46 copy (possibly convert) that to the memory prepared by the
47 I<requestor> and pointed at with the B<OSSL_PARAM> I<data>.
49 =item * Request parameter descriptors
51 The caller gets an array of constant B<OSSL_PARAM>, which describe
52 available parameters and some of their properties; name, data type and
54 For a detailed description of each field for this use, see the field
57 The caller may then use the information from this descriptor array to
58 build up its own B<OSSL_PARAM> array to pass down to a I<setter> or
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.
67 An B<OSSL_PARAM> array must have a terminating element, where I<key>
68 is NULL. The usual full terminating template is:
70 { NULL, 0, NULL, 0, 0 }
72 This can also be specified using L<OSSL_PARAM_END(3)>.
74 =head2 B<OSSL_PARAM> fields
80 The identity of the parameter in the form of a string.
82 In an B<OSSL_PARAM> array, an item with this field set to NULL is
83 considered a terminating item.
87 The I<data_type> is a value that describes the type and organization of
89 See L</Supported types> below for a description of the types.
95 I<data> is a pointer to the memory where the parameter data is (when
96 setting parameters) or shall (when requesting parameters) be stored,
97 and I<data_size> is its size in bytes.
98 The organization of the data depends on the parameter type and flag.
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.
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.
112 When the B<OSSL_PARAM> is used as a parameter descriptor, I<data>
114 If I<data_size> is zero, it means that an arbitrary data size is
115 accepted, otherwise it specifies the maximum size allowed.
119 When an array of B<OSSL_PARAM> is used to request data, the
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
125 (further notes on this in L</NOTES> below).
127 When the B<OSSL_PARAM> is used as a parameter descriptor,
128 I<return_size> should be ignored.
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
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
142 entities should remain oblivious and just pass the B<OSSL_PARAM> array
145 =head2 Supported types
147 The I<data_type> field can be one of the following types:
151 =item B<OSSL_PARAM_INTEGER>
153 =item B<OSSL_PARAM_UNSIGNED_INTEGER>
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
160 =item B<OSSL_PARAM_REAL>
162 The parameter data is a floating point value in native form.
164 =item B<OSSL_PARAM_UTF8_STRING>
166 The parameter data is a printable string.
168 =item B<OSSL_PARAM_OCTET_STRING>
170 The parameter data is an arbitrary string of bytes.
172 =item B<OSSL_PARAM_UTF8_PTR>
174 The parameter data is a pointer to a printable string.
176 The difference between this and B<OSSL_PARAM_UTF8_STRING> is that I<data>
177 doesn't point directly at the data, but to a pointer that points to the data.
179 If there is any uncertainty about which to use, B<OSSL_PARAM_UTF8_STRING> is
180 almost certainly the correct choice.
182 This is used to indicate that constant data is or will be passed,
183 and there is therefore no need to copy the data that is passed, just
186 I<data_size> must be set to the size of the data, not the size of the
188 If this is used in a parameter request,
189 I<data_size> is not relevant. However, the I<responder> will set
190 I<return_size> to the size of the data.
192 Note that the use of this type is B<fragile> and can only be safely
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).
197 =item B<OSSL_PARAM_OCTET_PTR>
199 The parameter data is a pointer to an arbitrary string of bytes.
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
205 If there is any uncertainty about which to use, B<OSSL_PARAM_OCTET_STRING> is
206 almost certainly the correct choice.
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
212 I<data_size> must be set to the size of the data, not the size of the
214 If this is used in a parameter request,
215 I<data_size> is not relevant. However, the I<responder> will set
216 I<return_size> to the size of the data.
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).
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:
235 Keys that a I<setter> or I<responder> doesn't recognise should simply
237 That in itself isn't an error.
241 If the keys that a called I<setter> recognises form a consistent
242 enough set of data, that call should succeed.
246 Apart from the I<return_size>, a I<responder> must never change the fields
248 To return a value, it should change the contents of the memory that
253 If the data type for a key that it's associated with is incorrect,
254 the called function may return an error.
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
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.
264 If a I<responder> finds that some data sizes are too small for the
265 requested data, it must set I<return_size> for each such
266 B<OSSL_PARAM> item to the minimum required size, and eventually return
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
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.
293 A couple of examples to just show how B<OSSL_PARAM> arrays could be
298 This example is for setting parameters on some object:
300 #include <openssl/core.h>
302 const char *foo = "some string";
303 size_t foo_l = strlen(foo) + 1;
304 const char bar[] = "some other string";
306 { "foo", OSSL_PARAM_UTF8_STRING_PTR, &foo, foo_l, 0 },
307 { "bar", OSSL_PARAM_UTF8_STRING, &bar, sizeof(bar), 0 },
308 { NULL, 0, NULL, 0, 0 }
313 This example is for requesting parameters on some object:
315 const char *foo = NULL;
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 },
322 { NULL, 0, NULL, 0, 0 }
325 A I<responder> that receives this array (as I<params> in this example)
326 could fill in the parameters like this:
328 /* OSSL_PARAM *params */
332 for (i = 0; params[i].key != NULL; i++) {
333 if (strcmp(params[i].key, "foo") == 0) {
334 *(char **)params[i].data = "foo value";
335 params[i].return_size = 10; /* size of "foo value" */
336 } else if (strcmp(params[i].key, "bar") == 0) {
337 memcpy(params[i].data, "bar value", 10);
338 params[i].return_size = 10; /* size of "bar value" */
340 /* Ignore stuff we don't know */
345 L<openssl-core.h(7)>, L<OSSL_PARAM_get_int(3)>, L<OSSL_PARAM_dup(3)>
349 B<OSSL_PARAM> was added in OpenSSL 3.0.
353 Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
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>.