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 comment 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<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 B<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 B<param_n> elements is passed in as B<params>.
  68 The auxiliary storage for the parameters is a block of memory pointed to
  69 by B<data> of at least B<data_n> bytes in size.
  70 If required, secure memory for private BIGNUMs should be pointed to by
  71 B<secure> of at least B<secure_n> bytes in size.
  72
  73 ossl_param_bld_push_TYPE() are a series of functions which will create
  74 OSSL_PARAM objects of the specified size and correct type for the B<val>
  75 argument.
  76 B<val> is stored by value and an expression or auto variable can be used.
  77
  78 ossl_param_bld_push_BN() is a function that will create an OSSL_PARAM object
  79 that holds the specified BIGNUM B<bn>.
  80 If B<bn> is marked as being securely allocated, it's OSSL_PARAM representation
  81 will also be securely allocated.
  82 The B<bn> argument is stored by reference and the underlying BIGNUM object
  83 must exist until after ossl_param_bld_to_param() has been called.
  84
  85 ossl_param_bld_push_utf8_string() is a function that will create an OSSL_PARAM
  86 object that references the UTF8 string specified by B<buf>.
  87 If the length of the string, B<bsize>, is zero then it will be calculated.
  88 The string that B<buf> points to is stored by reference and must remain in
  89 scope until after ossl_param_bld_to_param() has been called.
  90
  91 ossl_param_bld_push_octet_string() is a function that will create an OSSL_PARAM
  92 object that references the octet string specified by B<buf> and <bsize>.
  93 The memory that B<buf> points to is stored by reference and must remain in
  94 scope until after ossl_param_bld_to_param() has been called.
  95
  96 ossl_param_bld_push_utf8_ptr() is a function that will create an OSSL_PARAM
  97 object that references the UTF8 string specified by B<buf>.
  98 If the length of the string, B<bsize>, is zero then it will be calculated.
  99 The string B<buf> points to is stored by reference and must remain in
 100 scope until the OSSL_PARAM array is freed.
 101
 102 ossl_param_bld_push_octet_ptr() is a function that will create an OSSL_PARAM
 103 object that references the octet string specified by B<buf>.
 104 The memory B<buf> points to is stored by reference and must remain in
 105 scope until the OSSL_PARAM array is freed.
 106
 107 =head1 RETURN VALUES
 108
 109 ossl_param_bld_to_param() and ossl_param_bld_to_param_ex() return the
 110 allocated OSSL_PARAM array, or NULL on error.
 111
 112 All of the ossl_param_bld_push_TYPE functions return 1 on success and 0
 113 on error.
 114
 115 =head1 NOTES
 116
 117 The constant B<OSSL_PARAM_BLD_MAX> specifies the maximum number of parameters
 118 that can be added.
 119 Exceeding this will result in the push functions returning errors.
 120
 121 The structure B<OSSL_PARAM_BLD> should be considered opaque and subject to
 122 change between versions.
 123
 124 =head1 EXAMPLES
 125
 126 Both examples creating an OSSL_PARAM array that contains an RSA key.
 127 For both, the predefined key variables are:
 128
 129     BIGNUM *p, *q;  /* both prime */
 130     BIGNUM *n;      /* = p * q */
 131     unsigned int e; /* exponent, usually 65537 */
 132     BIGNUM *d;      /* e^-1 */
 133
 134 =head2 Example 1
 135
 136 This example shows how to create an OSSL_PARAM array that contains an RSA
 137 private key.
 138
 139     OSSL_PARAM_BLD bld;
 140     OSSL_PARAM *params;
 141
 142     ossl_param_bld_init(&bld, &secure);
 143     if (!ossl_param_bld_push_BN(&bld, "p", p)
 144         || !ossl_param_bld_push_BN(&bld, "q", q)
 145         || !ossl_param_bld_push_uint(&bld, "e", e)
 146         || !ossl_param_bld_push_BN(&bld, "n", n)
 147         || !ossl_param_bld_push_BN(&bld, "d", d)
 148         || (params = ossl_param_bld_to_param(&bld)) == NULL)
 149         goto err;
 150     /* Use params */
 151     ...
 152     ossl_param_bld_free(params);
 153
 154 =head2 Example 2
 155
 156 This example shows how to create an OSSL_PARAM array that contains an RSA
 157 public key.
 158
 159     OSSL_PARAM_BLD bld;
 160     OSSL_PARAM *params;
 161
 162     ossl_param_bld_init(&bld, &secure);
 163     if (!ossl_param_bld_push_BN(&bld, "n", n)
 164         || !ossl_param_bld_push_BN(&bld, "d", d)
 165         || (params = ossl_param_bld_to_param(&bld)) == NULL)
 166         goto err;
 167     /* Use params */
 168     ...
 169     ossl_param_bld_free(params);
 170
 171 =head1 SEE ALSO
 172
 173 L<OSSL_PARAM_int>, L<OSSL_PARAM>
 174
 175 =head1 HISTORY
 176
 177 The functions described here were all added in OpenSSL 3.0.
 178
 179 =head1 COPYRIGHT
 180
 181 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
 182
 183 Licensed under the Apache License 2.0 (the "License").  You may not use
 184 this file except in compliance with the License.  You can obtain a copy
 185 in the file LICENSE in the source distribution or at
 186 L<https://www.openssl.org/source/license.html>.
 187
 188 =cut