1OSSL_PARAM_BLD(3ossl) OpenSSL OSSL_PARAM_BLD(3ossl)
2
6 OSSL_PARAM_BLD, OSSL_PARAM_BLD_new, OSSL_PARAM_BLD_to_param,
7 OSSL_PARAM_BLD_free, OSSL_PARAM_BLD_push_int, OSSL_PARAM_BLD_push_uint,
8 OSSL_PARAM_BLD_push_long, OSSL_PARAM_BLD_push_ulong,
9 OSSL_PARAM_BLD_push_int32, OSSL_PARAM_BLD_push_uint32,
10 OSSL_PARAM_BLD_push_int64, OSSL_PARAM_BLD_push_uint64,
11 OSSL_PARAM_BLD_push_size_t, OSSL_PARAM_BLD_push_time_t,
12 OSSL_PARAM_BLD_push_double, OSSL_PARAM_BLD_push_BN,
13 OSSL_PARAM_BLD_push_BN_pad, OSSL_PARAM_BLD_push_utf8_string,
14 OSSL_PARAM_BLD_push_utf8_ptr, OSSL_PARAM_BLD_push_octet_string,
15 OSSL_PARAM_BLD_push_octet_ptr - functions to assist in the creation of
16 OSSL_PARAM arrays
17
19 #include <openssl/param_build.h>
20 typedef struct OSSL_PARAM_BLD;
22 OSSL_PARAM_BLD *OSSL_PARAM_BLD_new(void);
24 OSSL_PARAM *OSSL_PARAM_BLD_to_param(OSSL_PARAM_BLD *bld);
25 void OSSL_PARAM_BLD_free(OSSL_PARAM_BLD *bld);
26 int OSSL_PARAM_BLD_push_TYPE(OSSL_PARAM_BLD *bld, const char *key, TYPE val);
28 int OSSL_PARAM_BLD_push_BN(OSSL_PARAM_BLD *bld, const char *key,
30 const BIGNUM *bn);
31 int OSSL_PARAM_BLD_push_BN_pad(OSSL_PARAM_BLD *bld, const char *key,
32 const BIGNUM *bn, size_t sz);
33 int OSSL_PARAM_BLD_push_utf8_string(OSSL_PARAM_BLD *bld, const char *key,
35 const char *buf, size_t bsize);
36 int OSSL_PARAM_BLD_push_utf8_ptr(OSSL_PARAM_BLD *bld, const char *key,
37 char *buf, size_t bsize);
38 int OSSL_PARAM_BLD_push_octet_string(OSSL_PARAM_BLD *bld, const char *key,
39 const void *buf, size_t bsize);
40 int OSSL_PARAM_BLD_push_octet_ptr(OSSL_PARAM_BLD *bld, const char *key,
41 void *buf, size_t bsize);
42
44 A collection of utility functions that simplify the creation of
45 OSSL_PARAM arrays. The TYPE names are as per OSSL_PARAM_int(3).
46 OSSL_PARAM_BLD_new() allocates and initialises a new OSSL_PARAM_BLD
48 structure so that values can be added. Any existing values are
49 cleared.
50 OSSL_PARAM_BLD_free() deallocates the memory allocates by
52 OSSL_PARAM_BLD_new().
53 OSSL_PARAM_BLD_to_param() converts a built up OSSL_PARAM_BLD structure
55 bld into an allocated OSSL_PARAM array. The OSSL_PARAM array and all
56 associated storage must be freed by calling OSSL_PARAM_free() with the
57 functions return value. OSSL_PARAM_BLD_free() can safely be called any
58 time after this function is.
59 OSSL_PARAM_BLD_push_TYPE() are a series of functions which will create
61 OSSL_PARAM objects of the specified size and correct type for the val
62 argument. val is stored by value and an expression or auto variable
63 can be used.
64 OSSL_PARAM_BLD_push_BN() is a function that will create an OSSL_PARAM
66 object that holds the specified BIGNUM bn. If bn is marked as being
67 securely allocated, its OSSL_PARAM representation will also be securely
68 allocated. The bn argument is stored by reference and the underlying
69 BIGNUM object must exist until after OSSL_PARAM_BLD_to_param() has been
70 called.
71 OSSL_PARAM_BLD_push_BN_pad() is a function that will create an
73 OSSL_PARAM object that holds the specified BIGNUM bn. The object will
74 be padded to occupy exactly sz bytes, if insufficient space is
75 specified an error results. If bn is marked as being securely
76 allocated, its OSSL_PARAM representation will also be securely
77 allocated. The bn argument is stored by reference and the underlying
78 BIGNUM object must exist until after OSSL_PARAM_BLD_to_param() has been
79 called.
80 OSSL_PARAM_BLD_push_utf8_string() is a function that will create an
82 OSSL_PARAM object that references the UTF8 string specified by buf.
83 The length of the string bsize should not include the terminating NUL
84 byte. If it is zero then it will be calculated. The string that buf
85 points to is stored by reference and must remain in scope until after
86 OSSL_PARAM_BLD_to_param() has been called.
87 OSSL_PARAM_BLD_push_octet_string() is a function that will create an
89 OSSL_PARAM object that references the octet string specified by buf and
90 <bsize>. The memory that buf points to is stored by reference and must
91 remain in scope until after OSSL_PARAM_BLD_to_param() has been called.
92 OSSL_PARAM_BLD_push_utf8_ptr() is a function that will create an
94 OSSL_PARAM object that references the UTF8 string specified by buf.
95 The length of the string bsize should not include the terminating NUL
96 byte. If it is zero then it will be calculated. The string buf points
97 to is stored by reference and must remain in scope until the OSSL_PARAM
98 array is freed.
99 OSSL_PARAM_BLD_push_octet_ptr() is a function that will create an
101 OSSL_PARAM object that references the octet string specified by buf.
102 The memory buf points to is stored by reference and must remain in
103 scope until the OSSL_PARAM array is freed.
104
106 OSSL_PARAM_BLD_new() returns the allocated OSSL_PARAM_BLD structure, or
107 NULL on error.
108 OSSL_PARAM_BLD_to_param() returns the allocated OSSL_PARAM array, or
110 NULL on error.
111 All of the OSSL_PARAM_BLD_push_TYPE functions return 1 on success and 0
113 on error.
114
116 OSSL_PARAM_BLD_push_BN() and OSSL_PARAM_BLD_push_BN_pad() currently
117 only support nonnegative BIGNUMs. They return an error on negative
118 BIGNUMs.
119
121 Both examples creating an OSSL_PARAM array that contains an RSA key.
122 For both, the predefined key variables are:
123 BIGNUM *n; /* modulus */
125 unsigned int e; /* public exponent */
126 BIGNUM *d; /* private exponent */
127 BIGNUM *p, *q; /* first two prime factors */
128 BIGNUM *dmp1, *dmq1; /* first two CRT exponents */
129 BIGNUM *iqmp; /* first CRT coefficient */
130 Example 1
132 This example shows how to create an OSSL_PARAM array that contains an
133 RSA private key.
134 OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new();
136 OSSL_PARAM *params = NULL;
137 if (bld == NULL
139 || !OSSL_PARAM_BLD_push_BN(bld, "n", n)
140 || !OSSL_PARAM_BLD_push_uint(bld, "e", e)
141 || !OSSL_PARAM_BLD_push_BN(bld, "d", d)
142 || !OSSL_PARAM_BLD_push_BN(bld, "rsa-factor1", p)
143 || !OSSL_PARAM_BLD_push_BN(bld, "rsa-factor2", q)
144 || !OSSL_PARAM_BLD_push_BN(bld, "rsa-exponent1", dmp1)
145 || !OSSL_PARAM_BLD_push_BN(bld, "rsa-exponent2", dmq1)
146 || !OSSL_PARAM_BLD_push_BN(bld, "rsa-coefficient1", iqmp)
147 || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL)
148 goto err;
149 OSSL_PARAM_BLD_free(bld);
150 /* Use params */
151 ...
152 OSSL_PARAM_free(params);
153 Example 2
155 This example shows how to create an OSSL_PARAM array that contains an
156 RSA public key.
157 OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new();
159 OSSL_PARAM *params = NULL;
160 if (nld == NULL
162 || !OSSL_PARAM_BLD_push_BN(bld, "n", n)
163 || !OSSL_PARAM_BLD_push_uint(bld, "e", e)
164 || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL)
165 goto err;
166 OSSL_PARAM_BLD_free(bld);
167 /* Use params */
168 ...
169 OSSL_PARAM_free(params);
170
172 OSSL_PARAM_int(3), OSSL_PARAM(3), OSSL_PARAM_free(3)
173
175 The functions described here were all added in OpenSSL 3.0.
176
178 Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.
179 Licensed under the Apache License 2.0 (the "License"). You may not use
181 this file except in compliance with the License. You can obtain a copy
182 in the file LICENSE in the source distribution or at
183 <https://www.openssl.org/source/license.html>.
1843.1.1 2023-08-31 OSSL_PARAM_BLD(3ossl)