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