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() only support nonnegative 335B<BIGNUM>s when the desired data type is B<OSSL_PARAM_UNSIGNED_INTEGER>. 336OSSL_PARAM_construct_BN() currently constructs an L<OSSL_PARAM(3)> structure 337with the data type B<OSSL_PARAM_UNSIGNED_INTEGER>. 338 339For OSSL_PARAM_construct_utf8_ptr() and OSSL_PARAM_consstruct_octet_ptr(), 340I<bsize> is not relevant if the purpose is to send the L<OSSL_PARAM(3)> array 341to a I<responder>, i.e. to get parameter data back. 342In that case, I<bsize> can safely be given zero. 343See L<OSSL_PARAM(3)/DESCRIPTION> for further information on the 344possible purposes. 345 346=head1 EXAMPLES 347 348Reusing the examples from L<OSSL_PARAM(3)> to just show how 349L<OSSL_PARAM(3)> arrays can be handled using the macros and functions 350defined herein. 351 352=head2 Example 1 353 354This 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 369This example is for requesting parameters on some object, and also 370demonstrates that the requester isn't obligated to request all 371available 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 381A I<responder> that receives this array (as C<params> in this example) 382could 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=head1 SEE ALSO 396 397L<openssl-core.h(7)>, L<OSSL_PARAM(3)> 398 399=head1 HISTORY 400 401These APIs were introduced in OpenSSL 3.0. 402 403=head1 COPYRIGHT 404 405Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved. 406 407Licensed under the Apache License 2.0 (the "License"). You may not use 408this file except in compliance with the License. You can obtain a copy 409in the file LICENSE in the source distribution or at 410L<https://www.openssl.org/source/license.html>. 411 412=cut 413
