1*b077aed3SPierre Pronchery=pod 2*b077aed3SPierre Pronchery 3*b077aed3SPierre Pronchery=head1 NAME 4*b077aed3SPierre Pronchery 5*b077aed3SPierre ProncheryOSSL_PARAM_BLD, OSSL_PARAM_BLD_new, OSSL_PARAM_BLD_to_param, 6*b077aed3SPierre ProncheryOSSL_PARAM_BLD_free, OSSL_PARAM_BLD_push_int, 7*b077aed3SPierre ProncheryOSSL_PARAM_BLD_push_uint, OSSL_PARAM_BLD_push_long, 8*b077aed3SPierre ProncheryOSSL_PARAM_BLD_push_ulong, OSSL_PARAM_BLD_push_int32, 9*b077aed3SPierre ProncheryOSSL_PARAM_BLD_push_uint32, OSSL_PARAM_BLD_push_int64, 10*b077aed3SPierre ProncheryOSSL_PARAM_BLD_push_uint64, OSSL_PARAM_BLD_push_size_t, 11*b077aed3SPierre ProncheryOSSL_PARAM_BLD_push_time_t, OSSL_PARAM_BLD_push_double, 12*b077aed3SPierre ProncheryOSSL_PARAM_BLD_push_BN, OSSL_PARAM_BLD_push_BN_pad, 13*b077aed3SPierre ProncheryOSSL_PARAM_BLD_push_utf8_string, OSSL_PARAM_BLD_push_utf8_ptr, 14*b077aed3SPierre ProncheryOSSL_PARAM_BLD_push_octet_string, OSSL_PARAM_BLD_push_octet_ptr 15*b077aed3SPierre Pronchery- functions to assist in the creation of OSSL_PARAM arrays 16*b077aed3SPierre Pronchery 17*b077aed3SPierre Pronchery=head1 SYNOPSIS 18*b077aed3SPierre Pronchery 19*b077aed3SPierre Pronchery=for openssl generic 20*b077aed3SPierre Pronchery 21*b077aed3SPierre Pronchery #include <openssl/param_build.h> 22*b077aed3SPierre Pronchery 23*b077aed3SPierre Pronchery typedef struct OSSL_PARAM_BLD; 24*b077aed3SPierre Pronchery 25*b077aed3SPierre Pronchery OSSL_PARAM_BLD *OSSL_PARAM_BLD_new(void); 26*b077aed3SPierre Pronchery OSSL_PARAM *OSSL_PARAM_BLD_to_param(OSSL_PARAM_BLD *bld); 27*b077aed3SPierre Pronchery void OSSL_PARAM_BLD_free(OSSL_PARAM_BLD *bld); 28*b077aed3SPierre Pronchery 29*b077aed3SPierre Pronchery int OSSL_PARAM_BLD_push_TYPE(OSSL_PARAM_BLD *bld, const char *key, TYPE val); 30*b077aed3SPierre Pronchery 31*b077aed3SPierre Pronchery int OSSL_PARAM_BLD_push_BN(OSSL_PARAM_BLD *bld, const char *key, 32*b077aed3SPierre Pronchery const BIGNUM *bn); 33*b077aed3SPierre Pronchery int OSSL_PARAM_BLD_push_BN_pad(OSSL_PARAM_BLD *bld, const char *key, 34*b077aed3SPierre Pronchery const BIGNUM *bn, size_t sz); 35*b077aed3SPierre Pronchery 36*b077aed3SPierre Pronchery int OSSL_PARAM_BLD_push_utf8_string(OSSL_PARAM_BLD *bld, const char *key, 37*b077aed3SPierre Pronchery const char *buf, size_t bsize); 38*b077aed3SPierre Pronchery int OSSL_PARAM_BLD_push_utf8_ptr(OSSL_PARAM_BLD *bld, const char *key, 39*b077aed3SPierre Pronchery char *buf, size_t bsize); 40*b077aed3SPierre Pronchery int OSSL_PARAM_BLD_push_octet_string(OSSL_PARAM_BLD *bld, const char *key, 41*b077aed3SPierre Pronchery const void *buf, size_t bsize); 42*b077aed3SPierre Pronchery int OSSL_PARAM_BLD_push_octet_ptr(OSSL_PARAM_BLD *bld, const char *key, 43*b077aed3SPierre Pronchery void *buf, size_t bsize); 44*b077aed3SPierre Pronchery 45*b077aed3SPierre Pronchery 46*b077aed3SPierre Pronchery=head1 DESCRIPTION 47*b077aed3SPierre Pronchery 48*b077aed3SPierre ProncheryA collection of utility functions that simplify the creation of OSSL_PARAM 49*b077aed3SPierre Proncheryarrays. The B<I<TYPE>> names are as per L<OSSL_PARAM_int(3)>. 50*b077aed3SPierre Pronchery 51*b077aed3SPierre ProncheryOSSL_PARAM_BLD_new() allocates and initialises a new OSSL_PARAM_BLD structure 52*b077aed3SPierre Proncheryso that values can be added. 53*b077aed3SPierre ProncheryAny existing values are cleared. 54*b077aed3SPierre Pronchery 55*b077aed3SPierre ProncheryOSSL_PARAM_BLD_free() deallocates the memory allocates by OSSL_PARAM_BLD_new(). 56*b077aed3SPierre Pronchery 57*b077aed3SPierre ProncheryOSSL_PARAM_BLD_to_param() converts a built up OSSL_PARAM_BLD structure 58*b077aed3SPierre ProncheryI<bld> into an allocated OSSL_PARAM array. 59*b077aed3SPierre ProncheryThe OSSL_PARAM array and all associated storage must be freed by calling 60*b077aed3SPierre ProncheryOSSL_PARAM_free() with the functions return value. 61*b077aed3SPierre ProncheryOSSL_PARAM_BLD_free() can safely be called any time after this function is. 62*b077aed3SPierre Pronchery 63*b077aed3SPierre Pronchery=begin comment 64*b077aed3SPierre Pronchery 65*b077aed3SPierre ProncheryPOD is pretty good at recognising function names and making them appropriately 66*b077aed3SPierre Proncherybold... however, when part of the function name is variable, we have to help 67*b077aed3SPierre Proncherythe processor along 68*b077aed3SPierre Pronchery 69*b077aed3SPierre Pronchery=end comment 70*b077aed3SPierre Pronchery 71*b077aed3SPierre ProncheryB<OSSL_PARAM_BLD_push_I<TYPE>>() are a series of functions which will create 72*b077aed3SPierre ProncheryOSSL_PARAM objects of the specified size and correct type for the I<val> 73*b077aed3SPierre Proncheryargument. 74*b077aed3SPierre ProncheryI<val> is stored by value and an expression or auto variable can be used. 75*b077aed3SPierre Pronchery 76*b077aed3SPierre ProncheryOSSL_PARAM_BLD_push_BN() is a function that will create an OSSL_PARAM object 77*b077aed3SPierre Proncherythat holds the specified BIGNUM I<bn>. 78*b077aed3SPierre ProncheryIf I<bn> is marked as being securely allocated, its OSSL_PARAM representation 79*b077aed3SPierre Proncherywill also be securely allocated. 80*b077aed3SPierre ProncheryThe I<bn> argument is stored by reference and the underlying BIGNUM object 81*b077aed3SPierre Proncherymust exist until after OSSL_PARAM_BLD_to_param() has been called. 82*b077aed3SPierre Pronchery 83*b077aed3SPierre ProncheryOSSL_PARAM_BLD_push_BN_pad() is a function that will create an OSSL_PARAM object 84*b077aed3SPierre Proncherythat holds the specified BIGNUM I<bn>. 85*b077aed3SPierre ProncheryThe object will be padded to occupy exactly I<sz> bytes, if insufficient space 86*b077aed3SPierre Proncheryis specified an error results. 87*b077aed3SPierre ProncheryIf I<bn> is marked as being securely allocated, its OSSL_PARAM representation 88*b077aed3SPierre Proncherywill also be securely allocated. 89*b077aed3SPierre ProncheryThe I<bn> argument is stored by reference and the underlying BIGNUM object 90*b077aed3SPierre Proncherymust exist until after OSSL_PARAM_BLD_to_param() has been called. 91*b077aed3SPierre Pronchery 92*b077aed3SPierre ProncheryOSSL_PARAM_BLD_push_utf8_string() is a function that will create an OSSL_PARAM 93*b077aed3SPierre Proncheryobject that references the UTF8 string specified by I<buf>. 94*b077aed3SPierre ProncheryThe length of the string I<bsize> should not include the terminating NUL byte. 95*b077aed3SPierre ProncheryIf it is zero then it will be calculated. 96*b077aed3SPierre ProncheryThe string that I<buf> points to is stored by reference and must remain in 97*b077aed3SPierre Proncheryscope until after OSSL_PARAM_BLD_to_param() has been called. 98*b077aed3SPierre Pronchery 99*b077aed3SPierre ProncheryOSSL_PARAM_BLD_push_octet_string() is a function that will create an OSSL_PARAM 100*b077aed3SPierre Proncheryobject that references the octet string specified by I<buf> and <bsize>. 101*b077aed3SPierre ProncheryThe memory that I<buf> points to is stored by reference and must remain in 102*b077aed3SPierre Proncheryscope until after OSSL_PARAM_BLD_to_param() has been called. 103*b077aed3SPierre Pronchery 104*b077aed3SPierre ProncheryOSSL_PARAM_BLD_push_utf8_ptr() is a function that will create an OSSL_PARAM 105*b077aed3SPierre Proncheryobject that references the UTF8 string specified by I<buf>. 106*b077aed3SPierre ProncheryThe length of the string I<bsize> should not include the terminating NUL byte. 107*b077aed3SPierre ProncheryIf it is zero then it will be calculated. 108*b077aed3SPierre ProncheryThe string I<buf> points to is stored by reference and must remain in 109*b077aed3SPierre Proncheryscope until the OSSL_PARAM array is freed. 110*b077aed3SPierre Pronchery 111*b077aed3SPierre ProncheryOSSL_PARAM_BLD_push_octet_ptr() is a function that will create an OSSL_PARAM 112*b077aed3SPierre Proncheryobject that references the octet string specified by I<buf>. 113*b077aed3SPierre ProncheryThe memory I<buf> points to is stored by reference and must remain in 114*b077aed3SPierre Proncheryscope until the OSSL_PARAM array is freed. 115*b077aed3SPierre Pronchery 116*b077aed3SPierre Pronchery=head1 RETURN VALUES 117*b077aed3SPierre Pronchery 118*b077aed3SPierre ProncheryOSSL_PARAM_BLD_new() returns the allocated OSSL_PARAM_BLD structure, or NULL 119*b077aed3SPierre Proncheryon error. 120*b077aed3SPierre Pronchery 121*b077aed3SPierre ProncheryOSSL_PARAM_BLD_to_param() returns the allocated OSSL_PARAM array, or NULL 122*b077aed3SPierre Proncheryon error. 123*b077aed3SPierre Pronchery 124*b077aed3SPierre ProncheryAll of the OSSL_PARAM_BLD_push_TYPE functions return 1 on success and 0 125*b077aed3SPierre Proncheryon error. 126*b077aed3SPierre Pronchery 127*b077aed3SPierre Pronchery=head1 NOTES 128*b077aed3SPierre Pronchery 129*b077aed3SPierre ProncheryOSSL_PARAM_BLD_push_BN() and OSSL_PARAM_BLD_push_BN_pad() currently only 130*b077aed3SPierre Proncherysupport nonnegative B<BIGNUM>s. They return an error on negative B<BIGNUM>s. 131*b077aed3SPierre Pronchery 132*b077aed3SPierre Pronchery=head1 EXAMPLES 133*b077aed3SPierre Pronchery 134*b077aed3SPierre ProncheryBoth examples creating an OSSL_PARAM array that contains an RSA key. 135*b077aed3SPierre ProncheryFor both, the predefined key variables are: 136*b077aed3SPierre Pronchery 137*b077aed3SPierre Pronchery BIGNUM *n; /* modulus */ 138*b077aed3SPierre Pronchery unsigned int e; /* public exponent */ 139*b077aed3SPierre Pronchery BIGNUM *d; /* private exponent */ 140*b077aed3SPierre Pronchery BIGNUM *p, *q; /* first two prime factors */ 141*b077aed3SPierre Pronchery BIGNUM *dmp1, *dmq1; /* first two CRT exponents */ 142*b077aed3SPierre Pronchery BIGNUM *iqmp; /* first CRT coefficient */ 143*b077aed3SPierre Pronchery 144*b077aed3SPierre Pronchery=head2 Example 1 145*b077aed3SPierre Pronchery 146*b077aed3SPierre ProncheryThis example shows how to create an OSSL_PARAM array that contains an RSA 147*b077aed3SPierre Proncheryprivate key. 148*b077aed3SPierre Pronchery 149*b077aed3SPierre Pronchery OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new(); 150*b077aed3SPierre Pronchery OSSL_PARAM *params = NULL; 151*b077aed3SPierre Pronchery 152*b077aed3SPierre Pronchery if (bld == NULL 153*b077aed3SPierre Pronchery || !OSSL_PARAM_BLD_push_BN(bld, "n", n) 154*b077aed3SPierre Pronchery || !OSSL_PARAM_BLD_push_uint(bld, "e", e) 155*b077aed3SPierre Pronchery || !OSSL_PARAM_BLD_push_BN(bld, "d", d) 156*b077aed3SPierre Pronchery || !OSSL_PARAM_BLD_push_BN(bld, "rsa-factor1", p) 157*b077aed3SPierre Pronchery || !OSSL_PARAM_BLD_push_BN(bld, "rsa-factor2", q) 158*b077aed3SPierre Pronchery || !OSSL_PARAM_BLD_push_BN(bld, "rsa-exponent1", dmp1) 159*b077aed3SPierre Pronchery || !OSSL_PARAM_BLD_push_BN(bld, "rsa-exponent2", dmq1) 160*b077aed3SPierre Pronchery || !OSSL_PARAM_BLD_push_BN(bld, "rsa-coefficient1", iqmp) 161*b077aed3SPierre Pronchery || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL) 162*b077aed3SPierre Pronchery goto err; 163*b077aed3SPierre Pronchery OSSL_PARAM_BLD_free(bld); 164*b077aed3SPierre Pronchery /* Use params */ 165*b077aed3SPierre Pronchery ... 166*b077aed3SPierre Pronchery OSSL_PARAM_free(params); 167*b077aed3SPierre Pronchery 168*b077aed3SPierre Pronchery=head2 Example 2 169*b077aed3SPierre Pronchery 170*b077aed3SPierre ProncheryThis example shows how to create an OSSL_PARAM array that contains an RSA 171*b077aed3SPierre Proncherypublic key. 172*b077aed3SPierre Pronchery 173*b077aed3SPierre Pronchery OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new(); 174*b077aed3SPierre Pronchery OSSL_PARAM *params = NULL; 175*b077aed3SPierre Pronchery 176*b077aed3SPierre Pronchery if (nld == NULL 177*b077aed3SPierre Pronchery || !OSSL_PARAM_BLD_push_BN(bld, "n", n) 178*b077aed3SPierre Pronchery || !OSSL_PARAM_BLD_push_uint(bld, "e", e) 179*b077aed3SPierre Pronchery || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL) 180*b077aed3SPierre Pronchery goto err; 181*b077aed3SPierre Pronchery OSSL_PARAM_BLD_free(bld); 182*b077aed3SPierre Pronchery /* Use params */ 183*b077aed3SPierre Pronchery ... 184*b077aed3SPierre Pronchery OSSL_PARAM_free(params); 185*b077aed3SPierre Pronchery 186*b077aed3SPierre Pronchery=head1 SEE ALSO 187*b077aed3SPierre Pronchery 188*b077aed3SPierre ProncheryL<OSSL_PARAM_int(3)>, L<OSSL_PARAM(3)>, L<OSSL_PARAM_free(3)> 189*b077aed3SPierre Pronchery 190*b077aed3SPierre Pronchery=head1 HISTORY 191*b077aed3SPierre Pronchery 192*b077aed3SPierre ProncheryThe functions described here were all added in OpenSSL 3.0. 193*b077aed3SPierre Pronchery 194*b077aed3SPierre Pronchery=head1 COPYRIGHT 195*b077aed3SPierre Pronchery 196*b077aed3SPierre ProncheryCopyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved. 197*b077aed3SPierre Pronchery 198*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 199*b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 200*b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 201*b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 202*b077aed3SPierre Pronchery 203*b077aed3SPierre Pronchery=cut 204