1=pod 2 3=head1 NAME 4 5OSSL_PARAM - a structure to pass or request object parameters 6 7=head1 SYNOPSIS 8 9 #include <openssl/core.h> 10 11 typedef struct ossl_param_st OSSL_PARAM; 12 struct ossl_param_st { 13 const char *key; /* the name of the parameter */ 14 unsigned int data_type; /* declare what kind of content is in data */ 15 void *data; /* value being passed in or out */ 16 size_t data_size; /* data size */ 17 size_t return_size; /* returned size */ 18 }; 19 20=head1 DESCRIPTION 21 22B<OSSL_PARAM> is a type that allows passing arbitrary data for some 23object between two parties that have no or very little shared 24knowledge about their respective internal structures for that object. 25 26A typical usage example could be an application that wants to set some 27parameters for an object, or wants to find out some parameters of an 28object. 29 30Arrays of this type can be used for the following purposes: 31 32=over 4 33 34=item * Setting parameters for some object 35 36The caller sets up the B<OSSL_PARAM> array and calls some function 37(the I<setter>) that has intimate knowledge about the object that can 38take the data from the B<OSSL_PARAM> array and assign them in a 39suitable form for the internal structure of the object. 40 41=item * Request parameters of some object 42 43The caller (the I<requester>) sets up the B<OSSL_PARAM> array and 44calls some function (the I<responder>) that has intimate knowledge 45about the object, which can take the internal data of the object and 46copy (possibly convert) that to the memory prepared by the 47I<requester> and pointed at with the B<OSSL_PARAM> I<data>. 48 49=item * Request parameter descriptors 50 51The caller gets an array of constant B<OSSL_PARAM>, which describe 52available parameters and some of their properties; name, data type and 53expected data size. 54For a detailed description of each field for this use, see the field 55descriptions below. 56 57The caller may then use the information from this descriptor array to 58build up its own B<OSSL_PARAM> array to pass down to a I<setter> or 59I<responder>. 60 61=back 62 63Normally, the order of the an B<OSSL_PARAM> array is not relevant. 64However, if the I<responder> can handle multiple elements with the 65same key, those elements must be handled in the order they are in. 66 67An B<OSSL_PARAM> array must have a terminating element, where I<key> 68is NULL. The usual full terminating template is: 69 70 { NULL, 0, NULL, 0, 0 } 71 72This can also be specified using L<OSSL_PARAM_END(3)>. 73 74=head2 Functional support 75 76Libcrypto offers a limited set of helper functions to handle 77B<OSSL_PARAM> items and arrays, please see L<OSSL_PARAM_get_int(3)>. 78Developers are free to extend or replace those as they see fit. 79 80=head2 B<OSSL_PARAM> fields 81 82=over 4 83 84=item I<key> 85 86The identity of the parameter in the form of a string. 87 88In an B<OSSL_PARAM> array, an item with this field set to NULL is 89considered a terminating item. 90 91=item I<data_type> 92 93The I<data_type> is a value that describes the type and organization of 94the data. 95See L</Supported types> below for a description of the types. 96 97=item I<data> 98 99=item I<data_size> 100 101I<data> is a pointer to the memory where the parameter data is (when 102setting parameters) or shall (when requesting parameters) be stored, 103and I<data_size> is its size in bytes. 104The organization of the data depends on the parameter type and flag. 105 106The I<data_size> needs special attention with the parameter type 107B<OSSL_PARAM_UTF8_STRING> in relation to C strings. When setting 108parameters, the size should be set to the length of the string, not 109counting the terminating NUL byte. When requesting parameters, the 110size should be set to the size of the buffer to be populated, which 111should accommodate enough space for a terminating NUL byte. 112 113When I<requesting parameters>, it's acceptable for I<data> to be NULL. 114This can be used by the I<requester> to figure out dynamically exactly 115how much buffer space is needed to store the parameter data. 116In this case, I<data_size> is ignored. 117 118When the B<OSSL_PARAM> is used as a parameter descriptor, I<data> 119should be ignored. 120If I<data_size> is zero, it means that an arbitrary data size is 121accepted, otherwise it specifies the maximum size allowed. 122 123=item I<return_size> 124 125When an array of B<OSSL_PARAM> is used to request data, the 126I<responder> must set this field to indicate size of the parameter 127data, including padding as the case may be. 128In case the I<data_size> is an unsuitable size for the data, the 129I<responder> must still set this field to indicate the minimum data 130size required. 131(further notes on this in L</NOTES> below). 132 133When the B<OSSL_PARAM> is used as a parameter descriptor, 134I<return_size> should be ignored. 135 136=back 137 138B<NOTE:> 139 140The key names and associated types are defined by the entity that 141offers these parameters, i.e. names for parameters provided by the 142OpenSSL libraries are defined by the libraries, and names for 143parameters provided by providers are defined by those providers, 144except for the pointer form of strings (see data type descriptions 145below). 146Entities that want to set or request parameters need to know what 147those keys are and of what type, any functionality between those two 148entities should remain oblivious and just pass the B<OSSL_PARAM> array 149along. 150 151=head2 Supported types 152 153The I<data_type> field can be one of the following types: 154 155=over 4 156 157=item B<OSSL_PARAM_INTEGER> 158 159=item B<OSSL_PARAM_UNSIGNED_INTEGER> 160 161The parameter data is an integer (signed or unsigned) of arbitrary 162length, organized in native form, i.e. most significant byte first on 163Big-Endian systems, and least significant byte first on Little-Endian 164systems. 165 166=item B<OSSL_PARAM_REAL> 167 168The parameter data is a floating point value in native form. 169 170=item B<OSSL_PARAM_UTF8_STRING> 171 172The parameter data is a printable string. 173 174=item B<OSSL_PARAM_OCTET_STRING> 175 176The parameter data is an arbitrary string of bytes. 177 178=item B<OSSL_PARAM_UTF8_PTR> 179 180The parameter data is a pointer to a printable string. 181 182The difference between this and B<OSSL_PARAM_UTF8_STRING> is that I<data> 183doesn't point directly at the data, but to a pointer that points to the data. 184 185If there is any uncertainty about which to use, B<OSSL_PARAM_UTF8_STRING> is 186almost certainly the correct choice. 187 188This is used to indicate that constant data is or will be passed, 189and there is therefore no need to copy the data that is passed, just 190the pointer to it. 191 192I<data_size> must be set to the size of the data, not the size of the 193pointer to the data. 194If this is used in a parameter request, 195I<data_size> is not relevant. However, the I<responder> will set 196I<return_size> to the size of the data. 197 198Note that the use of this type is B<fragile> and can only be safely 199used for data that remains constant and in a constant location for a 200long enough duration (such as the life-time of the entity that 201offers these parameters). 202 203=item B<OSSL_PARAM_OCTET_PTR> 204 205The parameter data is a pointer to an arbitrary string of bytes. 206 207The difference between this and B<OSSL_PARAM_OCTET_STRING> is that 208I<data> doesn't point directly at the data, but to a pointer that 209points to the data. 210 211If there is any uncertainty about which to use, B<OSSL_PARAM_OCTET_STRING> is 212almost certainly the correct choice. 213 214This is used to indicate that constant data is or will be passed, and 215there is therefore no need to copy the data that is passed, just the 216pointer to it. 217 218I<data_size> must be set to the size of the data, not the size of the 219pointer to the data. 220If this is used in a parameter request, 221I<data_size> is not relevant. However, the I<responder> will set 222I<return_size> to the size of the data. 223 224Note that the use of this type is B<fragile> and can only be safely 225used for data that remains constant and in a constant location for a 226long enough duration (such as the life-time of the entity that 227offers these parameters). 228 229=back 230 231=head1 NOTES 232 233Both when setting and requesting parameters, the functions that are 234called will have to decide what is and what is not an error. 235The recommended behaviour is: 236 237=over 4 238 239=item * 240 241Keys that a I<setter> or I<responder> doesn't recognise should simply 242be ignored. 243That in itself isn't an error. 244 245=item * 246 247If the keys that a called I<setter> recognises form a consistent 248enough set of data, that call should succeed. 249 250=item * 251 252Apart from the I<return_size>, a I<responder> must never change the fields 253of an B<OSSL_PARAM>. 254To return a value, it should change the contents of the memory that 255I<data> points at. 256 257=item * 258 259If the data type for a key that it's associated with is incorrect, 260the called function may return an error. 261 262The called function may also try to convert the data to a suitable 263form (for example, it's plausible to pass a large number as an octet 264string, so even though a given key is defined as an 265B<OSSL_PARAM_UNSIGNED_INTEGER>, is plausible to pass the value as an 266B<OSSL_PARAM_OCTET_STRING>), but this is in no way mandatory. 267 268=item * 269 270If I<data> for a B<OSSL_PARAM_OCTET_STRING> or a 271B<OSSL_PARAM_UTF8_STRING> is NULL, the I<responder> should 272set I<return_size> to the size of the item to be returned 273and return success. Later the responder will be called again 274with I<data> pointing at the place for the value to be put. 275 276=item * 277 278If a I<responder> finds that some data sizes are too small for the 279requested data, it must set I<return_size> for each such 280B<OSSL_PARAM> item to the minimum required size, and eventually return 281an error. 282 283=item * 284 285For the integer type parameters (B<OSSL_PARAM_UNSIGNED_INTEGER> and 286B<OSSL_PARAM_INTEGER>), a I<responder> may choose to return an error 287if the I<data_size> isn't a suitable size (even if I<data_size> is 288bigger than needed). If the I<responder> finds the size suitable, it 289must fill all I<data_size> bytes and ensure correct padding for the 290native endianness, and set I<return_size> to the same value as 291I<data_size>. 292 293=back 294 295=begin comment RETURN VALUES doesn't make sense for a manual that only 296describes a type, but document checkers still want that section, and 297to have more than just the section title. 298 299=head1 RETURN VALUES 300 301txt 302 303=end comment 304 305=head1 EXAMPLES 306 307A couple of examples to just show how B<OSSL_PARAM> arrays could be 308set up. 309 310=head3 Example 1 311 312This example is for setting parameters on some object: 313 314 #include <openssl/core.h> 315 316 const char *foo = "some string"; 317 size_t foo_l = strlen(foo); 318 const char bar[] = "some other string"; 319 OSSL_PARAM set[] = { 320 { "foo", OSSL_PARAM_UTF8_PTR, &foo, foo_l, 0 }, 321 { "bar", OSSL_PARAM_UTF8_STRING, (void *)&bar, sizeof(bar) - 1, 0 }, 322 { NULL, 0, NULL, 0, 0 } 323 }; 324 325=head3 Example 2 326 327This example is for requesting parameters on some object: 328 329 const char *foo = NULL; 330 size_t foo_l; 331 char bar[1024]; 332 size_t bar_l; 333 OSSL_PARAM request[] = { 334 { "foo", OSSL_PARAM_UTF8_PTR, &foo, 0 /*irrelevant*/, 0 }, 335 { "bar", OSSL_PARAM_UTF8_STRING, &bar, sizeof(bar), 0 }, 336 { NULL, 0, NULL, 0, 0 } 337 }; 338 339A I<responder> that receives this array (as I<params> in this example) 340could fill in the parameters like this: 341 342 /* OSSL_PARAM *params */ 343 344 int i; 345 346 for (i = 0; params[i].key != NULL; i++) { 347 if (strcmp(params[i].key, "foo") == 0) { 348 *(char **)params[i].data = "foo value"; 349 params[i].return_size = 9; /* length of "foo value" string */ 350 } else if (strcmp(params[i].key, "bar") == 0) { 351 memcpy(params[i].data, "bar value", 10); 352 params[i].return_size = 9; /* length of "bar value" string */ 353 } 354 /* Ignore stuff we don't know */ 355 } 356 357=head1 SEE ALSO 358 359L<openssl-core.h(7)>, L<OSSL_PARAM_get_int(3)>, L<OSSL_PARAM_dup(3)> 360 361=head1 HISTORY 362 363B<OSSL_PARAM> was added in OpenSSL 3.0. 364 365=head1 COPYRIGHT 366 367Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved. 368 369Licensed under the Apache License 2.0 (the "License"). You may not use 370this file except in compliance with the License. You can obtain a copy 371in the file LICENSE in the source distribution or at 372L<https://www.openssl.org/source/license.html>. 373 374=cut 375
