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_uint, OSSL_PARAM_uint32,
   7 OSSL_PARAM_uint64, OSSL_PARAM_ulong, OSSL_PARAM_BN, OSSL_PARAM_utf8_string,
   8 OSSL_PARAM_octet_string, OSSL_PARAM_utf8_ptr, OSSL_PARAM_octet_ptr,
   9 OSSL_PARAM_END, OSSL_PARAM_construct_BN, OSSL_PARAM_construct_double,
  10 OSSL_PARAM_construct_int, OSSL_PARAM_construct_int32,
  11 OSSL_PARAM_construct_int64, OSSL_PARAM_construct_long,
  12 OSSL_PARAM_construct_size_t, OSSL_PARAM_construct_uint,
  13 OSSL_PARAM_construct_uint32, OSSL_PARAM_construct_uint64,
  14 OSSL_PARAM_construct_ulong, OSSL_PARAM_END, OSSL_PARAM_construct_BN,
  15 OSSL_PARAM_construct_utf8_string, OSSL_PARAM_construct_utf8_ptr,
  16 OSSL_PARAM_construct_octet_string, OSSL_PARAM_construct_octet_ptr,
  17 OSSL_PARAM_construct_end, OSSL_PARAM_locate, OSSL_PARAM_locate_const,
  18 OSSL_PARAM_get_double, OSSL_PARAM_get_int, OSSL_PARAM_get_int32,
  19 OSSL_PARAM_get_int64, OSSL_PARAM_get_long, OSSL_PARAM_get_size_t,
  20 OSSL_PARAM_get_uint, OSSL_PARAM_get_uint32, OSSL_PARAM_get_uint64,
  21 OSSL_PARAM_get_ulong, OSSL_PARAM_set_double, OSSL_PARAM_set_int,
  22 OSSL_PARAM_set_int32, OSSL_PARAM_set_int64, OSSL_PARAM_set_long,
  23 OSSL_PARAM_set_size_t, OSSL_PARAM_set_uint, OSSL_PARAM_set_uint32,
  24 OSSL_PARAM_set_uint64, OSSL_PARAM_set_ulong, OSSL_PARAM_get_BN,
  25 OSSL_PARAM_set_BN, OSSL_PARAM_get_utf8_string, OSSL_PARAM_set_utf8_string,
  26 OSSL_PARAM_get_octet_string, OSSL_PARAM_set_octet_string,
  27 OSSL_PARAM_get_utf8_ptr, OSSL_PARAM_set_utf8_ptr, OSSL_PARAM_get_octet_ptr,
  28 OSSL_PARAM_set_octet_ptr
  29 - OSSL_PARAM helpers
  30
  31 =head1 SYNOPSIS
  32
  33 =for comment generic
  34
  35  #include <openssl/params.h>
  36
  37  #define OSSL_PARAM_TYPE(key, address)
  38  #define OSSL_PARAM_utf8_string(key, address, size)
  39  #define OSSL_PARAM_octet_string(key, address, size)
  40  #define OSSL_PARAM_utf8_ptr(key, address, size)
  41  #define OSSL_PARAM_octet_ptr(key, address, size)
  42  #define OSSL_PARAM_BN(key, address, size)
  43  #define OSSL_PARAM_END
  44
  45  OSSL_PARAM OSSL_PARAM_construct_TYPE(const char *key, TYPE *buf, size_t *ret);
  46  OSSL_PARAM OSSL_PARAM_construct_BN(const char *key, unsigned char *buf,
  47                                     size_t bsize);
  48  OSSL_PARAM OSSL_PARAM_construct_utf8_string(const char *key, char *buf,
  49                                              size_t bsize);
  50  OSSL_PARAM OSSL_PARAM_construct_octet_string(const char *key, void *buf,
  51                                               size_t bsize);
  52  OSSL_PARAM OSSL_PARAM_construct_utf8_ptr(const char *key, char **buf,
  53                                           size_t bsize);
  54  OSSL_PARAM OSSL_PARAM_construct_octet_ptr(const char *key, void **buf,
  55                                            size_t bsize);
  56  OSSL_PARAM OSSL_PARAM_construct_end(void);
  57
  58  OSSL_PARAM *OSSL_PARAM_locate(OSSL_PARAM *array, const char *key);
  59  const OSSL_PARAM *OSSL_PARAM_locate_const(const OSSL_PARAM *array,
  60                                            const char *key);
  61
  62  int OSSL_PARAM_get_TYPE(const OSSL_PARAM *p, const char *key, TYPE *val);
  63  int OSSL_PARAM_set_TYPE(OSSL_PARAM *p, const char *key, TYPE val);
  64
  65  int OSSL_PARAM_get_BN(const OSSL_PARAM *p, const char *key, BIGNUM **val);
  66  int OSSL_PARAM_set_BN(OSSL_PARAM *p, const char *key, const BIGNUM *val);
  67
  68  int OSSL_PARAM_get_utf8_string(const OSSL_PARAM *p, char **val,
  69                                 size_t max_len);
  70  int OSSL_PARAM_set_utf8_string(OSSL_PARAM *p, const char *val);
  71
  72  int OSSL_PARAM_get_octet_string(const OSSL_PARAM *p, void **val,
  73                                  size_t max_len, size_t *used_len);
  74  int OSSL_PARAM_set_octet_string(OSSL_PARAM *p, const void *val, size_t len);
  75
  76  int OSSL_PARAM_get_utf8_ptr(const OSSL_PARAM *p, char **val);
  77  int OSSL_PARAM_set_utf8_ptr(OSSL_PARAM *p, char *val);
  78
  79  int OSSL_PARAM_get_octet_ptr(const OSSL_PARAM *p, void **val,
  80                               size_t *used_len);
  81  int OSSL_PARAM_set_octet_ptr(OSSL_PARAM *p, void *val, size_t used_len);
  82
  83 =head1 DESCRIPTION
  84
  85 A collection of utility functions that simplify and add type safety to the
  86 OSSL_PARAM arrays.  The following B<TYPE> names are supported:
  87
  88 =over 1
  89
  90 =item *
  91
  92 double
  93
  94 =item *
  95
  96 int
  97
  98 =item *
  99
 100 int32 (int32_t)
 101
 102 =item *
 103
 104 int64 (int64_t)
 105
 106 =item *
 107
 108 long int (long)
 109
 110 =item *
 111
 112 size_t
 113
 114 =item *
 115
 116 uint32 (uint32_t)
 117
 118 =item *
 119
 120 uint64 (uint64_t)
 121
 122 =item *
 123
 124 unsigned int (uint)
 125
 126 =item *
 127
 128 unsigned long int (ulong)
 129
 130 =back
 131
 132 OSSL_PARAM_TYPE() are a series of macros designed to assist initialising an
 133 array of OSSL_PARAM structures.
 134 Each of these macros defines a parameter of the specified B<TYPE> with the
 135 provided B<key> and parameter variable B<address>.
 136
 137 OSSL_PARAM_utf8_string(), OSSL_PARAM_octet_string(), OSSL_PARAM_utf8_ptr(),
 138 OSSL_PARAM_octet_ptr(), OSSL_PARAM_BN() are macros that provide support
 139 for defining UTF8 strings, OCTET strings and big numbers.
 140 A parameter with name B<key> is defined.
 141 The storage for this parameter is at B<address> and is of B<size> bytes.
 142
 143 OSSL_PARAM_END provides an end of parameter list marker.
 144 This should terminate all OSSL_PARAM arrays.
 145
 146 OSSL_PARAM_construct_TYPE() are a series of functions that create OSSL_PARAM
 147 records dynamically.
 148 A parameter with name B<key> is created.
 149 The parameter will use storage pointed to by B<buf> and return size of B<ret>.
 150
 151 OSSL_PARAM_construct_BN() is a function that constructs a large integer
 152 OSSL_PARAM structure.
 153 A parameter with name B<key>, storage B<buf>, size B<bsize> and return
 154 size B<rsize> is created.
 155
 156 OSSL_PARAM_construct_utf8_string() is a function that constructs a UTF8
 157 string OSSL_PARAM structure.
 158 A parameter with name B<key>, storage B<buf>, size B<bsize> and return
 159 size B<rsize> is created.
 160
 161 OSSL_PARAM_construct_octet_string() is a function that constructs an OCTET
 162 string OSSL_PARAM structure.
 163 A parameter with name B<key>, storage B<buf>, size B<bsize> and return
 164 size B<rsize> is created.
 165
 166 OSSL_PARAM_construct_utf8_ptr() is a function that constructes a UTF string
 167 pointer OSSL_PARAM structure.
 168 A parameter with name B<key>, storage pointer B<*buf>, size B<bsize> and
 169 return size B<rsize> is created.
 170
 171 OSSL_PARAM_construct_octet_ptr() is a function that constructes an OCTET string
 172 pointer OSSL_PARAM structure.
 173 A parameter with name B<key>, storage pointer B<*buf>, size B<bsize> and
 174 return size B<rsize> is created.
 175
 176 OSSL_PARAM_construct_end() is a function that constructs the terminating
 177 OSSL_PARAM structure.
 178
 179 OSSL_PARAM_locate() is a function that searches an B<array> of parameters for
 180 the one matching the B<key> name.
 181
 182 OSSL_PARAM_locate_const() behaves exactly like OSSL_PARAM_locate() except for
 183 the presence of I<const> for the B<array> argument and its return value.
 184
 185 OSSL_PARAM_get_TYPE() retrieves a value of type B<TYPE> from the parameter B<p>.
 186 The value is copied to the address B<val>.
 187 Type coercion takes place as discussed in the NOTES section.
 188
 189 OSSL_PARAM_set_TYPE() stores a value B<val> of type B<TYPE> into the paramter
 190 B<p>.
 191 Type coercion takes place as discussed in the NOTES section.
 192
 193 OSSL_PARAM_get_BN() retrieves a BIGNUM from the parameter pointed to by B<p>.
 194 The BIGNUM referenced by B<val> is updated and is allocated if B<*val> is
 195 B<NULL>.
 196
 197 OSSL_PARAM_set_BN() stores the BIGNUM B<val> into the paramater B<p>.
 198
 199 OSSL_PARAM_get_utf8_string() retrieves a UTF8 string from the parameter
 200 pointed to by B<p>.
 201 The string is either stored into B<*val> with a length limit of B<max_len> or,
 202 in the case when B<*val> is B<NULL>, memory is allocated for the string and
 203 B<max_len> is ignored.
 204 If memory is allocated by this function, it must be freed by the caller.
 205
 206 OSSL_PARAM_set_utf8_string() sets a UTF8 string from the parameter pointed to
 207 by B<p> to the value referenced by B<val>.
 208
 209 OSSL_PARAM_get_octet_string() retrieves an OCTET string from the parameter
 210 pointed to by B<p>.
 211 The OCTETs are either stored into B<*val> with a length limit of B<max_len> or,
 212 in the case when B<*val> is B<NULL>, memory is allocated and
 213 B<max_len> is ignored.
 214 If memory is allocated by this function, it must be freed by the caller.
 215
 216 OSSL_PARAM_set_octet_string() sets an OCTET string from the parameter
 217 pointed to by B<p> to the value referenced by B<val>.
 218
 219 OSSL_PARAM_get_utf8_ptr() retrieves the UTF8 string pointer from the parameter
 220 referenced by B<p> and stores it in B<*val>.
 221
 222 OSSL_PARAM_set_utf8_ptr() sets the UTF8 string pointer in the parameter
 223 referenced by B<p> to the values B<val>.
 224
 225 OSSL_PARAM_get_octet_ptr() retrieves the OCTET string pointer from the parameter
 226 referenced by B<p> and stores it in B<*val>.
 227 The length of the OCTET string is stored in B<*used_len>.
 228
 229 OSSL_PARAM_set_octet_ptr() sets the OCTET string pointer in the parameter
 230 referenced by B<p> to the values B<val>.
 231 The length of the OCTET string is provided by B<used_len>.
 232
 233 =head1 RETURN VALUES
 234
 235 OSSL_PARAM_construct_TYPE(), OSSL_PARAM_construct_BN(),
 236 OSSL_PARAM_construct_utf8_string(), OSSL_PARAM_construct_octet_string(),
 237 OSSL_PARAM_construct_utf8_ptr() and OSSL_PARAM_construct_octet_ptr()
 238 return a populated OSSL_PARAM structure.
 239
 240 OSSL_PARAM_locate() and OSSL_PARAM_locate_const() return a pointer to
 241 the matching OSSL_PARAM object.  They return B<NULL> on error or when
 242 no object matching B<key> exists in the B<array>.
 243
 244 All other functions return B<1> on success and B<0> on failure.
 245
 246 =head1 NOTES
 247
 248 Native types will be converted as required only if the value is exactly
 249 representable by the target type or parameter.
 250 Apart from that, the functions must be used appropriately for the
 251 expected type of the parameter.
 252
 253 For OSSL_PARAM_get_utf8_ptr() and OSSL_PARAM_get_octet_ptr(), B<bsize>
 254 is not relevant if the purpose is to send the B<OSSL_PARAM> array to a
 255 I<responder>, i.e. to get parameter data back.
 256 In that case, B<bsize> can safely be given zero.
 257 See L<OSSL_PARAM(3)/DESCRIPTION> for further information on the
 258 possible purposes.
 259
 260 =head1 EXAMPLES
 261
 262 Reusing the examples from L<OSSL_PARAM(3)> to just show how
 263 C<OSSL_PARAM> arrays can be handled using the macros and functions
 264 defined herein.
 265
 266 =head2 Example 1
 267
 268 This example is for setting parameters on some object:
 269
 270     #include <openssl/core.h>
 271
 272     const char *foo = "some string";
 273     size_t foo_l = strlen(foo) + 1;
 274     const char bar[] = "some other string";
 275     const OSSL_PARAM set[] = {
 276         OSSL_PARAM_utf8_ptr("foo", foo, foo_l),
 277         OSSL_PARAM_utf8_string("bar", bar, sizeof(bar)),
 278         OSSL_PARAM_END
 279     };
 280
 281 =head2 Example 2
 282
 283 This example is for requesting parameters on some object, and also
 284 demonstrates that the requestor isn't obligated to request all
 285 available parameters:
 286
 287     const char *foo = NULL;
 288     char bar[1024];
 289     OSSL_PARAM request[] = {
 290         OSSL_PARAM_utf8_ptr("foo", foo, 0),
 291         OSSL_PARAM_utf8_string("bar", bar, sizeof(bar)),
 292         OSSL_PARAM_END
 293     };
 294
 295 A I<responder> that receives this array (as C<params> in this example)
 296 could fill in the parameters like this:
 297
 298     /* OSSL_PARAM *params */
 299
 300     OSSL_PARAM *p;
 301
 302     if ((p = OSSL_PARAM_locate(params, "foo")) == NULL)
 303         OSSL_PARAM_set_utf8_ptr(p, "foo value");
 304     if ((p = OSSL_PARAM_locate(params, "bar")) == NULL)
 305         OSSL_PARAM_set_utf8_ptr(p, "bar value");
 306     if ((p = OSSL_PARAM_locate(params, "cookie")) == NULL)
 307         OSSL_PARAM_set_utf8_ptr(p, "cookie value");
 308
 309 =head1 SEE ALSO
 310
 311 L<openssl-core.h(7)>, L<OSSL_PARAM(3)>
 312
 313 =head1 HISTORY
 314
 315 These APIs were introduced in OpenSSL 3.0.0.
 316
 317 =head1 COPYRIGHT
 318
 319 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
 320
 321 Licensed under the Apache License 2.0 (the "License").  You may not use
 322 this file except in compliance with the License.  You can obtain a copy
 323 in the file LICENSE in the source distribution or at
 324 L<https://www.openssl.org/source/license.html>.
 325
 326 =cut