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() currently only support 335nonnegative B<BIGNUM>s, and by consequence, only 336B<OSSL_PARAM_UNSIGNED_INTEGER>. OSSL_PARAM_construct_BN() currently 337constructs an L<OSSL_PARAM(3)> structure with the data type 338B<OSSL_PARAM_UNSIGNED_INTEGER>. 339 340For OSSL_PARAM_construct_utf8_ptr() and OSSL_PARAM_consstruct_octet_ptr(), 341I<bsize> is not relevant if the purpose is to send the L<OSSL_PARAM(3)> array 342to a I<responder>, i.e. to get parameter data back. 343In that case, I<bsize> can safely be given zero. 344See L<OSSL_PARAM(3)/DESCRIPTION> for further information on the 345possible purposes. 346 347=head1 EXAMPLES 348 349Reusing the examples from L<OSSL_PARAM(3)> to just show how 350L<OSSL_PARAM(3)> arrays can be handled using the macros and functions 351defined herein. 352 353=head2 Example 1 354 355This example is for setting parameters on some object: 356 357 #include <openssl/core.h> 358 359 const char *foo = "some string"; 360 size_t foo_l = strlen(foo); 361 const char bar[] = "some other string"; 362 const OSSL_PARAM set[] = { 363 OSSL_PARAM_utf8_ptr("foo", &foo, foo_l), 364 OSSL_PARAM_utf8_string("bar", bar, sizeof(bar) - 1), 365 OSSL_PARAM_END 366 }; 367 368=head2 Example 2 369 370This example is for requesting parameters on some object, and also 371demonstrates that the requester isn't obligated to request all 372available parameters: 373 374 const char *foo = NULL; 375 char bar[1024]; 376 OSSL_PARAM request[] = { 377 OSSL_PARAM_utf8_ptr("foo", &foo, 0), 378 OSSL_PARAM_utf8_string("bar", bar, sizeof(bar)), 379 OSSL_PARAM_END 380 }; 381 382A I<responder> that receives this array (as C<params> in this example) 383could fill in the parameters like this: 384 385 /* OSSL_PARAM *params */ 386 387 OSSL_PARAM *p; 388 389 if ((p = OSSL_PARAM_locate(params, "foo")) != NULL) 390 OSSL_PARAM_set_utf8_ptr(p, "foo value"); 391 if ((p = OSSL_PARAM_locate(params, "bar")) != NULL) 392 OSSL_PARAM_set_utf8_string(p, "bar value"); 393 if ((p = OSSL_PARAM_locate(params, "cookie")) != NULL) 394 OSSL_PARAM_set_utf8_ptr(p, "cookie value"); 395 396=head1 SEE ALSO 397 398L<openssl-core.h(7)>, L<OSSL_PARAM(3)> 399 400=head1 HISTORY 401 402These APIs were introduced in OpenSSL 3.0. 403 404=head1 COPYRIGHT 405 406Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved. 407 408Licensed under the Apache License 2.0 (the "License"). You may not use 409this file except in compliance with the License. You can obtain a copy 410in the file LICENSE in the source distribution or at 411L<https://www.openssl.org/source/license.html>. 412 413=cut 414