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