doc/man3/OSSL_PARAM_BLD.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 OSSL_PARAM_BLD, OSSL_PARAM_BLD_new, OSSL_PARAM_BLD_to_param,
   6 OSSL_PARAM_BLD_free, OSSL_PARAM_BLD_push_int,
   7 OSSL_PARAM_BLD_push_uint, OSSL_PARAM_BLD_push_long,
   8 OSSL_PARAM_BLD_push_ulong, OSSL_PARAM_BLD_push_int32,
   9 OSSL_PARAM_BLD_push_uint32, OSSL_PARAM_BLD_push_int64,
  10 OSSL_PARAM_BLD_push_uint64, OSSL_PARAM_BLD_push_size_t,
  11 OSSL_PARAM_BLD_push_time_t, OSSL_PARAM_BLD_push_double,
  12 OSSL_PARAM_BLD_push_BN, OSSL_PARAM_BLD_push_BN_pad,
  13 OSSL_PARAM_BLD_push_utf8_string, OSSL_PARAM_BLD_push_utf8_ptr,
  14 OSSL_PARAM_BLD_push_octet_string, OSSL_PARAM_BLD_push_octet_ptr
  15 - functions to assist in the creation of OSSL_PARAM arrays
  16
  17 =head1 SYNOPSIS
  18
  19 =for openssl generic
  20
  21  #include <openssl/param_build.h>
  22
  23  typedef struct OSSL_PARAM_BLD;
  24
  25  OSSL_PARAM_BLD *OSSL_PARAM_BLD_new(void);
  26  OSSL_PARAM *OSSL_PARAM_BLD_to_param(OSSL_PARAM_BLD *bld);
  27  void OSSL_PARAM_BLD_free(OSSL_PARAM_BLD *bld);
  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_new() allocates and initialises a new OSSL_PARAM_BLD structure
  52 so that values can be added.
  53 Any existing values are cleared.
  54
  55 OSSL_PARAM_BLD_free() deallocates the memory allocates by OSSL_PARAM_BLD_new().
  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_free() with the functions return value.
  61 OSSL_PARAM_BLD_free() can safely be called any time after this function is.
  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, its 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, its 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 The length of the string I<bsize> should not include the terminating NUL byte.
  95 If it 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 The length of the string I<bsize> should not include the terminating NUL byte.
 107 If it is zero then it will be calculated.
 108 The string I<buf> points to is stored by reference and must remain in
 109 scope until the OSSL_PARAM array is freed.
 110
 111 OSSL_PARAM_BLD_push_octet_ptr() is a function that will create an OSSL_PARAM
 112 object that references the octet string specified by I<buf>.
 113 The memory I<buf> points to is stored by reference and must remain in
 114 scope until the OSSL_PARAM array is freed.
 115
 116 =head1 RETURN VALUES
 117
 118 OSSL_PARAM_BLD_new() returns the allocated OSSL_PARAM_BLD structure, or NULL
 119 on error.
 120
 121 OSSL_PARAM_BLD_to_param() returns the allocated OSSL_PARAM array, or NULL
 122 on error.
 123
 124 All of the OSSL_PARAM_BLD_push_TYPE functions return 1 on success and 0
 125 on error.
 126
 127 =head1 NOTES
 128
 129 OSSL_PARAM_BLD_push_BN() and OSSL_PARAM_BLD_push_BN_pad() currently only
 130 support nonnegative B<BIGNUM>s.  They return an error on negative B<BIGNUM>s.
 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 = OSSL_PARAM_BLD_new();
 148     OSSL_PARAM *params = NULL;
 149
 150     if (bld == NULL
 151         || !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     OSSL_PARAM_BLD_free(bld);
 159     /* Use params */
 160     ...
 161     OSSL_PARAM_free(params);
 162
 163 =head2 Example 2
 164
 165 This example shows how to create an OSSL_PARAM array that contains an RSA
 166 public key.
 167
 168     OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new();
 169     OSSL_PARAM *params = NULL;
 170
 171     if (nld == NULL
 172         || !OSSL_PARAM_BLD_push_BN(bld, "n", n)
 173         || !OSSL_PARAM_BLD_push_BN(bld, "d", d)
 174         || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL)
 175         goto err;
 176     OSSL_PARAM_BLD_free(bld);
 177     /* Use params */
 178     ...
 179     OSSL_PARAM_free(params);
 180
 181 =head1 SEE ALSO
 182
 183 L<OSSL_PARAM_int(3)>, L<OSSL_PARAM(3)>, L<OSSL_PARAM_free(3)>
 184
 185 =head1 HISTORY
 186
 187 The functions described here were all added in OpenSSL 3.0.
 188
 189 =head1 COPYRIGHT
 190
 191 Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
 192
 193 Licensed under the Apache License 2.0 (the "License").  You may not use
 194 this file except in compliance with the License.  You can obtain a copy
 195 in the file LICENSE in the source distribution or at
 196 L<https://www.openssl.org/source/license.html>.
 197
 198 =cut