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 77When B<I<TYPE>> denotes an integer type, signed integer types will normally 78get the OSSL_PARAM type B<OSSL_PARAM_INTEGER> params. 79When B<I<TYPE>> denotes an unsigned integer type will get the OSSL_PARAM type 80B<OSSL_PARAM_UNSIGNED_INTEGER>. 81 82OSSL_PARAM_BLD_push_BN() is a function that will create an OSSL_PARAM object 83that holds the specified BIGNUM I<bn>. 84When the I<bn> is zero or positive, its OSSL_PARAM type becomes 85B<OSSL_PARAM_UNSIGNED_INTEGER>. 86When the I<bn> is negative, its OSSL_PARAM type becomes B<OSSL_PARAM_INTEGER>. 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_BN_pad() is a function that will create an OSSL_PARAM object 93that holds the specified BIGNUM I<bn>. 94The object will be padded to occupy exactly I<sz> bytes, if insufficient space 95is specified an error results. 96When the I<bn> is zero or positive, its OSSL_PARAM type becomes 97B<OSSL_PARAM_UNSIGNED_INTEGER>. 98When the I<bn> is negative, its OSSL_PARAM type becomes B<OSSL_PARAM_INTEGER>. 99If I<bn> is marked as being securely allocated, its OSSL_PARAM representation 100will also be securely allocated. 101The I<bn> argument is stored by reference and the underlying BIGNUM object 102must exist until after OSSL_PARAM_BLD_to_param() has been called. 103 104OSSL_PARAM_BLD_push_utf8_string() 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 that I<buf> points to is stored by reference and must remain in 109scope until after OSSL_PARAM_BLD_to_param() has been called. 110 111OSSL_PARAM_BLD_push_octet_string() is a function that will create an OSSL_PARAM 112object that references the octet string specified by I<buf> and <bsize>. 113The memory that I<buf> points to is stored by reference and must remain in 114scope until after OSSL_PARAM_BLD_to_param() has been called. 115 116OSSL_PARAM_BLD_push_utf8_ptr() is a function that will create an OSSL_PARAM 117object that references the UTF8 string specified by I<buf>. 118The length of the string I<bsize> should not include the terminating NUL byte. 119If it is zero then it will be calculated. 120The string I<buf> points to is stored by reference and must remain in 121scope until the OSSL_PARAM array is freed. 122 123OSSL_PARAM_BLD_push_octet_ptr() is a function that will create an OSSL_PARAM 124object that references the octet string specified by I<buf>. 125The memory I<buf> points to is stored by reference and must remain in 126scope until the OSSL_PARAM array is freed. 127 128=head1 RETURN VALUES 129 130OSSL_PARAM_BLD_new() returns the allocated OSSL_PARAM_BLD structure, or NULL 131on error. 132 133OSSL_PARAM_BLD_to_param() returns the allocated OSSL_PARAM array, or NULL 134on error. 135 136All of the OSSL_PARAM_BLD_push_TYPE functions return 1 on success and 0 137on error. 138 139=head1 NOTES 140 141OSSL_PARAM_BLD_push_BN() and OSSL_PARAM_BLD_push_BN_pad() only 142support nonnegative B<BIGNUM>s. They return an error on negative 143B<BIGNUM>s. 144To pass signed B<BIGNUM>s, use OSSL_PARAM_BLD_push_signed_BN(). 145 146=head1 EXAMPLES 147 148Both examples creating an OSSL_PARAM array that contains an RSA key. 149For both, the predefined key variables are: 150 151 BIGNUM *n; /* modulus */ 152 unsigned int e; /* public exponent */ 153 BIGNUM *d; /* private exponent */ 154 BIGNUM *p, *q; /* first two prime factors */ 155 BIGNUM *dmp1, *dmq1; /* first two CRT exponents */ 156 BIGNUM *iqmp; /* first CRT coefficient */ 157 158=head2 Example 1 159 160This example shows how to create an OSSL_PARAM array that contains an RSA 161private key. 162 163 OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new(); 164 OSSL_PARAM *params = NULL; 165 166 if (bld == NULL 167 || !OSSL_PARAM_BLD_push_BN(bld, "n", n) 168 || !OSSL_PARAM_BLD_push_uint(bld, "e", e) 169 || !OSSL_PARAM_BLD_push_BN(bld, "d", d) 170 || !OSSL_PARAM_BLD_push_BN(bld, "rsa-factor1", p) 171 || !OSSL_PARAM_BLD_push_BN(bld, "rsa-factor2", q) 172 || !OSSL_PARAM_BLD_push_BN(bld, "rsa-exponent1", dmp1) 173 || !OSSL_PARAM_BLD_push_BN(bld, "rsa-exponent2", dmq1) 174 || !OSSL_PARAM_BLD_push_BN(bld, "rsa-coefficient1", iqmp) 175 || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL) 176 goto err; 177 OSSL_PARAM_BLD_free(bld); 178 /* Use params */ 179 ... 180 OSSL_PARAM_free(params); 181 182=head2 Example 2 183 184This example shows how to create an OSSL_PARAM array that contains an RSA 185public key. 186 187 OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new(); 188 OSSL_PARAM *params = NULL; 189 190 if (nld == NULL 191 || !OSSL_PARAM_BLD_push_BN(bld, "n", n) 192 || !OSSL_PARAM_BLD_push_uint(bld, "e", e) 193 || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL) 194 goto err; 195 OSSL_PARAM_BLD_free(bld); 196 /* Use params */ 197 ... 198 OSSL_PARAM_free(params); 199 200=head1 SEE ALSO 201 202L<OSSL_PARAM_int(3)>, L<OSSL_PARAM(3)>, L<OSSL_PARAM_free(3)> 203 204=head1 HISTORY 205 206The functions described here were all added in OpenSSL 3.0. 207 208=head1 COPYRIGHT 209 210Copyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved. 211 212Licensed under the Apache License 2.0 (the "License"). You may not use 213this file except in compliance with the License. You can obtain a copy 214in the file LICENSE in the source distribution or at 215L<https://www.openssl.org/source/license.html>. 216 217=cut 218