doc/internal/man3/ossl_param_bld_init.pod

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