doc/man3/OSSL_PARAM_BLD.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 OSSL_PARAM_BLD, OSSL_PARAM_BLD_new, OSSL_PARAM_BLD_to_param,
   6 OSSL_PARAM_BLD_free, OSSL_PARAM_BLD_push_int,
   7 OSSL_PARAM_BLD_push_uint, OSSL_PARAM_BLD_push_long,
   8 OSSL_PARAM_BLD_push_ulong, OSSL_PARAM_BLD_push_int32,
   9 OSSL_PARAM_BLD_push_uint32, OSSL_PARAM_BLD_push_int64,
  10 OSSL_PARAM_BLD_push_uint64, OSSL_PARAM_BLD_push_size_t,
  11 OSSL_PARAM_BLD_push_time_t, OSSL_PARAM_BLD_push_double,
  12 OSSL_PARAM_BLD_push_BN, OSSL_PARAM_BLD_push_BN_pad,
  13 OSSL_PARAM_BLD_push_utf8_string, OSSL_PARAM_BLD_push_utf8_ptr,
  14 OSSL_PARAM_BLD_push_octet_string, OSSL_PARAM_BLD_push_octet_ptr
  15 - functions to assist in the creation of OSSL_PARAM arrays
  16
  17 =head1 SYNOPSIS
  18
  19 =for openssl generic
  20
  21  #include <openssl/param_build.h>
  22
  23  typedef struct OSSL_PARAM_BLD;
  24
  25  OSSL_PARAM_BLD *OSSL_PARAM_BLD_new(void);
  26  OSSL_PARAM *OSSL_PARAM_BLD_to_param(OSSL_PARAM_BLD *bld);
  27  void OSSL_PARAM_BLD_free(OSSL_PARAM_BLD *bld);
  28
  29  int OSSL_PARAM_BLD_push_TYPE(OSSL_PARAM_BLD *bld, const char *key, TYPE val);
  30
  31  int OSSL_PARAM_BLD_push_BN(OSSL_PARAM_BLD *bld, const char *key,
  32                             const BIGNUM *bn);
  33  int OSSL_PARAM_BLD_push_BN_pad(OSSL_PARAM_BLD *bld, const char *key,
  34                                 const BIGNUM *bn, size_t sz);
  35
  36  int OSSL_PARAM_BLD_push_utf8_string(OSSL_PARAM_BLD *bld, const char *key,
  37                                      const char *buf, size_t bsize);
  38  int OSSL_PARAM_BLD_push_utf8_ptr(OSSL_PARAM_BLD *bld, const char *key,
  39                                   char *buf, size_t bsize);
  40  int OSSL_PARAM_BLD_push_octet_string(OSSL_PARAM_BLD *bld, const char *key,
  41                                       const void *buf, size_t bsize);
  42  int OSSL_PARAM_BLD_push_octet_ptr(OSSL_PARAM_BLD *bld, const char *key,
  43                                    void *buf, size_t bsize);
  44
  45
  46 =head1 DESCRIPTION
  47
  48 A collection of utility functions that simplify the creation of OSSL_PARAM
  49 arrays.  The B<I<TYPE>> names are as per L<OSSL_PARAM_int(3)>.
  50
  51 OSSL_PARAM_BLD_new() allocates and initialises a new OSSL_PARAM_BLD structure
  52 so that values can be added.
  53 Any existing values are cleared.
  54
  55 OSSL_PARAM_BLD_free() deallocates the memory allocates by OSSL_PARAM_BLD_new().
  56
  57 OSSL_PARAM_BLD_to_param() converts a built up OSSL_PARAM_BLD structure
  58 I<bld> into an allocated OSSL_PARAM array.
  59 The OSSL_PARAM array and all associated storage must be freed by calling
  60 OSSL_PARAM_free() with the functions return value.
  61 OSSL_PARAM_BLD_free() can safely be called any time after this function is.
  62
  63 =begin comment
  64
  65 POD is pretty good at recognising function names and making them appropriately
  66 bold...  however, when part of the function name is variable, we have to help
  67 the processor along
  68
  69 =end comment
  70
  71 B<OSSL_PARAM_BLD_push_I<TYPE>>() are a series of functions which will create
  72 OSSL_PARAM objects of the specified size and correct type for the I<val>
  73 argument.
  74 I<val> is stored by value and an expression or auto variable can be used.
  75
  76 When B<I<TYPE>> denotes an integer type, signed integer types will normally
  77 get the OSSL_PARAM type B<OSSL_PARAM_INTEGER> params.
  78 When B<I<TYPE>> denotes an unsigned integer type will get the OSSL_PARAM type
  79 B<OSSL_PARAM_UNSIGNED_INTEGER>.
  80
  81 OSSL_PARAM_BLD_push_BN() is a function that will create an OSSL_PARAM object
  82 that holds the specified BIGNUM I<bn>.
  83 When the I<bn> is zero or positive, its OSSL_PARAM type becomes
  84 B<OSSL_PARAM_UNSIGNED_INTEGER>.
  85 When the I<bn> is negative, its OSSL_PARAM type becomes B<OSSL_PARAM_INTEGER>.
  86 If I<bn> is marked as being securely allocated, its OSSL_PARAM representation
  87 will also be securely allocated.
  88 The I<bn> argument is stored by reference and the underlying BIGNUM object
  89 must exist until after OSSL_PARAM_BLD_to_param() has been called.
  90
  91 OSSL_PARAM_BLD_push_BN_pad() is a function that will create an OSSL_PARAM object
  92 that holds the specified BIGNUM I<bn>.
  93 The object will be padded to occupy exactly I<sz> bytes, if insufficient space
  94 is specified an error results.
  95 When the I<bn> is zero or positive, its OSSL_PARAM type becomes
  96 B<OSSL_PARAM_UNSIGNED_INTEGER>.
  97 When the I<bn> is negative, its OSSL_PARAM type becomes B<OSSL_PARAM_INTEGER>.
  98 If I<bn> is marked as being securely allocated, its OSSL_PARAM representation
  99 will also be securely allocated.
 100 The I<bn> argument is stored by reference and the underlying BIGNUM object
 101 must exist until after OSSL_PARAM_BLD_to_param() has been called.
 102
 103 OSSL_PARAM_BLD_push_utf8_string() is a function that will create an OSSL_PARAM
 104 object that references the UTF8 string specified by I<buf>.
 105 The length of the string I<bsize> should not include the terminating NUL byte.
 106 If it is zero then it will be calculated.
 107 The string that I<buf> points to is stored by reference and must remain in
 108 scope until after OSSL_PARAM_BLD_to_param() has been called.
 109
 110 OSSL_PARAM_BLD_push_octet_string() is a function that will create an OSSL_PARAM
 111 object that references the octet string specified by I<buf> and <bsize>.
 112 The memory that I<buf> points to is stored by reference and must remain in
 113 scope until after OSSL_PARAM_BLD_to_param() has been called.
 114
 115 OSSL_PARAM_BLD_push_utf8_ptr() is a function that will create an OSSL_PARAM
 116 object that references the UTF8 string specified by I<buf>.
 117 The length of the string I<bsize> should not include the terminating NUL byte.
 118 If it is zero then it will be calculated.
 119 The string I<buf> points to is stored by reference and must remain in
 120 scope until the OSSL_PARAM array is freed.
 121
 122 OSSL_PARAM_BLD_push_octet_ptr() is a function that will create an OSSL_PARAM
 123 object that references the octet string specified by I<buf>.
 124 The memory I<buf> points to is stored by reference and must remain in
 125 scope until the OSSL_PARAM array is freed.
 126
 127 =head1 RETURN VALUES
 128
 129 OSSL_PARAM_BLD_new() returns the allocated OSSL_PARAM_BLD structure, or NULL
 130 on error.
 131
 132 OSSL_PARAM_BLD_to_param() returns the allocated OSSL_PARAM array, or NULL
 133 on error.
 134
 135 All of the OSSL_PARAM_BLD_push_TYPE functions return 1 on success and 0
 136 on error.
 137
 138 =head1 NOTES
 139
 140 OSSL_PARAM_BLD_push_BN() and OSSL_PARAM_BLD_push_BN_pad() only
 141 support nonnegative B<BIGNUM>s.  They return an error on negative
 142 B<BIGNUM>s.
 143 To pass signed B<BIGNUM>s, use OSSL_PARAM_BLD_push_signed_BN().
 144
 145 =head1 EXAMPLES
 146
 147 Both examples creating an OSSL_PARAM array that contains an RSA key.
 148 For both, the predefined key variables are:
 149
 150     BIGNUM *p, *q;  /* both prime */
 151     BIGNUM *n;      /* = p * q */
 152     unsigned int e; /* exponent, usually 65537 */
 153     BIGNUM *d;      /* e^-1 */
 154
 155 =head2 Example 1
 156
 157 This example shows how to create an OSSL_PARAM array that contains an RSA
 158 private key.
 159
 160     OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new();
 161     OSSL_PARAM *params = NULL;
 162
 163     if (bld == NULL
 164         || !OSSL_PARAM_BLD_push_BN(bld, "p", p)
 165         || !OSSL_PARAM_BLD_push_BN(bld, "q", q)
 166         || !OSSL_PARAM_BLD_push_uint(bld, "e", e)
 167         || !OSSL_PARAM_BLD_push_BN(bld, "n", n)
 168         || !OSSL_PARAM_BLD_push_BN(bld, "d", d)
 169         || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL)
 170         goto err;
 171     OSSL_PARAM_BLD_free(bld);
 172     /* Use params */
 173     ...
 174     OSSL_PARAM_free(params);
 175
 176 =head2 Example 2
 177
 178 This example shows how to create an OSSL_PARAM array that contains an RSA
 179 public key.
 180
 181     OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new();
 182     OSSL_PARAM *params = NULL;
 183
 184     if (nld == NULL
 185         || !OSSL_PARAM_BLD_push_BN(bld, "n", n)
 186         || !OSSL_PARAM_BLD_push_BN(bld, "e", e)
 187         || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL)
 188         goto err;
 189     OSSL_PARAM_BLD_free(bld);
 190     /* Use params */
 191     ...
 192     OSSL_PARAM_free(params);
 193
 194 =head1 SEE ALSO
 195
 196 L<OSSL_PARAM_int(3)>, L<OSSL_PARAM(3)>, L<OSSL_PARAM_free(3)>
 197
 198 =head1 HISTORY
 199
 200 The functions described here were all added in OpenSSL 3.0.
 201
 202 =head1 COPYRIGHT
 203
 204 Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.
 205
 206 Licensed under the Apache License 2.0 (the "License").  You may not use
 207 this file except in compliance with the License.  You can obtain a copy
 208 in the file LICENSE in the source distribution or at
 209 L<https://www.openssl.org/source/license.html>.
 210
 211 =cut