1=pod 2 3=head1 NAME 4 5OSSL_PARAM_BLD, OSSL_PARAM_BLD_new, OSSL_PARAM_BLD_to_param, 6OSSL_PARAM_BLD_free, OSSL_PARAM_BLD_push_int, 7OSSL_PARAM_BLD_push_uint, OSSL_PARAM_BLD_push_long, 8OSSL_PARAM_BLD_push_ulong, OSSL_PARAM_BLD_push_int32, 9OSSL_PARAM_BLD_push_uint32, OSSL_PARAM_BLD_push_int64, 10OSSL_PARAM_BLD_push_uint64, OSSL_PARAM_BLD_push_size_t, 11OSSL_PARAM_BLD_push_time_t, OSSL_PARAM_BLD_push_double, 12OSSL_PARAM_BLD_push_BN, OSSL_PARAM_BLD_push_BN_pad, 13OSSL_PARAM_BLD_push_utf8_string, OSSL_PARAM_BLD_push_utf8_ptr, 14OSSL_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 48A collection of utility functions that simplify the creation of OSSL_PARAM 49arrays. The B<I<TYPE>> names are as per L<OSSL_PARAM_int(3)>. 50 51OSSL_PARAM_BLD_new() allocates and initialises a new OSSL_PARAM_BLD structure 52so that values can be added. 53Any existing values are cleared. 54 55OSSL_PARAM_BLD_free() deallocates the memory allocates by OSSL_PARAM_BLD_new(). 56 57OSSL_PARAM_BLD_to_param() converts a built up OSSL_PARAM_BLD structure 58I<bld> into an allocated OSSL_PARAM array. 59The OSSL_PARAM array and all associated storage must be freed by calling 60OSSL_PARAM_free() with the functions return value. 61OSSL_PARAM_BLD_free() can safely be called any time after this function is. 62 63=begin comment 64 65POD is pretty good at recognising function names and making them appropriately 66bold... however, when part of the function name is variable, we have to help 67the processor along 68 69=end comment 70 71B<OSSL_PARAM_BLD_push_I<TYPE>>() are a series of functions which will create 72OSSL_PARAM objects of the specified size and correct type for the I<val> 73argument. 74I<val> is stored by value and an expression or auto variable can be used. 75 76OSSL_PARAM_BLD_push_BN() is a function that will create an OSSL_PARAM object 77that holds the specified BIGNUM I<bn>. 78If I<bn> is marked as being securely allocated, its OSSL_PARAM representation 79will also be securely allocated. 80The I<bn> argument is stored by reference and the underlying BIGNUM object 81must exist until after OSSL_PARAM_BLD_to_param() has been called. 82 83OSSL_PARAM_BLD_push_BN_pad() is a function that will create an OSSL_PARAM object 84that holds the specified BIGNUM I<bn>. 85The object will be padded to occupy exactly I<sz> bytes, if insufficient space 86is specified an error results. 87If I<bn> is marked as being securely allocated, its OSSL_PARAM representation 88will also be securely allocated. 89The I<bn> argument is stored by reference and the underlying BIGNUM object 90must exist until after OSSL_PARAM_BLD_to_param() has been called. 91 92OSSL_PARAM_BLD_push_utf8_string() is a function that will create an OSSL_PARAM 93object that references the UTF8 string specified by I<buf>. 94The length of the string I<bsize> should not include the terminating NUL byte. 95If it is zero then it will be calculated. 96The string that I<buf> points to is stored by reference and must remain in 97scope until after OSSL_PARAM_BLD_to_param() has been called. 98 99OSSL_PARAM_BLD_push_octet_string() is a function that will create an OSSL_PARAM 100object that references the octet string specified by I<buf> and <bsize>. 101The memory that I<buf> points to is stored by reference and must remain in 102scope until after OSSL_PARAM_BLD_to_param() has been called. 103 104OSSL_PARAM_BLD_push_utf8_ptr() is a function that will create an OSSL_PARAM 105object that references the UTF8 string specified by I<buf>. 106The length of the string I<bsize> should not include the terminating NUL byte. 107If it is zero then it will be calculated. 108The string I<buf> points to is stored by reference and must remain in 109scope until the OSSL_PARAM array is freed. 110 111OSSL_PARAM_BLD_push_octet_ptr() is a function that will create an OSSL_PARAM 112object that references the octet string specified by I<buf>. 113The memory I<buf> points to is stored by reference and must remain in 114scope until the OSSL_PARAM array is freed. 115 116=head1 RETURN VALUES 117 118OSSL_PARAM_BLD_new() returns the allocated OSSL_PARAM_BLD structure, or NULL 119on error. 120 121OSSL_PARAM_BLD_to_param() returns the allocated OSSL_PARAM array, or NULL 122on error. 123 124All of the OSSL_PARAM_BLD_push_TYPE functions return 1 on success and 0 125on error. 126 127=head1 EXAMPLES 128 129Both examples creating an OSSL_PARAM array that contains an RSA key. 130For both, the predefined key variables are: 131 132 BIGNUM *p, *q; /* both prime */ 133 BIGNUM *n; /* = p * q */ 134 unsigned int e; /* exponent, usually 65537 */ 135 BIGNUM *d; /* e^-1 */ 136 137=head2 Example 1 138 139This example shows how to create an OSSL_PARAM array that contains an RSA 140private key. 141 142 OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new(); 143 OSSL_PARAM *params = NULL; 144 145 if (bld == NULL 146 || !OSSL_PARAM_BLD_push_BN(bld, "p", p) 147 || !OSSL_PARAM_BLD_push_BN(bld, "q", q) 148 || !OSSL_PARAM_BLD_push_uint(bld, "e", e) 149 || !OSSL_PARAM_BLD_push_BN(bld, "n", n) 150 || !OSSL_PARAM_BLD_push_BN(bld, "d", d) 151 || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL) 152 goto err; 153 OSSL_PARAM_BLD_free(bld); 154 /* Use params */ 155 ... 156 OSSL_PARAM_free(params); 157 158=head2 Example 2 159 160This example shows how to create an OSSL_PARAM array that contains an RSA 161public key. 162 163 OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new(); 164 OSSL_PARAM *params = NULL; 165 166 if (nld == NULL 167 || !OSSL_PARAM_BLD_push_BN(bld, "n", n) 168 || !OSSL_PARAM_BLD_push_BN(bld, "d", d) 169 || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL) 170 goto err; 171 OSSL_PARAM_BLD_free(bld); 172 /* Use params */ 173 ... 174 OSSL_PARAM_free(params); 175 176=head1 SEE ALSO 177 178L<OSSL_PARAM_int(3)>, L<OSSL_PARAM(3)>, L<OSSL_PARAM_free(3)> 179 180=head1 HISTORY 181 182The functions described here were all added in OpenSSL 3.0. 183 184=head1 COPYRIGHT 185 186Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. 187 188Licensed under the Apache License 2.0 (the "License"). You may not use 189this file except in compliance with the License. You can obtain a copy 190in the file LICENSE in the source distribution or at 191L<https://www.openssl.org/source/license.html>. 192 193=cut 194