doc/internal/man3/ossl_param_bld_init.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 ossl_param_build_init,
   6 ossl_param_build_to_param, ossl_param_build_push_int,
   7 ossl_param_build_push_uint, ossl_param_build_push_long,
   8 ossl_param_build_push_ulong, ossl_param_build_push_int32,
   9 ossl_param_build_push_uint32, ossl_param_build_push_int64,
  10 ossl_param_build_push_uint64, ossl_param_build_push_size_t,
  11 ossl_param_build_push_double, ossl_param_build_push_BN,
  12 ossl_param_build_push_utf8_string, ossl_param_build_push_utf8_ptr,
  13 ossl_param_build_push_octet_string, ossl_param_build_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_template.h"
  21
  22  #define OSSL_PARAM_BLD_MAX 10
  23  typedef struct { ... } OSSL_PARAM_BLD;
  24
  25  void ossl_param_build_init(OSSL_PARAM_BLD *bld);
  26  OSSL_PARAM *ossl_param_build_to_param(OSSL_PARAM_BLD *bld, void **secure);
  27  OSSL_PARAM *ossl_param_build_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
  32  int ossl_param_build_push_TYPE(OSSL_PARAM_BLD *bld, const char *key, TYPE val);
  33
  34  int ossl_param_build_push_BN(OSSL_PARAM_BLD *bld, const char *key,
  35                             const BIGNUM *bn);
  36
  37  int ossl_param_build_push_utf8_string(OSSL_PARAM_BLD *bld, const char *key,
  38                                      char *buf, size_t bsize);
  39  int ossl_param_build_push_utf8_ptr(OSSL_PARAM_BLD *bld, const char *key,
  40                                   char *buf, size_t bsize);
  41  int ossl_param_build_push_octet_string(OSSL_PARAM_BLD *bld, const char *key,
  42                                       void *buf, size_t bsize);
  43  int ossl_param_build_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<TYPE> names are as per L<OSSL_PARAM_int(3)>.
  51
  52 ossl_param_build_init() initialises the OSSL_PARAM_BLD structure so that values
  53 can be added.
  54 Any existing values are cleared.
  55
  56 ossl_param_build_to_param() converts a built up OSSL_PARAM_BLD structure
  57 B<bld> into an allocated OSSL_PARAM array.
  58 The pointer referenced by the B<secure> argument is set to point to an
  59 allocated block of secure memory if required and to NULL it not.
  60 The OSSL_PARAM array and all associated storage can be freed by calling
  61 OPENSSL_free() with the functions return value and OPENSSL_secure_free()
  62 with the pointer referenced by B<secure>.
  63
  64 ossl_param_build_to_param_ex() behaves like ossl_param_build_to_param(), except that
  65 no additional memory is allocated.
  66 An OSSL_PARAM array of at least B<param_n> elements is passed in as B<params>.
  67 The auxiliary storage for the parameters is a block of memory pointed to
  68 by B<data> of at least B<data_n> bytes in size.
  69 If required, secure memory for private BIGNUMs should be pointed to by
  70 B<secure> of at least B<secure_n> bytes in size.
  71
  72 ossl_param_build_push_TYPE() are a series of functions which will create
  73 OSSL_PARAM objects of the specified size and correct type for the B<val>
  74 argument.
  75 B<val> is stored by value and an expression or auto variable can be used.
  76
  77 ossl_param_build_push_BN() is a function that will create an OSSL_PARAM object
  78 that holds the specified BIGNUM B<bn>.
  79 If B<bn> is marked as being securely allocated, the secure flag is
  80 set in the OSSL_PARAM_BLD structure.
  81 The B<bn> argument is stored by reference and the underlying BIGNUM object
  82 must exist until after ossl_param_build_to_param() has been called.
  83
  84 ossl_param_build_push_utf8_string() is a function that will create an OSSL_PARAM
  85 object that references the UTF8 string specified by B<buf>.
  86 If the length of the string, B<bsize>, is zero then it will be calculated.
  87 The string that B<buf> points to is stored by reference and must remain in
  88 scope until after ossl_param_build_to_param() has been called.
  89
  90 ossl_param_build_push_octet_string() is a function that will create an OSSL_PARAM
  91 object that references the octet string specified by B<buf> and <bsize>.
  92 The memory that B<buf> points to is stored by reference and must remain in
  93 scope until after ossl_param_build_to_param() has been called.
  94
  95 ossl_param_build_push_utf8_ptr() is a function that will create an OSSL_PARAM
  96 object that references the UTF8 string specified by B<buf>.
  97 If the length of the string, B<bsize>, is zero then it will be calculated.
  98 The string B<buf> points to is stored by reference and must remain in
  99 scope until the OSSL_PARAM array is freed.
 100
 101 ossl_param_build_push_octet_ptr() is a function that will create an OSSL_PARAM
 102 object that references the octet string specified by B<buf>.
 103 The memory B<buf> points to is stored by reference and must remain in
 104 scope until the OSSL_PARAM array is freed.
 105
 106 =head1 RETURN VALUES
 107
 108 ossl_param_build_to_param() and ossl_param_bld_to_param_ex() return the
 109 allocated OSSL_PARAM array, or NULL on error.
 110
 111 All of the ossl_param_build_push_TYPE functions return 1 on success and 0
 112 on error.
 113
 114 =head1 NOTES
 115
 116 The constant B<OSSL_PARAM_BLD_MAX> specifies the maximum number of parameters
 117 that can be added.
 118 Exceeding this will result in the push functions returning errors.
 119
 120 The structure B<OSSL_PARAM_BLD> should be considered opaque and subject to
 121 change between versions.
 122
 123 =head1 EXAMPLES
 124
 125 Both examples creating an OSSL_PARAM array that contains an RSA key.
 126 For both, the predefined key variables are:
 127
 128     BIGNUM *p, *q;  /* both prime */
 129     BIGNUM *n;      /* = p * q */
 130     unsigned int e; /* exponent, usually 65537 */
 131     BIGNUM *d;      /* e^-1 */
 132
 133 =head2 Example 1
 134
 135 This example shows how to create an OSSL_PARAM array that contains an RSA
 136 private key.
 137
 138     OSSL_PARAM_BLD bld;
 139     OSSL_PARAM *params;
 140     void *secure;
 141
 142     ossl_param_build_init(&bld, &secure);
 143     if (!ossl_param_build_push_BN(&bld, "p", p)
 144         || !ossl_param_build_push_BN(&bld, "q", q)
 145         || !ossl_param_build_push_uint(&bld, "e", e)
 146         || !ossl_param_build_push_BN(&bld, "n", n)
 147         || !ossl_param_build_push_BN(&bld, "d", d)
 148         || (params = ossl_param_build_to_param(&bld)) == NULL)
 149         goto err;
 150     /* Use params */
 151     ...
 152     OPENSSL_free(params);
 153     OPENSSL_secure_free(secure);
 154
 155 =head2 Example 2
 156
 157 This example shows how to create an OSSL_PARAM array that contains an RSA
 158 public key.
 159
 160     OSSL_PARAM_BLD bld;
 161     OSSL_PARAM *params;
 162     void *secure;
 163
 164     ossl_param_build_init(&bld, &secure);
 165     if (!ossl_param_build_push_BN(&bld, "n", n)
 166         || !ossl_param_build_push_BN(&bld, "d", d)
 167         || (params = ossl_param_build_to_param(&bld)) == NULL)
 168         goto err;
 169     /* Use params */
 170     ...
 171     OPENSSL_free(params);
 172     OPENSSL_secure_free(secure);
 173
 174 =head1 SEE ALSO
 175
 176 L<OSSL_PARAM_int>, L<OSSL_PARAM>
 177
 178 =head1 HISTORY
 179
 180 The functions described here were all added in OpenSSL 3.0.
 181
 182 =head1 COPYRIGHT
 183
 184 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
 185
 186 Licensed under the Apache License 2.0 (the "License").  You may not use
 187 this file except in compliance with the License.  You can obtain a copy
 188 in the file LICENSE in the source distribution or at
 189 L<https://www.openssl.org/source/license.html>.
 190
 191 =cut