doc/man3/OSSL_PARAM_int.pod

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