1OSSL_PARAM_INT(3ossl)               OpenSSL              OSSL_PARAM_INT(3ossl)
2
3
4

NAME

6       OSSL_PARAM_double, OSSL_PARAM_int, OSSL_PARAM_int32, OSSL_PARAM_int64,
7       OSSL_PARAM_long, OSSL_PARAM_size_t, OSSL_PARAM_time_t, OSSL_PARAM_uint,
8       OSSL_PARAM_uint32, OSSL_PARAM_uint64, OSSL_PARAM_ulong, OSSL_PARAM_BN,
9       OSSL_PARAM_utf8_string, OSSL_PARAM_octet_string, OSSL_PARAM_utf8_ptr,
10       OSSL_PARAM_octet_ptr, OSSL_PARAM_END, OSSL_PARAM_DEFN,
11       OSSL_PARAM_construct_double, OSSL_PARAM_construct_int,
12       OSSL_PARAM_construct_int32, OSSL_PARAM_construct_int64,
13       OSSL_PARAM_construct_long, OSSL_PARAM_construct_size_t,
14       OSSL_PARAM_construct_time_t, OSSL_PARAM_construct_uint,
15       OSSL_PARAM_construct_uint32, OSSL_PARAM_construct_uint64,
16       OSSL_PARAM_construct_ulong, OSSL_PARAM_construct_BN,
17       OSSL_PARAM_construct_utf8_string, OSSL_PARAM_construct_utf8_ptr,
18       OSSL_PARAM_construct_octet_string, OSSL_PARAM_construct_octet_ptr,
19       OSSL_PARAM_construct_end, OSSL_PARAM_locate, OSSL_PARAM_locate_const,
20       OSSL_PARAM_get_double, OSSL_PARAM_get_int, OSSL_PARAM_get_int32,
21       OSSL_PARAM_get_int64, OSSL_PARAM_get_long, OSSL_PARAM_get_size_t,
22       OSSL_PARAM_get_time_t, OSSL_PARAM_get_uint, OSSL_PARAM_get_uint32,
23       OSSL_PARAM_get_uint64, OSSL_PARAM_get_ulong, OSSL_PARAM_get_BN,
24       OSSL_PARAM_get_utf8_string, OSSL_PARAM_get_octet_string,
25       OSSL_PARAM_get_utf8_ptr, OSSL_PARAM_get_octet_ptr,
26       OSSL_PARAM_get_utf8_string_ptr, OSSL_PARAM_get_octet_string_ptr,
27       OSSL_PARAM_set_double, OSSL_PARAM_set_int, OSSL_PARAM_set_int32,
28       OSSL_PARAM_set_int64, OSSL_PARAM_set_long, OSSL_PARAM_set_size_t,
29       OSSL_PARAM_set_time_t, OSSL_PARAM_set_uint, OSSL_PARAM_set_uint32,
30       OSSL_PARAM_set_uint64, OSSL_PARAM_set_ulong, OSSL_PARAM_set_BN,
31       OSSL_PARAM_set_utf8_string, OSSL_PARAM_set_octet_string,
32       OSSL_PARAM_set_utf8_ptr, OSSL_PARAM_set_octet_ptr,
33       OSSL_PARAM_UNMODIFIED, OSSL_PARAM_modified,
34       OSSL_PARAM_set_all_unmodified - OSSL_PARAM helpers
35

SYNOPSIS

37        #include <openssl/params.h>
38
39        /*
40         * TYPE in function names is one of:
41         * double, int, int32, int64, long, size_t, time_t, uint, uint32, uint64, ulong
42         * Corresponding TYPE in function arguments is one of:
43         * double, int, int32_t, int64_t, long, size_t, time_t, unsigned int, uint32_t,
44         * uint64_t, unsigned long
45         */
46
47        #define OSSL_PARAM_TYPE(key, address)
48        #define OSSL_PARAM_BN(key, address, size)
49        #define OSSL_PARAM_utf8_string(key, address, size)
50        #define OSSL_PARAM_octet_string(key, address, size)
51        #define OSSL_PARAM_utf8_ptr(key, address, size)
52        #define OSSL_PARAM_octet_ptr(key, address, size)
53        #define OSSL_PARAM_END
54
55        #define OSSL_PARAM_UNMODIFIED
56
57        #define OSSL_PARAM_DEFN(key, type, addr, sz)    \
58           { (key), (type), (addr), (sz), OSSL_PARAM_UNMODIFIED }
59
60        OSSL_PARAM OSSL_PARAM_construct_TYPE(const char *key, TYPE *buf);
61        OSSL_PARAM OSSL_PARAM_construct_BN(const char *key, unsigned char *buf,
62                                           size_t bsize);
63        OSSL_PARAM OSSL_PARAM_construct_utf8_string(const char *key, char *buf,
64                                                    size_t bsize);
65        OSSL_PARAM OSSL_PARAM_construct_octet_string(const char *key, void *buf,
66                                                     size_t bsize);
67        OSSL_PARAM OSSL_PARAM_construct_utf8_ptr(const char *key, char **buf,
68                                                 size_t bsize);
69        OSSL_PARAM OSSL_PARAM_construct_octet_ptr(const char *key, void **buf,
70                                                  size_t bsize);
71        OSSL_PARAM OSSL_PARAM_construct_end(void);
72
73        OSSL_PARAM *OSSL_PARAM_locate(OSSL_PARAM *array, const char *key);
74        const OSSL_PARAM *OSSL_PARAM_locate_const(const OSSL_PARAM *array,
75                                                  const char *key);
76
77        int OSSL_PARAM_get_TYPE(const OSSL_PARAM *p, TYPE *val);
78        int OSSL_PARAM_set_TYPE(OSSL_PARAM *p, TYPE val);
79
80        int OSSL_PARAM_get_BN(const OSSL_PARAM *p, BIGNUM **val);
81        int OSSL_PARAM_set_BN(OSSL_PARAM *p, const BIGNUM *val);
82
83        int OSSL_PARAM_get_utf8_string(const OSSL_PARAM *p, char **val,
84                                       size_t max_len);
85        int OSSL_PARAM_set_utf8_string(OSSL_PARAM *p, const char *val);
86
87        int OSSL_PARAM_get_octet_string(const OSSL_PARAM *p, void **val,
88                                        size_t max_len, size_t *used_len);
89        int OSSL_PARAM_set_octet_string(OSSL_PARAM *p, const void *val, size_t len);
90
91        int OSSL_PARAM_get_utf8_ptr(const OSSL_PARAM *p, const char **val);
92        int OSSL_PARAM_set_utf8_ptr(OSSL_PARAM *p, const char *val);
93
94        int OSSL_PARAM_get_octet_ptr(const OSSL_PARAM *p, const void **val,
95                                     size_t *used_len);
96        int OSSL_PARAM_set_octet_ptr(OSSL_PARAM *p, const void *val,
97                                     size_t used_len);
98
99        int OSSL_PARAM_get_utf8_string_ptr(const OSSL_PARAM *p, const char **val);
100        int OSSL_PARAM_get_octet_string_ptr(const OSSL_PARAM *p, const void **val,
101                                            size_t *used_len);
102
103        int OSSL_PARAM_modified(const OSSL_PARAM *param);
104        void OSSL_PARAM_set_all_unmodified(OSSL_PARAM *params);
105

DESCRIPTION

107       A collection of utility functions that simplify and add type safety to
108       the OSSL_PARAM arrays.  The following TYPE names are supported:
109
110
111        double
112
113
114        int
115
116
117        int32 (int32_t)
118
119
120        int64 (int64_t)
121
122
123        long int (long)
124
125
126        time_t
127
128
129        size_t
130
131
132        uint32 (uint32_t)
133
134
135        uint64 (uint64_t)
136
137
138        unsigned int (uint)
139
140
141        unsigned long int (ulong)
142
143       OSSL_PARAM_TYPE() are a series of macros designed to assist
144       initialising an array of OSSL_PARAM structures.  Each of these macros
145       defines a parameter of the specified TYPE with the provided key and
146       parameter variable address.
147
148       OSSL_PARAM_utf8_string(), OSSL_PARAM_octet_string(),
149       OSSL_PARAM_utf8_ptr(), OSSL_PARAM_octet_ptr(), OSSL_PARAM_BN() are
150       macros that provide support for defining UTF8 strings, OCTET strings
151       and big numbers.  A parameter with name key is defined.  The storage
152       for this parameter is at address and is of size bytes.
153
154       OSSL_PARAM_END provides an end of parameter list marker.  This should
155       terminate all OSSL_PARAM arrays.
156
157       The OSSL_PARAM_DEFN() macro provides the ability to construct a single
158       OSSL_PARAM (typically used in the construction of OSSL_PARAM arrays).
159       The key, type, addr and sz arguments correspond to the key, data_type,
160       data and data_size fields of the OSSL_PARAM structure as described on
161       the OSSL_PARAM(3) page.
162
163       OSSL_PARAM_construct_TYPE() are a series of functions that create
164       OSSL_PARAM records dynamically.  A parameter with name key is created.
165       The parameter will use storage pointed to by buf and return size of
166       ret.
167
168       OSSL_PARAM_construct_BN() is a function that constructs a large integer
169       OSSL_PARAM structure.  A parameter with name key, storage buf, size
170       bsize and return size rsize is created.
171
172       OSSL_PARAM_construct_utf8_string() is a function that constructs a UTF8
173       string OSSL_PARAM structure.  A parameter with name key, storage buf
174       and size bsize is created.  If bsize is zero, the string length is
175       determined using strlen(3).  Generally pass zero for bsize instead of
176       calling strlen(3) yourself.
177
178       OSSL_PARAM_construct_octet_string() is a function that constructs an
179       OCTET string OSSL_PARAM structure.  A parameter with name key, storage
180       buf and size bsize is created.
181
182       OSSL_PARAM_construct_utf8_ptr() is a function that constructs a UTF8
183       string pointer OSSL_PARAM structure.  A parameter with name key,
184       storage pointer *buf and size bsize is created.
185
186       OSSL_PARAM_construct_octet_ptr() is a function that constructs an OCTET
187       string pointer OSSL_PARAM structure.  A parameter with name key,
188       storage pointer *buf and size bsize is created.
189
190       OSSL_PARAM_construct_end() is a function that constructs the
191       terminating OSSL_PARAM structure.
192
193       OSSL_PARAM_locate() is a function that searches an array of parameters
194       for the one matching the key name.
195
196       OSSL_PARAM_locate_const() behaves exactly like OSSL_PARAM_locate()
197       except for the presence of const for the array argument and its return
198       value.
199
200       OSSL_PARAM_get_TYPE() retrieves a value of type TYPE from the parameter
201       p.  The value is copied to the address val.  Type coercion takes place
202       as discussed in the NOTES section.
203
204       OSSL_PARAM_set_TYPE() stores a value val of type TYPE into the
205       parameter p.  If the parameter's data field is NULL, then only its
206       return_size field will be assigned the size the parameter's data buffer
207       should have.  Type coercion takes place as discussed in the NOTES
208       section.
209
210       OSSL_PARAM_get_BN() retrieves a BIGNUM from the parameter pointed to by
211       p.  The BIGNUM referenced by val is updated and is allocated if *val is
212       NULL.
213
214       OSSL_PARAM_set_BN() stores the BIGNUM val into the parameter p.  If the
215       parameter's data field is NULL, then only its return_size field will be
216       assigned the size the parameter's data buffer should have.
217
218       OSSL_PARAM_get_utf8_string() retrieves a UTF8 string from the parameter
219       pointed to by p.  The string is stored into *val with a size limit of
220       max_len, which must be large enough to accomodate a terminating NUL
221       byte, otherwise this function will fail.  If *val is NULL, memory is
222       allocated for the string (including the terminating  NUL byte) and
223       max_len is ignored.  If memory is allocated by this function, it must
224       be freed by the caller.
225
226       OSSL_PARAM_set_utf8_string() sets a UTF8 string from the parameter
227       pointed to by p to the value referenced by val.  If the parameter's
228       data field isn't NULL, its data_size must indicate that the buffer is
229       large enough to accomodate the string that val points at, not including
230       the terminating NUL byte, or this function will fail.  A terminating
231       NUL byte is added only if the parameter's data_size indicates the
232       buffer is longer than the string length, otherwise the string will not
233       be NUL terminated.  If the parameter's data field is NULL, then only
234       its return_size field will be assigned the minimum size the parameter's
235       data buffer should have to accomodate the string, not including a
236       terminating NUL byte.
237
238       OSSL_PARAM_get_octet_string() retrieves an OCTET string from the
239       parameter pointed to by p.  The OCTETs are either stored into *val with
240       a length limit of max_len or, in the case when *val is NULL, memory is
241       allocated and max_len is ignored. *used_len is populated with the
242       number of OCTETs stored. If val is NULL then the OCTETS are not stored,
243       but *used_len is still populated.  If memory is allocated by this
244       function, it must be freed by the caller.
245
246       OSSL_PARAM_set_octet_string() sets an OCTET string from the parameter
247       pointed to by p to the value referenced by val.  If the parameter's
248       data field is NULL, then only its return_size field will be assigned
249       the size the parameter's data buffer should have.
250
251       OSSL_PARAM_get_utf8_ptr() retrieves the UTF8 string pointer from the
252       parameter referenced by p and stores it in *val.
253
254       OSSL_PARAM_set_utf8_ptr() sets the UTF8 string pointer in the parameter
255       referenced by p to the values val.
256
257       OSSL_PARAM_get_octet_ptr() retrieves the OCTET string pointer from the
258       parameter referenced by p and stores it in *val.  The length of the
259       OCTET string is stored in *used_len.
260
261       OSSL_PARAM_set_octet_ptr() sets the OCTET string pointer in the
262       parameter referenced by p to the values val.  The length of the OCTET
263       string is provided by used_len.
264
265       OSSL_PARAM_get_utf8_string_ptr() retrieves the pointer to a UTF8 string
266       from the parameter pointed to by p, and stores that pointer in *val.
267       This is different from OSSL_PARAM_get_utf8_string(), which copies the
268       string.
269
270       OSSL_PARAM_get_octet_string_ptr() retrieves the pointer to a octet
271       string from the parameter pointed to by p, and stores that pointer in
272       *val, along with the string's length in *used_len.  This is different
273       from OSSL_PARAM_get_octet_string(), which copies the string.
274
275       The OSSL_PARAM_UNMODIFIED macro is used to detect if a parameter was
276       set.  On creation, via either the macros or construct calls, the
277       return_size field is set to this.  If the parameter is set using the
278       calls defined herein, the return_size field is changed.
279
280       OSSL_PARAM_modified() queries if the parameter param has been set or
281       not using the calls defined herein.
282
283       OSSL_PARAM_set_all_unmodified() resets the unused indicator for all
284       parameters in the array params.
285

RETURN VALUES

287       OSSL_PARAM_construct_TYPE(), OSSL_PARAM_construct_BN(),
288       OSSL_PARAM_construct_utf8_string(),
289       OSSL_PARAM_construct_octet_string(), OSSL_PARAM_construct_utf8_ptr()
290       and OSSL_PARAM_construct_octet_ptr() return a populated OSSL_PARAM
291       structure.
292
293       OSSL_PARAM_locate() and OSSL_PARAM_locate_const() return a pointer to
294       the matching OSSL_PARAM object.  They return NULL on error or when no
295       object matching key exists in the array.
296
297       OSSL_PARAM_modified() returns 1 if the parameter was set and 0
298       otherwise.
299
300       All other functions return 1 on success and 0 on failure.
301

NOTES

303       Native types will be converted as required only if the value is exactly
304       representable by the target type or parameter.  Apart from that, the
305       functions must be used appropriately for the expected type of the
306       parameter.
307
308       OSSL_PARAM_get_BN() and OSSL_PARAM_set_BN() currently only support
309       nonnegative BIGNUMs, and by consequence, only
310       OSSL_PARAM_UNSIGNED_INTEGER.  OSSL_PARAM_construct_BN() currently
311       constructs an OSSL_PARAM structure with the data type
312       OSSL_PARAM_UNSIGNED_INTEGER.
313
314       For OSSL_PARAM_construct_utf8_ptr() and
315       OSSL_PARAM_consstruct_octet_ptr(), bsize is not relevant if the purpose
316       is to send the OSSL_PARAM array to a responder, i.e. to get parameter
317       data back.  In that case, bsize can safely be given zero.  See
318       "DESCRIPTION" in OSSL_PARAM(3) for further information on the possible
319       purposes.
320

EXAMPLES

322       Reusing the examples from OSSL_PARAM(3) to just show how OSSL_PARAM
323       arrays can be handled using the macros and functions defined herein.
324
325   Example 1
326       This example is for setting parameters on some object:
327
328           #include <openssl/core.h>
329
330           const char *foo = "some string";
331           size_t foo_l = strlen(foo);
332           const char bar[] = "some other string";
333           const OSSL_PARAM set[] = {
334               OSSL_PARAM_utf8_ptr("foo", &foo, foo_l),
335               OSSL_PARAM_utf8_string("bar", bar, sizeof(bar) - 1),
336               OSSL_PARAM_END
337           };
338
339   Example 2
340       This example is for requesting parameters on some object, and also
341       demonstrates that the requestor isn't obligated to request all
342       available parameters:
343
344           const char *foo = NULL;
345           char bar[1024];
346           OSSL_PARAM request[] = {
347               OSSL_PARAM_utf8_ptr("foo", &foo, 0),
348               OSSL_PARAM_utf8_string("bar", bar, sizeof(bar)),
349               OSSL_PARAM_END
350           };
351
352       A responder that receives this array (as "params" in this example)
353       could fill in the parameters like this:
354
355           /* OSSL_PARAM *params */
356
357           OSSL_PARAM *p;
358
359           if ((p = OSSL_PARAM_locate(params, "foo")) != NULL)
360               OSSL_PARAM_set_utf8_ptr(p, "foo value");
361           if ((p = OSSL_PARAM_locate(params, "bar")) != NULL)
362               OSSL_PARAM_set_utf8_string(p, "bar value");
363           if ((p = OSSL_PARAM_locate(params, "cookie")) != NULL)
364               OSSL_PARAM_set_utf8_ptr(p, "cookie value");
365

SEE ALSO

367       openssl-core.h(7), OSSL_PARAM(3)
368

HISTORY

370       These APIs were introduced in OpenSSL 3.0.
371
373       Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
374
375       Licensed under the Apache License 2.0 (the "License").  You may not use
376       this file except in compliance with the License.  You can obtain a copy
377       in the file LICENSE in the source distribution or at
378       <https://www.openssl.org/source/license.html>.
379
380
381
3823.0.5                             2022-07-05             OSSL_PARAM_INT(3ossl)
Impressum