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