1OSSL_PARAM_INT(3ossl) OpenSSL OSSL_PARAM_INT(3ossl)
2
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
37 #include <openssl/params.h>
38 /*
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 #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 #define OSSL_PARAM_UNMODIFIED
56 #define OSSL_PARAM_DEFN(key, type, addr, sz) \
58 { (key), (type), (addr), (sz), OSSL_PARAM_UNMODIFIED }
59 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 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 int OSSL_PARAM_get_TYPE(const OSSL_PARAM *p, TYPE *val);
78 int OSSL_PARAM_set_TYPE(OSSL_PARAM *p, TYPE val);
79 int OSSL_PARAM_get_BN(const OSSL_PARAM *p, BIGNUM **val);
81 int OSSL_PARAM_set_BN(OSSL_PARAM *p, const BIGNUM *val);
82 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 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 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 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 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 int OSSL_PARAM_modified(const OSSL_PARAM *param);
104 void OSSL_PARAM_set_all_unmodified(OSSL_PARAM *params);
105
107 A collection of utility functions that simplify and add type safety to
108 the OSSL_PARAM(3) arrays. The following TYPE names are supported:
109 •
111 double
112 •
114 int
115 •
117 int32 (int32_t)
118 •
120 int64 (int64_t)
121 •
123 long int (long)
124 •
126 time_t
127 •
129 size_t
130 •
132 uint32 (uint32_t)
133 •
135 uint64 (uint64_t)
136 •
138 unsigned int (uint)
139 •
141 unsigned long int (ulong)
142 OSSL_PARAM_TYPE() are a series of macros designed to assist
144 initialising an array of OSSL_PARAM(3) structures. Each of these
145 macros defines a parameter of the specified TYPE with the provided key
146 and parameter variable address.
147 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 OSSL_PARAM_END provides an end of parameter list marker. This should
155 terminate all OSSL_PARAM(3) arrays.
156 The OSSL_PARAM_DEFN() macro provides the ability to construct a single
158 OSSL_PARAM(3) (typically used in the construction of OSSL_PARAM
159 arrays). The key, type, addr and sz arguments correspond to the key,
160 data_type, data and data_size fields of the OSSL_PARAM(3) structure as
161 described on the OSSL_PARAM(3) page.
162 OSSL_PARAM_construct_TYPE() are a series of functions that create
164 OSSL_PARAM(3) records dynamically. A parameter with name key is
165 created. The parameter will use storage pointed to by buf and return
166 size of ret.
167 OSSL_PARAM_construct_BN() is a function that constructs a large integer
169 OSSL_PARAM(3) structure. A parameter with name key, storage buf, size
170 bsize and return size rsize is created.
171 OSSL_PARAM_construct_utf8_string() is a function that constructs a UTF8
173 string OSSL_PARAM(3) 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 OSSL_PARAM_construct_octet_string() is a function that constructs an
179 OCTET string OSSL_PARAM(3) structure. A parameter with name key,
180 storage buf and size bsize is created.
181 OSSL_PARAM_construct_utf8_ptr() is a function that constructs a UTF8
183 string pointer OSSL_PARAM(3) structure. A parameter with name key,
184 storage pointer *buf and size bsize is created.
185 OSSL_PARAM_construct_octet_ptr() is a function that constructs an OCTET
187 string pointer OSSL_PARAM(3) structure. A parameter with name key,
188 storage pointer *buf and size bsize is created.
189 OSSL_PARAM_construct_end() is a function that constructs the
191 terminating OSSL_PARAM(3) structure.
192 OSSL_PARAM_locate() is a function that searches an array of parameters
194 for the one matching the key name.
195 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 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 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 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 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 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 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 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 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 OSSL_PARAM_get_utf8_ptr() retrieves the UTF8 string pointer from the
252 parameter referenced by p and stores it in *val.
253 OSSL_PARAM_set_utf8_ptr() sets the UTF8 string pointer in the parameter
255 referenced by p to the values val.
256 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 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 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 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 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 OSSL_PARAM_modified() queries if the parameter param has been set or
281 not using the calls defined herein.
282 OSSL_PARAM_set_all_unmodified() resets the unused indicator for all
284 parameters in the array params.
285
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(3)
291 structure.
292 OSSL_PARAM_locate() and OSSL_PARAM_locate_const() return a pointer to
294 the matching OSSL_PARAM(3) object. They return NULL on error or when
295 no object matching key exists in the array.
296 OSSL_PARAM_modified() returns 1 if the parameter was set and 0
298 otherwise.
299 All other functions return 1 on success and 0 on failure.
301
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 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(3) structure with the data type
312 OSSL_PARAM_UNSIGNED_INTEGER.
313 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(3) array to a responder, i.e. to get
317 parameter data back. In that case, bsize can safely be given zero.
318 See "DESCRIPTION" in OSSL_PARAM(3) for further information on the
319 possible purposes.
320
322 Reusing the examples from OSSL_PARAM(3) to just show how OSSL_PARAM(3)
323 arrays can be handled using the macros and functions defined herein.
324 Example 1
326 This example is for setting parameters on some object:
327 #include <openssl/core.h>
329 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 Example 2
340 This example is for requesting parameters on some object, and also
341 demonstrates that the requester isn't obligated to request all
342 available parameters:
343 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 A responder that receives this array (as "params" in this example)
353 could fill in the parameters like this:
354 /* OSSL_PARAM *params */
356 OSSL_PARAM *p;
358 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
367 openssl-core.h(7), OSSL_PARAM(3)
368
370 These APIs were introduced in OpenSSL 3.0.
371
373 Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved.
374 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>.
3793.0.9 2023-07-27 OSSL_PARAM_INT(3ossl)