1 =pod 2 3 =head1 NAME 4 5 OSSL_PARAM_double, OSSL_PARAM_int, OSSL_PARAM_int32, OSSL_PARAM_int64, 6 OSSL_PARAM_long, OSSL_PARAM_size_t, OSSL_PARAM_time_t, OSSL_PARAM_uint, 7 OSSL_PARAM_uint32, OSSL_PARAM_uint64, OSSL_PARAM_ulong, OSSL_PARAM_BN, 8 OSSL_PARAM_utf8_string, OSSL_PARAM_octet_string, OSSL_PARAM_utf8_ptr, 9 OSSL_PARAM_octet_ptr, 10 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, 20 OSSL_PARAM_locate, OSSL_PARAM_locate_const, 21 OSSL_PARAM_get_double, OSSL_PARAM_get_int, OSSL_PARAM_get_int32, 22 OSSL_PARAM_get_int64, OSSL_PARAM_get_long, OSSL_PARAM_get_size_t, 23 OSSL_PARAM_get_time_t, OSSL_PARAM_get_uint, OSSL_PARAM_get_uint32, 24 OSSL_PARAM_get_uint64, OSSL_PARAM_get_ulong, OSSL_PARAM_get_BN, 25 OSSL_PARAM_get_utf8_string, OSSL_PARAM_get_octet_string, 26 OSSL_PARAM_get_utf8_ptr, OSSL_PARAM_get_octet_ptr, 27 OSSL_PARAM_get_utf8_string_ptr, OSSL_PARAM_get_octet_string_ptr, 28 OSSL_PARAM_set_double, OSSL_PARAM_set_int, OSSL_PARAM_set_int32, 29 OSSL_PARAM_set_int64, OSSL_PARAM_set_long, OSSL_PARAM_set_size_t, 30 OSSL_PARAM_set_time_t, OSSL_PARAM_set_uint, OSSL_PARAM_set_uint32, 31 OSSL_PARAM_set_uint64, OSSL_PARAM_set_ulong, OSSL_PARAM_set_BN, 32 OSSL_PARAM_set_utf8_string, OSSL_PARAM_set_octet_string, 33 OSSL_PARAM_set_utf8_ptr, OSSL_PARAM_set_octet_ptr, 34 OSSL_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 112 A collection of utility functions that simplify and add type safety to the 113 L<OSSL_PARAM(3)> arrays. The following B<I<TYPE>> names are supported: 114 115 =over 2 116 117 =item * 118 119 double 120 121 =item * 122 123 int 124 125 =item * 126 127 int32 (int32_t) 128 129 =item * 130 131 int64 (int64_t) 132 133 =item * 134 135 long int (long) 136 137 =item * 138 139 time_t 140 141 =item * 142 143 size_t 144 145 =item * 146 147 uint32 (uint32_t) 148 149 =item * 150 151 uint64 (uint64_t) 152 153 =item * 154 155 unsigned int (uint) 156 157 =item * 158 159 unsigned long int (ulong) 160 161 =back 162 163 OSSL_PARAM_TYPE() are a series of macros designed to assist initialising an 164 array of L<OSSL_PARAM(3)> structures. 165 Each of these macros defines a parameter of the specified B<I<TYPE>> with the 166 provided I<key> and parameter variable I<address>. 167 168 OSSL_PARAM_utf8_string(), OSSL_PARAM_octet_string(), OSSL_PARAM_utf8_ptr(), 169 OSSL_PARAM_octet_ptr(), OSSL_PARAM_BN() are macros that provide support 170 for defining UTF8 strings, OCTET strings and big numbers. 171 A parameter with name I<key> is defined. 172 The storage for this parameter is at I<address> and is of I<size> bytes. 173 174 OSSL_PARAM_END provides an end of parameter list marker. 175 This should terminate all L<OSSL_PARAM(3)> arrays. 176 177 The OSSL_PARAM_DEFN() macro provides the ability to construct a single 178 L<OSSL_PARAM(3)> (typically used in the construction of B<OSSL_PARAM> arrays). The 179 I<key>, I<type>, I<addr> and I<sz> arguments correspond to the I<key>, 180 I<data_type>, I<data> and I<data_size> fields of the L<OSSL_PARAM(3)> structure as 181 described on the L<OSSL_PARAM(3)> page. 182 183 OSSL_PARAM_construct_TYPE() are a series of functions that create L<OSSL_PARAM(3)> 184 records dynamically. 185 A parameter with name I<key> is created. 186 The parameter will use storage pointed to by I<buf> and return size of I<ret>. 187 188 OSSL_PARAM_construct_BN() is a function that constructs a large integer 189 L<OSSL_PARAM(3)> structure. 190 A parameter with name I<key>, storage I<buf>, size I<bsize> and return 191 size I<rsize> is created. 192 193 OSSL_PARAM_construct_utf8_string() is a function that constructs a UTF8 194 string L<OSSL_PARAM(3)> structure. 195 A parameter with name I<key>, storage I<buf> and size I<bsize> is created. 196 If I<bsize> is zero, the string length is determined using strlen(3). 197 Generally pass zero for I<bsize> instead of calling strlen(3) yourself. 198 199 OSSL_PARAM_construct_octet_string() is a function that constructs an OCTET 200 string L<OSSL_PARAM(3)> structure. 201 A parameter with name I<key>, storage I<buf> and size I<bsize> is created. 202 203 OSSL_PARAM_construct_utf8_ptr() is a function that constructs a UTF8 string 204 pointer L<OSSL_PARAM(3)> structure. 205 A parameter with name I<key>, storage pointer I<*buf> and size I<bsize> 206 is created. 207 208 OSSL_PARAM_construct_octet_ptr() is a function that constructs an OCTET string 209 pointer L<OSSL_PARAM(3)> structure. 210 A parameter with name I<key>, storage pointer I<*buf> and size I<bsize> 211 is created. 212 213 OSSL_PARAM_construct_end() is a function that constructs the terminating 214 L<OSSL_PARAM(3)> structure. 215 216 OSSL_PARAM_locate() is a function that searches an I<array> of parameters for 217 the one matching the I<key> name. 218 219 OSSL_PARAM_locate_const() behaves exactly like OSSL_PARAM_locate() except for 220 the presence of I<const> for the I<array> argument and its return value. 221 222 OSSL_PARAM_get_TYPE() retrieves a value of type B<I<TYPE>> from the parameter 223 I<p>. 224 The value is copied to the address I<val>. 225 Type coercion takes place as discussed in the NOTES section. 226 227 OSSL_PARAM_set_TYPE() stores a value I<val> of type B<I<TYPE>> into the 228 parameter I<p>. 229 If the parameter's I<data> field is NULL, then only its I<return_size> field 230 will be assigned the size the parameter's I<data> buffer should have. 231 Type coercion takes place as discussed in the NOTES section. 232 233 OSSL_PARAM_get_BN() retrieves a BIGNUM from the parameter pointed to by I<p>. 234 The BIGNUM referenced by I<val> is updated and is allocated if I<*val> is 235 NULL. 236 237 OSSL_PARAM_set_BN() stores the BIGNUM I<val> into the parameter I<p>. 238 If the parameter's I<data> field is NULL, then only its I<return_size> field 239 will be assigned the size the parameter's I<data> buffer should have. 240 241 OSSL_PARAM_get_utf8_string() retrieves a UTF8 string from the parameter 242 pointed to by I<p>. 243 The string is stored into I<*val> with a size limit of I<max_len>, 244 which must be large enough to accommodate a terminating NUL byte, 245 otherwise this function will fail. 246 If I<*val> is NULL, memory is allocated for the string (including the 247 terminating NUL byte) and I<max_len> is ignored. 248 If memory is allocated by this function, it must be freed by the caller. 249 250 OSSL_PARAM_set_utf8_string() sets a UTF8 string from the parameter pointed to 251 by I<p> to the value referenced by I<val>. 252 If the parameter's I<data> field isn't NULL, its I<data_size> must indicate 253 that the buffer is large enough to accommodate the string that I<val> points at, 254 not including the terminating NUL byte, or this function will fail. 255 A terminating NUL byte is added only if the parameter's I<data_size> indicates 256 the buffer is longer than the string length, otherwise the string will not be 257 NUL terminated. 258 If the parameter's I<data> field is NULL, then only its I<return_size> field 259 will be assigned the minimum size the parameter's I<data> buffer should have 260 to accommodate the string, not including a terminating NUL byte. 261 262 OSSL_PARAM_get_octet_string() retrieves an OCTET string from the parameter 263 pointed to by I<p>. 264 The OCTETs are either stored into I<*val> with a length limit of I<max_len> or, 265 in the case when I<*val> is NULL, memory is allocated and 266 I<max_len> is ignored. I<*used_len> is populated with the number of OCTETs 267 stored. If I<val> is NULL then the OCTETS are not stored, but I<*used_len> is 268 still populated. 269 If memory is allocated by this function, it must be freed by the caller. 270 271 OSSL_PARAM_set_octet_string() sets an OCTET string from the parameter 272 pointed to by I<p> to the value referenced by I<val>. 273 If the parameter's I<data> field is NULL, then only its I<return_size> field 274 will be assigned the size the parameter's I<data> buffer should have. 275 276 OSSL_PARAM_get_utf8_ptr() retrieves the UTF8 string pointer from the parameter 277 referenced by I<p> and stores it in I<*val>. 278 279 OSSL_PARAM_set_utf8_ptr() sets the UTF8 string pointer in the parameter 280 referenced by I<p> to the values I<val>. 281 282 OSSL_PARAM_get_octet_ptr() retrieves the OCTET string pointer from the parameter 283 referenced by I<p> and stores it in I<*val>. 284 The length of the OCTET string is stored in I<*used_len>. 285 286 OSSL_PARAM_set_octet_ptr() sets the OCTET string pointer in the parameter 287 referenced by I<p> to the values I<val>. 288 The length of the OCTET string is provided by I<used_len>. 289 290 OSSL_PARAM_get_utf8_string_ptr() retrieves the pointer to a UTF8 string from 291 the parameter pointed to by I<p>, and stores that pointer in I<*val>. 292 This is different from OSSL_PARAM_get_utf8_string(), which copies the 293 string. 294 295 OSSL_PARAM_get_octet_string_ptr() retrieves the pointer to a octet string 296 from the parameter pointed to by I<p>, and stores that pointer in I<*val>, 297 along with the string's length in I<*used_len>. 298 This is different from OSSL_PARAM_get_octet_string(), which copies the 299 string. 300 301 The OSSL_PARAM_UNMODIFIED macro is used to detect if a parameter was set. On 302 creation, via either the macros or construct calls, the I<return_size> field 303 is set to this. If the parameter is set using the calls defined herein, the 304 I<return_size> field is changed. 305 306 OSSL_PARAM_modified() queries if the parameter I<param> has been set or not 307 using the calls defined herein. 308 309 OSSL_PARAM_set_all_unmodified() resets the unused indicator for all parameters 310 in the array I<params>. 311 312 =head1 RETURN VALUES 313 314 OSSL_PARAM_construct_TYPE(), OSSL_PARAM_construct_BN(), 315 OSSL_PARAM_construct_utf8_string(), OSSL_PARAM_construct_octet_string(), 316 OSSL_PARAM_construct_utf8_ptr() and OSSL_PARAM_construct_octet_ptr() 317 return a populated L<OSSL_PARAM(3)> structure. 318 319 OSSL_PARAM_locate() and OSSL_PARAM_locate_const() return a pointer to 320 the matching L<OSSL_PARAM(3)> object. They return NULL on error or when 321 no object matching I<key> exists in the I<array>. 322 323 OSSL_PARAM_modified() returns 1 if the parameter was set and 0 otherwise. 324 325 All other functions return 1 on success and 0 on failure. 326 327 =head1 NOTES 328 329 Native types will be converted as required only if the value is exactly 330 representable by the target type or parameter. 331 Apart from that, the functions must be used appropriately for the 332 expected type of the parameter. 333 334 OSSL_PARAM_get_BN() and OSSL_PARAM_set_BN() only support nonnegative 335 B<BIGNUM>s when the desired data type is B<OSSL_PARAM_UNSIGNED_INTEGER>. 336 OSSL_PARAM_construct_BN() currently constructs an L<OSSL_PARAM(3)> structure 337 with the data type B<OSSL_PARAM_UNSIGNED_INTEGER>. 338 339 For OSSL_PARAM_construct_utf8_ptr() and OSSL_PARAM_consstruct_octet_ptr(), 340 I<bsize> is not relevant if the purpose is to send the L<OSSL_PARAM(3)> array 341 to a I<responder>, i.e. to get parameter data back. 342 In that case, I<bsize> can safely be given zero. 343 See L<OSSL_PARAM(3)/DESCRIPTION> for further information on the 344 possible purposes. 345 346 =head1 EXAMPLES 347 348 Reusing the examples from L<OSSL_PARAM(3)> to just show how 349 L<OSSL_PARAM(3)> arrays can be handled using the macros and functions 350 defined herein. 351 352 =head2 Example 1 353 354 This 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 369 This example is for requesting parameters on some object, and also 370 demonstrates that the requester isn't obligated to request all 371 available 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 381 A I<responder> that receives this array (as C<params> in this example) 382 could 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 =head2 Example 3 396 397 This example shows a special case where 398 I<-Wincompatible-pointer-types-discards-qualifiers> may be set during 399 compilation. The value for I<buf> cannot be a I<const char *> type string. An 400 alternative in this case would be to use B<OSSL_PARAM> macro abbreviated calls 401 rather than the specific callers which allows you to define the sha1 argument 402 as a standard character array (I<char[]>). 403 404 For example, this code: 405 406 OSSL_PARAM params[2]; 407 params[0] = OSSL_PARAM_construct_utf8_string("digest", "SHA1", 0); 408 params[1] = OSSL_PARAM_construct_end(); 409 410 Can be made compatible with the following version: 411 412 char sha1[] = "SHA1"; /* sha1 is defined as char[] in this case */ 413 OSSL_PARAM params[2]; 414 415 params[0] = OSSL_PARAM_construct_utf8_string("digest", sha1, 0); 416 params[1] = OSSL_PARAM_construct_end(); 417 418 =head1 SEE ALSO 419 420 L<openssl-core.h(7)>, L<OSSL_PARAM(3)> 421 422 =head1 HISTORY 423 424 These APIs were introduced in OpenSSL 3.0. 425 426 =head1 COPYRIGHT 427 428 Copyright 2019-2025 The OpenSSL Project Authors. All Rights Reserved. 429 430 Licensed under the Apache License 2.0 (the "License"). You may not use 431 this file except in compliance with the License. You can obtain a copy 432 in the file LICENSE in the source distribution or at 433 L<https://www.openssl.org/source/license.html>. 434 435 =cut 436
Indexes created Sat Jun 27 00:24:51 UTC 2026