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