xref: /openssl/doc/man3/OSSL_PARAM_int.pod (revision 7f4bf185)
1=pod
2
3=head1 NAME
4
5OSSL_PARAM_double, OSSL_PARAM_int, OSSL_PARAM_int32, OSSL_PARAM_int64,
6OSSL_PARAM_long, OSSL_PARAM_size_t, OSSL_PARAM_time_t, OSSL_PARAM_uint,
7OSSL_PARAM_uint32, OSSL_PARAM_uint64, OSSL_PARAM_ulong, OSSL_PARAM_BN,
8OSSL_PARAM_utf8_string, OSSL_PARAM_octet_string, OSSL_PARAM_utf8_ptr,
9OSSL_PARAM_octet_ptr,
10OSSL_PARAM_END, OSSL_PARAM_DEFN,
11OSSL_PARAM_construct_double, OSSL_PARAM_construct_int,
12OSSL_PARAM_construct_int32, OSSL_PARAM_construct_int64,
13OSSL_PARAM_construct_long, OSSL_PARAM_construct_size_t,
14OSSL_PARAM_construct_time_t, OSSL_PARAM_construct_uint,
15OSSL_PARAM_construct_uint32, OSSL_PARAM_construct_uint64,
16OSSL_PARAM_construct_ulong, OSSL_PARAM_construct_BN,
17OSSL_PARAM_construct_utf8_string, OSSL_PARAM_construct_utf8_ptr,
18OSSL_PARAM_construct_octet_string, OSSL_PARAM_construct_octet_ptr,
19OSSL_PARAM_construct_end,
20OSSL_PARAM_locate, OSSL_PARAM_locate_const,
21OSSL_PARAM_get_double, OSSL_PARAM_get_int, OSSL_PARAM_get_int32,
22OSSL_PARAM_get_int64, OSSL_PARAM_get_long, OSSL_PARAM_get_size_t,
23OSSL_PARAM_get_time_t, OSSL_PARAM_get_uint, OSSL_PARAM_get_uint32,
24OSSL_PARAM_get_uint64, OSSL_PARAM_get_ulong, OSSL_PARAM_get_BN,
25OSSL_PARAM_get_utf8_string, OSSL_PARAM_get_octet_string,
26OSSL_PARAM_get_utf8_ptr, OSSL_PARAM_get_octet_ptr,
27OSSL_PARAM_get_utf8_string_ptr, OSSL_PARAM_get_octet_string_ptr,
28OSSL_PARAM_set_double, OSSL_PARAM_set_int, OSSL_PARAM_set_int32,
29OSSL_PARAM_set_int64, OSSL_PARAM_set_long, OSSL_PARAM_set_size_t,
30OSSL_PARAM_set_time_t, OSSL_PARAM_set_uint, OSSL_PARAM_set_uint32,
31OSSL_PARAM_set_uint64, OSSL_PARAM_set_ulong, OSSL_PARAM_set_BN,
32OSSL_PARAM_set_utf8_string, OSSL_PARAM_set_octet_string,
33OSSL_PARAM_set_utf8_ptr, OSSL_PARAM_set_octet_ptr,
34OSSL_PARAM_UNMODIFIED, OSSL_PARAM_modified, OSSL_PARAM_set_all_unmodified
35- OSSL_PARAM helpers
36
37=head1 SYNOPSIS
38
39=for openssl generic
40
41 #include <openssl/params.h>
42
43 /*
44  * TYPE in function names is one of:
45  * double, int, int32, int64, long, size_t, time_t, uint, uint32, uint64, ulong
46  * Corresponding TYPE in function arguments is one of:
47  * double, int, int32_t, int64_t, long, size_t, time_t, unsigned int, uint32_t,
48  * uint64_t, unsigned long
49  */
50
51 #define OSSL_PARAM_TYPE(key, address)
52 #define OSSL_PARAM_BN(key, address, size)
53 #define OSSL_PARAM_utf8_string(key, address, size)
54 #define OSSL_PARAM_octet_string(key, address, size)
55 #define OSSL_PARAM_utf8_ptr(key, address, size)
56 #define OSSL_PARAM_octet_ptr(key, address, size)
57 #define OSSL_PARAM_END
58
59 #define OSSL_PARAM_UNMODIFIED
60
61 #define OSSL_PARAM_DEFN(key, type, addr, sz)    \
62    { (key), (type), (addr), (sz), OSSL_PARAM_UNMODIFIED }
63
64 OSSL_PARAM OSSL_PARAM_construct_TYPE(const char *key, TYPE *buf);
65 OSSL_PARAM OSSL_PARAM_construct_BN(const char *key, unsigned char *buf,
66                                    size_t bsize);
67 OSSL_PARAM OSSL_PARAM_construct_utf8_string(const char *key, char *buf,
68                                             size_t bsize);
69 OSSL_PARAM OSSL_PARAM_construct_octet_string(const char *key, void *buf,
70                                              size_t bsize);
71 OSSL_PARAM OSSL_PARAM_construct_utf8_ptr(const char *key, char **buf,
72                                          size_t bsize);
73 OSSL_PARAM OSSL_PARAM_construct_octet_ptr(const char *key, void **buf,
74                                           size_t bsize);
75 OSSL_PARAM OSSL_PARAM_construct_end(void);
76
77 OSSL_PARAM *OSSL_PARAM_locate(OSSL_PARAM *array, const char *key);
78 const OSSL_PARAM *OSSL_PARAM_locate_const(const OSSL_PARAM *array,
79                                           const char *key);
80
81 int OSSL_PARAM_get_TYPE(const OSSL_PARAM *p, TYPE *val);
82 int OSSL_PARAM_set_TYPE(OSSL_PARAM *p, TYPE val);
83
84 int OSSL_PARAM_get_BN(const OSSL_PARAM *p, BIGNUM **val);
85 int OSSL_PARAM_set_BN(OSSL_PARAM *p, const BIGNUM *val);
86
87 int OSSL_PARAM_get_utf8_string(const OSSL_PARAM *p, char **val,
88                                size_t max_len);
89 int OSSL_PARAM_set_utf8_string(OSSL_PARAM *p, const char *val);
90
91 int OSSL_PARAM_get_octet_string(const OSSL_PARAM *p, void **val,
92                                 size_t max_len, size_t *used_len);
93 int OSSL_PARAM_set_octet_string(OSSL_PARAM *p, const void *val, size_t len);
94
95 int OSSL_PARAM_get_utf8_ptr(const OSSL_PARAM *p, const char **val);
96 int OSSL_PARAM_set_utf8_ptr(OSSL_PARAM *p, const char *val);
97
98 int OSSL_PARAM_get_octet_ptr(const OSSL_PARAM *p, const void **val,
99                              size_t *used_len);
100 int OSSL_PARAM_set_octet_ptr(OSSL_PARAM *p, const void *val,
101                              size_t used_len);
102
103 int OSSL_PARAM_get_utf8_string_ptr(const OSSL_PARAM *p, const char **val);
104 int OSSL_PARAM_get_octet_string_ptr(const OSSL_PARAM *p, const void **val,
105                                     size_t *used_len);
106
107 int OSSL_PARAM_modified(const OSSL_PARAM *param);
108 void OSSL_PARAM_set_all_unmodified(OSSL_PARAM *params);
109
110=head1 DESCRIPTION
111
112A collection of utility functions that simplify and add type safety to the
113L<OSSL_PARAM(3)> arrays.  The following B<I<TYPE>> names are supported:
114
115=over 2
116
117=item *
118
119double
120
121=item *
122
123int
124
125=item *
126
127int32 (int32_t)
128
129=item *
130
131int64 (int64_t)
132
133=item *
134
135long int (long)
136
137=item *
138
139time_t
140
141=item *
142
143size_t
144
145=item *
146
147uint32 (uint32_t)
148
149=item *
150
151uint64 (uint64_t)
152
153=item *
154
155unsigned int (uint)
156
157=item *
158
159unsigned long int (ulong)
160
161=back
162
163OSSL_PARAM_TYPE() are a series of macros designed to assist initialising an
164array of L<OSSL_PARAM(3)> structures.
165Each of these macros defines a parameter of the specified B<I<TYPE>> with the
166provided I<key> and parameter variable I<address>.
167
168OSSL_PARAM_utf8_string(), OSSL_PARAM_octet_string(), OSSL_PARAM_utf8_ptr(),
169OSSL_PARAM_octet_ptr(), OSSL_PARAM_BN() are macros that provide support
170for defining UTF8 strings, OCTET strings and big numbers.
171A parameter with name I<key> is defined.
172The storage for this parameter is at I<address> and is of I<size> bytes.
173
174OSSL_PARAM_END provides an end of parameter list marker.
175This should terminate all L<OSSL_PARAM(3)> arrays.
176
177The OSSL_PARAM_DEFN() macro provides the ability to construct a single
178L<OSSL_PARAM(3)> (typically used in the construction of B<OSSL_PARAM> arrays). The
179I<key>, I<type>, I<addr> and I<sz> arguments correspond to the I<key>,
180I<data_type>, I<data> and I<data_size> fields of the L<OSSL_PARAM(3)> structure as
181described on the L<OSSL_PARAM(3)> page.
182
183OSSL_PARAM_construct_TYPE() are a series of functions that create L<OSSL_PARAM(3)>
184records dynamically.
185A parameter with name I<key> is created.
186The parameter will use storage pointed to by I<buf> and return size of I<ret>.
187
188OSSL_PARAM_construct_BN() is a function that constructs a large integer
189L<OSSL_PARAM(3)> structure.
190A parameter with name I<key>, storage I<buf>, size I<bsize> and return
191size I<rsize> is created.
192
193OSSL_PARAM_construct_utf8_string() is a function that constructs a UTF8
194string L<OSSL_PARAM(3)> structure.
195A parameter with name I<key>, storage I<buf> and size I<bsize> is created.
196If I<bsize> is zero, the string length is determined using strlen(3).
197Generally pass zero for I<bsize> instead of calling strlen(3) yourself.
198
199OSSL_PARAM_construct_octet_string() is a function that constructs an OCTET
200string L<OSSL_PARAM(3)> structure.
201A parameter with name I<key>, storage I<buf> and size I<bsize> is created.
202
203OSSL_PARAM_construct_utf8_ptr() is a function that constructs a UTF8 string
204pointer L<OSSL_PARAM(3)> structure.
205A parameter with name I<key>, storage pointer I<*buf> and size I<bsize>
206is created.
207
208OSSL_PARAM_construct_octet_ptr() is a function that constructs an OCTET string
209pointer L<OSSL_PARAM(3)> structure.
210A parameter with name I<key>, storage pointer I<*buf> and size I<bsize>
211is created.
212
213OSSL_PARAM_construct_end() is a function that constructs the terminating
214L<OSSL_PARAM(3)> structure.
215
216OSSL_PARAM_locate() is a function that searches an I<array> of parameters for
217the one matching the I<key> name.
218
219OSSL_PARAM_locate_const() behaves exactly like OSSL_PARAM_locate() except for
220the presence of I<const> for the I<array> argument and its return value.
221
222OSSL_PARAM_get_TYPE() retrieves a value of type B<I<TYPE>> from the parameter
223I<p>.
224The value is copied to the address I<val>.
225Type coercion takes place as discussed in the NOTES section.
226
227OSSL_PARAM_set_TYPE() stores a value I<val> of type B<I<TYPE>> into the
228parameter I<p>.
229If the parameter's I<data> field is NULL, then only its I<return_size> field
230will be assigned the size the parameter's I<data> buffer should have.
231Type coercion takes place as discussed in the NOTES section.
232
233OSSL_PARAM_get_BN() retrieves a BIGNUM from the parameter pointed to by I<p>.
234The BIGNUM referenced by I<val> is updated and is allocated if I<*val> is
235NULL.
236
237OSSL_PARAM_set_BN() stores the BIGNUM I<val> into the parameter I<p>.
238If the parameter's I<data> field is NULL, then only its I<return_size> field
239will be assigned the size the parameter's I<data> buffer should have.
240
241OSSL_PARAM_get_utf8_string() retrieves a UTF8 string from the parameter
242pointed to by I<p>.
243The string is stored into I<*val> with a size limit of I<max_len>,
244which must be large enough to accommodate a terminating NUL byte,
245otherwise this function will fail.
246If I<*val> is NULL, memory is allocated for the string (including the
247terminating  NUL byte) and I<max_len> is ignored.
248If memory is allocated by this function, it must be freed by the caller.
249
250OSSL_PARAM_set_utf8_string() sets a UTF8 string from the parameter pointed to
251by I<p> to the value referenced by I<val>.
252If the parameter's I<data> field isn't NULL, its I<data_size> must indicate
253that the buffer is large enough to accommodate the string that I<val> points at,
254not including the terminating NUL byte, or this function will fail.
255A terminating NUL byte is added only if the parameter's I<data_size> indicates
256the buffer is longer than the string length, otherwise the string will not be
257NUL terminated.
258If the parameter's I<data> field is NULL, then only its I<return_size> field
259will be assigned the minimum size the parameter's I<data> buffer should have
260to accommodate the string, not including a terminating NUL byte.
261
262OSSL_PARAM_get_octet_string() retrieves an OCTET string from the parameter
263pointed to by I<p>.
264The OCTETs are either stored into I<*val> with a length limit of I<max_len> or,
265in the case when I<*val> is NULL, memory is allocated and
266I<max_len> is ignored. I<*used_len> is populated with the number of OCTETs
267stored. If I<val> is NULL then the OCTETS are not stored, but I<*used_len> is
268still populated.
269If memory is allocated by this function, it must be freed by the caller.
270
271OSSL_PARAM_set_octet_string() sets an OCTET string from the parameter
272pointed to by I<p> to the value referenced by I<val>.
273If the parameter's I<data> field is NULL, then only its I<return_size> field
274will be assigned the size the parameter's I<data> buffer should have.
275
276OSSL_PARAM_get_utf8_ptr() retrieves the UTF8 string pointer from the parameter
277referenced by I<p> and stores it in I<*val>.
278
279OSSL_PARAM_set_utf8_ptr() sets the UTF8 string pointer in the parameter
280referenced by I<p> to the values I<val>.
281
282OSSL_PARAM_get_octet_ptr() retrieves the OCTET string pointer from the parameter
283referenced by I<p> and stores it in I<*val>.
284The length of the OCTET string is stored in I<*used_len>.
285
286OSSL_PARAM_set_octet_ptr() sets the OCTET string pointer in the parameter
287referenced by I<p> to the values I<val>.
288The length of the OCTET string is provided by I<used_len>.
289
290OSSL_PARAM_get_utf8_string_ptr() retrieves the pointer to a UTF8 string from
291the parameter pointed to by I<p>, and stores that pointer in I<*val>.
292This is different from OSSL_PARAM_get_utf8_string(), which copies the
293string.
294
295OSSL_PARAM_get_octet_string_ptr() retrieves the pointer to a octet string
296from the parameter pointed to by I<p>, and stores that pointer in I<*val>,
297along with the string's length in I<*used_len>.
298This is different from OSSL_PARAM_get_octet_string(), which copies the
299string.
300
301The OSSL_PARAM_UNMODIFIED macro is used to detect if a parameter was set.  On
302creation, via either the macros or construct calls, the I<return_size> field
303is set to this.  If the parameter is set using the calls defined herein, the
304I<return_size> field is changed.
305
306OSSL_PARAM_modified() queries if the parameter I<param> has been set or not
307using the calls defined herein.
308
309OSSL_PARAM_set_all_unmodified() resets the unused indicator for all parameters
310in the array I<params>.
311
312=head1 RETURN VALUES
313
314OSSL_PARAM_construct_TYPE(), OSSL_PARAM_construct_BN(),
315OSSL_PARAM_construct_utf8_string(), OSSL_PARAM_construct_octet_string(),
316OSSL_PARAM_construct_utf8_ptr() and OSSL_PARAM_construct_octet_ptr()
317return a populated L<OSSL_PARAM(3)> structure.
318
319OSSL_PARAM_locate() and OSSL_PARAM_locate_const() return a pointer to
320the matching L<OSSL_PARAM(3)> object.  They return NULL on error or when
321no object matching I<key> exists in the I<array>.
322
323OSSL_PARAM_modified() returns 1 if the parameter was set and 0 otherwise.
324
325All other functions return 1 on success and 0 on failure.
326
327=head1 NOTES
328
329Native types will be converted as required only if the value is exactly
330representable by the target type or parameter.
331Apart from that, the functions must be used appropriately for the
332expected type of the parameter.
333
334OSSL_PARAM_get_BN() and OSSL_PARAM_set_BN() only support nonnegative
335B<BIGNUM>s when the desired data type is B<OSSL_PARAM_UNSIGNED_INTEGER>.
336OSSL_PARAM_construct_BN() currently constructs an L<OSSL_PARAM(3)> structure
337with the data type B<OSSL_PARAM_UNSIGNED_INTEGER>.
338
339For OSSL_PARAM_construct_utf8_ptr() and OSSL_PARAM_consstruct_octet_ptr(),
340I<bsize> is not relevant if the purpose is to send the L<OSSL_PARAM(3)> array
341to a I<responder>, i.e. to get parameter data back.
342In that case, I<bsize> can safely be given zero.
343See L<OSSL_PARAM(3)/DESCRIPTION> for further information on the
344possible purposes.
345
346=head1 EXAMPLES
347
348Reusing the examples from L<OSSL_PARAM(3)> to just show how
349L<OSSL_PARAM(3)> arrays can be handled using the macros and functions
350defined herein.
351
352=head2 Example 1
353
354This example is for setting parameters on some object:
355
356    #include <openssl/core.h>
357
358    const char *foo = "some string";
359    size_t foo_l = strlen(foo);
360    const char bar[] = "some other string";
361    const OSSL_PARAM set[] = {
362        OSSL_PARAM_utf8_ptr("foo", &foo, foo_l),
363        OSSL_PARAM_utf8_string("bar", bar, sizeof(bar) - 1),
364        OSSL_PARAM_END
365    };
366
367=head2 Example 2
368
369This example is for requesting parameters on some object, and also
370demonstrates that the requester isn't obligated to request all
371available parameters:
372
373    const char *foo = NULL;
374    char bar[1024];
375    OSSL_PARAM request[] = {
376        OSSL_PARAM_utf8_ptr("foo", &foo, 0),
377        OSSL_PARAM_utf8_string("bar", bar, sizeof(bar)),
378        OSSL_PARAM_END
379    };
380
381A I<responder> that receives this array (as C<params> in this example)
382could fill in the parameters like this:
383
384    /* OSSL_PARAM *params */
385
386    OSSL_PARAM *p;
387
388    if ((p = OSSL_PARAM_locate(params, "foo")) != NULL)
389        OSSL_PARAM_set_utf8_ptr(p, "foo value");
390    if ((p = OSSL_PARAM_locate(params, "bar")) != NULL)
391        OSSL_PARAM_set_utf8_string(p, "bar value");
392    if ((p = OSSL_PARAM_locate(params, "cookie")) != NULL)
393        OSSL_PARAM_set_utf8_ptr(p, "cookie value");
394
395=head1 SEE ALSO
396
397L<openssl-core.h(7)>, L<OSSL_PARAM(3)>
398
399=head1 HISTORY
400
401These APIs were introduced in OpenSSL 3.0.
402
403=head1 COPYRIGHT
404
405Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved.
406
407Licensed under the Apache License 2.0 (the "License").  You may not use
408this file except in compliance with the License.  You can obtain a copy
409in the file LICENSE in the source distribution or at
410L<https://www.openssl.org/source/license.html>.
411
412=cut
413