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