doc/man3/OSSL_PARAM_BLD_new.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 OSSL_PARAM_BLD_new, OSSL_PARAM_BLD_to_param, OSSL_PARAM_BLD_free_params,
   6 OSSL_PARAM_BLD_free, OSSL_PARAM_BLD_push_int, OSSL_PARAM_BLD_push_uint,
   7 OSSL_PARAM_BLD_push_long, OSSL_PARAM_BLD_push_ulong,
   8 OSSL_PARAM_BLD_push_int32, OSSL_PARAM_BLD_push_uint32,
   9 OSSL_PARAM_BLD_push_int64, OSSL_PARAM_BLD_push_uint64,
  10 OSSL_PARAM_BLD_push_size_t, OSSL_PARAM_BLD_push_double,
  11 OSSL_PARAM_BLD_push_BN, OSSL_PARAM_BLD_push_BN_pad,
  12 OSSL_PARAM_BLD_push_utf8_string, OSSL_PARAM_BLD_push_utf8_ptr,
  13 OSSL_PARAM_BLD_push_octet_string, OSSL_PARAM_BLD_push_octet_ptr
  14 - functions to assist in the creation of OSSL_PARAM arrays
  15
  16 =head1 SYNOPSIS
  17
  18 =for openssl generic
  19
  20  #include "openssl/param_build.h"
  21
  22  typedef struct OSSL_PARAM_BLD;
  23
  24  OSSL_PARAM_BLD *OSSL_PARAM_BLD_new(void);
  25  OSSL_PARAM *OSSL_PARAM_BLD_to_param(OSSL_PARAM_BLD *bld);
  26  void OSSL_PARAM_BLD_free_params(OSSL_PARAM *params);
  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_BLD_free_params() with the functions return value.
  61 OSSL_PARAM_BLD_free() can safely be called any time after this function is.
  62
  63 OSSL_PARAM_BLD_free_params() deallocates the memory allocated by
  64 OSSL_PARAM_BLD_to_param().
  65
  66 =begin comment
  67
  68 POD is pretty good at recognising function names and making them appropriately
  69 bold...  however, when part of the function name is variable, we have to help
  70 the processor along
  71
  72 =end comment
  73
  74 B<OSSL_PARAM_BLD_push_I<TYPE>>() are a series of functions which will create
  75 OSSL_PARAM objects of the specified size and correct type for the I<val>
  76 argument.
  77 I<val> is stored by value and an expression or auto variable can be used.
  78
  79 OSSL_PARAM_BLD_push_BN() is a function that will create an OSSL_PARAM object
  80 that holds the specified BIGNUM I<bn>.
  81 If I<bn> is marked as being securely allocated, its OSSL_PARAM representation
  82 will also be securely allocated.
  83 The I<bn> argument is stored by reference and the underlying BIGNUM object
  84 must exist until after OSSL_PARAM_BLD_to_param() has been called.
  85
  86 OSSL_PARAM_BLD_push_BN_pad() is a function that will create an OSSL_PARAM object
  87 that holds the specified BIGNUM I<bn>.
  88 The object will be padded to occupy exactly I<sz> bytes, if insufficient space
  89 is specified an error results.
  90 If I<bn> is marked as being securely allocated, its OSSL_PARAM representation
  91 will also be securely allocated.
  92 The I<bn> argument is stored by reference and the underlying BIGNUM object
  93 must exist until after OSSL_PARAM_BLD_to_param() has been called.
  94
  95 OSSL_PARAM_BLD_push_utf8_string() is a function that will create an OSSL_PARAM
  96 object that references the UTF8 string specified by I<buf>.
  97 If the length of the string, I<bsize>, is zero then it will be calculated.
  98 The string that I<buf> points to is stored by reference and must remain in
  99 scope until after OSSL_PARAM_BLD_to_param() has been called.
 100
 101 OSSL_PARAM_BLD_push_octet_string() is a function that will create an OSSL_PARAM
 102 object that references the octet string specified by I<buf> and <bsize>.
 103 The memory that I<buf> points to is stored by reference and must remain in
 104 scope until after OSSL_PARAM_BLD_to_param() has been called.
 105
 106 OSSL_PARAM_BLD_push_utf8_ptr() is a function that will create an OSSL_PARAM
 107 object that references the UTF8 string specified by I<buf>.
 108 If the length of the string, I<bsize>, is zero then it will be calculated.
 109 The string I<buf> points to is stored by reference and must remain in
 110 scope until the OSSL_PARAM array is freed.
 111
 112 OSSL_PARAM_BLD_push_octet_ptr() is a function that will create an OSSL_PARAM
 113 object that references the octet string specified by I<buf>.
 114 The memory I<buf> points to is stored by reference and must remain in
 115 scope until the OSSL_PARAM array is freed.
 116
 117 =head1 RETURN VALUES
 118
 119 OSSL_PARAM_BLD_new() returns the allocated OSSL_PARAM_BLD structure, or NULL
 120 on error.
 121
 122 OSSL_PARAM_BLD_to_param() returns the allocated OSSL_PARAM array, or NULL
 123 on error.
 124
 125 All of the OSSL_PARAM_BLD_push_TYPE functions return 1 on success and 0
 126 on error.
 127
 128 =head1 EXAMPLES
 129
 130 Both examples creating an OSSL_PARAM array that contains an RSA key.
 131 For both, the predefined key variables are:
 132
 133     BIGNUM *p, *q;  /* both prime */
 134     BIGNUM *n;      /* = p * q */
 135     unsigned int e; /* exponent, usually 65537 */
 136     BIGNUM *d;      /* e^-1 */
 137
 138 =head2 Example 1
 139
 140 This example shows how to create an OSSL_PARAM array that contains an RSA
 141 private key.
 142
 143     OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new();
 144     OSSL_PARAM *params;
 145
 146     if (bld == NULL
 147         || !OSSL_PARAM_BLD_push_BN(&bld, "p", p)
 148         || !OSSL_PARAM_BLD_push_BN(&bld, "q", q)
 149         || !OSSL_PARAM_BLD_push_uint(&bld, "e", e)
 150         || !OSSL_PARAM_BLD_push_BN(&bld, "n", n)
 151         || !OSSL_PARAM_BLD_push_BN(&bld, "d", d)
 152         || (params = OSSL_PARAM_BLD_to_param(&bld)) == NULL)
 153         goto err;
 154     OSSL_PARAM_BLD_free(bld);
 155     /* Use params */
 156     ...
 157     OSSL_PARAM_BLD_free_params(params);
 158
 159 =head2 Example 2
 160
 161 This example shows how to create an OSSL_PARAM array that contains an RSA
 162 public key.
 163
 164     OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new();
 165     OSSL_PARAM *params;
 166
 167     if (nld == NULL
 168         || !OSSL_PARAM_BLD_push_BN(bld, "n", n)
 169         || !OSSL_PARAM_BLD_push_BN(bld, "d", d)
 170         || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL)
 171         goto err;
 172     OSSL_PARAM_BLD_free(bld);
 173     /* Use params */
 174     ...
 175     OSSL_PARAM_BLD_free_params(params);
 176
 177 =head1 SEE ALSO
 178
 179 L<OSSL_PARAM_int(3)>, L<OSSL_PARAM(3)>
 180
 181 =head1 HISTORY
 182
 183 The functions described here were all added in OpenSSL 3.0.
 184
 185 =head1 COPYRIGHT
 186
 187 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
 188
 189 Licensed under the Apache License 2.0 (the "License").  You may not use
 190 this file except in compliance with the License.  You can obtain a copy
 191 in the file LICENSE in the source distribution or at
 192 L<https://www.openssl.org/source/license.html>.
 193
 194 =cut