]>
Commit | Line | Data |
---|---|---|
3c93fbac P |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
7312ef3f P |
5 | ossl_param_bld_init, ossl_param_bld_to_param, ossl_param_bld_to_param_ex, |
6 | ossl_param_bld_free, ossl_param_bld_push_int, ossl_param_bld_push_uint, | |
7 | ossl_param_bld_push_long, ossl_param_bld_push_ulong, | |
8 | ossl_param_bld_push_int32, ossl_param_bld_push_uint32, | |
9 | ossl_param_bld_push_int64, ossl_param_bld_push_uint64, | |
10 | ossl_param_bld_push_size_t, ossl_param_bld_push_double, | |
ac23078b P |
11 | ossl_param_bld_push_BN, ossl_param_bld_push_BN_pad, |
12 | ossl_param_bld_push_utf8_string, ossl_param_bld_push_utf8_ptr, | |
13 | ossl_param_bld_push_octet_string, ossl_param_bld_push_octet_ptr | |
3c93fbac P |
14 | - functions to assist in the creation of OSSL_PARAM arrays |
15 | ||
16 | =head1 SYNOPSIS | |
17 | ||
bb82531f | 18 | =for openssl generic |
3c93fbac | 19 | |
7312ef3f | 20 | #include "internal/params_build.h" |
3c93fbac P |
21 | |
22 | #define OSSL_PARAM_BLD_MAX 10 | |
23 | typedef struct { ... } OSSL_PARAM_BLD; | |
24 | ||
a1c5cefa | 25 | void ossl_param_bld_init(OSSL_PARAM_BLD *bld); |
7312ef3f | 26 | OSSL_PARAM *ossl_param_bld_to_param(OSSL_PARAM_BLD *bld); |
a1c5cefa | 27 | OSSL_PARAM *ossl_param_bld_to_param_ex(OSSL_PARAM_BLD *bld, |
3c93fbac P |
28 | OSSL_PARAM *params, size_t param_n, |
29 | void *data, size_t data_n, | |
30 | void *secure, size_t secure_n); | |
7312ef3f | 31 | void ossl_param_bld_free(OSSL_PARAM *params); |
3c93fbac | 32 | |
a1c5cefa | 33 | int ossl_param_bld_push_TYPE(OSSL_PARAM_BLD *bld, const char *key, TYPE val); |
3c93fbac | 34 | |
a1c5cefa | 35 | int ossl_param_bld_push_BN(OSSL_PARAM_BLD *bld, const char *key, |
3c93fbac | 36 | const BIGNUM *bn); |
ac23078b P |
37 | int ossl_param_bld_push_BN_pad(OSSL_PARAM_BLD *bld, const char *key, |
38 | const BIGNUM *bn, size_t sz); | |
3c93fbac | 39 | |
a1c5cefa | 40 | int ossl_param_bld_push_utf8_string(OSSL_PARAM_BLD *bld, const char *key, |
5fa7789f | 41 | const char *buf, size_t bsize); |
a1c5cefa | 42 | int ossl_param_bld_push_utf8_ptr(OSSL_PARAM_BLD *bld, const char *key, |
3c93fbac | 43 | char *buf, size_t bsize); |
a1c5cefa | 44 | int ossl_param_bld_push_octet_string(OSSL_PARAM_BLD *bld, const char *key, |
5fa7789f | 45 | const void *buf, size_t bsize); |
a1c5cefa | 46 | int ossl_param_bld_push_octet_ptr(OSSL_PARAM_BLD *bld, const char *key, |
3c93fbac P |
47 | void *buf, size_t bsize); |
48 | ||
49 | ||
50 | =head1 DESCRIPTION | |
51 | ||
52 | A collection of utility functions that simplify the creation of OSSL_PARAM | |
bbecf04e | 53 | arrays. The B<I<TYPE>> names are as per L<OSSL_PARAM_int(3)>. |
3c93fbac | 54 | |
a1c5cefa | 55 | ossl_param_bld_init() initialises the OSSL_PARAM_BLD structure so that values |
3c93fbac P |
56 | can be added. |
57 | Any existing values are cleared. | |
58 | ||
a1c5cefa | 59 | ossl_param_bld_to_param() converts a built up OSSL_PARAM_BLD structure |
dfabee82 | 60 | I<bld> into an allocated OSSL_PARAM array. |
7312ef3f P |
61 | The OSSL_PARAM array and all associated storage must be freed by calling |
62 | ossl_param_bld_free() with the functions return value. | |
63 | ||
64 | ossl_param_bld_free() deallocates the memory allocated by | |
65 | ossl_param_bld_to_param(). | |
3c93fbac | 66 | |
a1c5cefa | 67 | ossl_param_bld_to_param_ex() behaves like ossl_param_bld_to_param(), except that |
3c93fbac | 68 | no additional memory is allocated. |
dfabee82 | 69 | An OSSL_PARAM array of at least I<param_n> elements is passed in as I<params>. |
3c93fbac | 70 | The auxiliary storage for the parameters is a block of memory pointed to |
dfabee82 | 71 | by I<data> of at least I<data_n> bytes in size. |
3c93fbac | 72 | If required, secure memory for private BIGNUMs should be pointed to by |
dfabee82 | 73 | I<secure> of at least I<secure_n> bytes in size. |
3c93fbac | 74 | |
c18d2d94 RL |
75 | =begin comment |
76 | ||
77 | POD is pretty good at recognising function names and making them appropriately | |
78 | bold... however, when part of the function name is variable, we have to help | |
79 | the processor along | |
80 | ||
81 | =end comment | |
82 | ||
83 | B<ossl_param_bld_push_I<TYPE>>() are a series of functions which will create | |
dfabee82 | 84 | OSSL_PARAM objects of the specified size and correct type for the I<val> |
3c93fbac | 85 | argument. |
dfabee82 | 86 | I<val> is stored by value and an expression or auto variable can be used. |
3c93fbac | 87 | |
a1c5cefa | 88 | ossl_param_bld_push_BN() is a function that will create an OSSL_PARAM object |
dfabee82 RL |
89 | that holds the specified BIGNUM I<bn>. |
90 | If I<bn> is marked as being securely allocated, it's OSSL_PARAM representation | |
7312ef3f | 91 | will also be securely allocated. |
dfabee82 | 92 | The I<bn> argument is stored by reference and the underlying BIGNUM object |
a1c5cefa | 93 | must exist until after ossl_param_bld_to_param() has been called. |
3c93fbac | 94 | |
ac23078b P |
95 | ossl_param_bld_push_BN_pad() is a function that will create an OSSL_PARAM object |
96 | that holds the specified BIGNUM I<bn>. | |
97 | The object will be padded to occupy exactly I<sz> bytes, if insufficient space | |
98 | is specified an error results. | |
99 | If I<bn> is marked as being securely allocated, it's OSSL_PARAM representation | |
100 | will also be securely allocated. | |
101 | The I<bn> argument is stored by reference and the underlying BIGNUM object | |
102 | must exist until after ossl_param_bld_to_param() has been called. | |
103 | ||
a1c5cefa | 104 | ossl_param_bld_push_utf8_string() is a function that will create an OSSL_PARAM |
dfabee82 RL |
105 | object that references the UTF8 string specified by I<buf>. |
106 | If the length of the string, I<bsize>, is zero then it will be calculated. | |
107 | The string that I<buf> points to is stored by reference and must remain in | |
a1c5cefa | 108 | scope until after ossl_param_bld_to_param() has been called. |
3c93fbac | 109 | |
a1c5cefa | 110 | ossl_param_bld_push_octet_string() is a function that will create an OSSL_PARAM |
dfabee82 RL |
111 | object that references the octet string specified by I<buf> and <bsize>. |
112 | The memory that I<buf> points to is stored by reference and must remain in | |
a1c5cefa | 113 | scope until after ossl_param_bld_to_param() has been called. |
3c93fbac | 114 | |
a1c5cefa | 115 | ossl_param_bld_push_utf8_ptr() is a function that will create an OSSL_PARAM |
dfabee82 RL |
116 | object that references the UTF8 string specified by I<buf>. |
117 | If the length of the string, I<bsize>, is zero then it will be calculated. | |
118 | The string I<buf> points to is stored by reference and must remain in | |
3c93fbac P |
119 | scope until the OSSL_PARAM array is freed. |
120 | ||
a1c5cefa | 121 | ossl_param_bld_push_octet_ptr() is a function that will create an OSSL_PARAM |
dfabee82 RL |
122 | object that references the octet string specified by I<buf>. |
123 | The memory I<buf> points to is stored by reference and must remain in | |
3c93fbac P |
124 | scope until the OSSL_PARAM array is freed. |
125 | ||
126 | =head1 RETURN VALUES | |
127 | ||
a1c5cefa | 128 | ossl_param_bld_to_param() and ossl_param_bld_to_param_ex() return the |
3c93fbac P |
129 | allocated OSSL_PARAM array, or NULL on error. |
130 | ||
a1c5cefa | 131 | All of the ossl_param_bld_push_TYPE functions return 1 on success and 0 |
3c93fbac P |
132 | on error. |
133 | ||
134 | =head1 NOTES | |
135 | ||
136 | The constant B<OSSL_PARAM_BLD_MAX> specifies the maximum number of parameters | |
137 | that can be added. | |
138 | Exceeding this will result in the push functions returning errors. | |
139 | ||
140 | The structure B<OSSL_PARAM_BLD> should be considered opaque and subject to | |
141 | change between versions. | |
142 | ||
143 | =head1 EXAMPLES | |
144 | ||
145 | Both examples creating an OSSL_PARAM array that contains an RSA key. | |
146 | For both, the predefined key variables are: | |
147 | ||
148 | BIGNUM *p, *q; /* both prime */ | |
149 | BIGNUM *n; /* = p * q */ | |
150 | unsigned int e; /* exponent, usually 65537 */ | |
151 | BIGNUM *d; /* e^-1 */ | |
152 | ||
153 | =head2 Example 1 | |
154 | ||
155 | This example shows how to create an OSSL_PARAM array that contains an RSA | |
156 | private key. | |
157 | ||
158 | OSSL_PARAM_BLD bld; | |
159 | OSSL_PARAM *params; | |
3c93fbac | 160 | |
a1c5cefa RL |
161 | ossl_param_bld_init(&bld, &secure); |
162 | if (!ossl_param_bld_push_BN(&bld, "p", p) | |
163 | || !ossl_param_bld_push_BN(&bld, "q", q) | |
164 | || !ossl_param_bld_push_uint(&bld, "e", e) | |
165 | || !ossl_param_bld_push_BN(&bld, "n", n) | |
166 | || !ossl_param_bld_push_BN(&bld, "d", d) | |
167 | || (params = ossl_param_bld_to_param(&bld)) == NULL) | |
3c93fbac P |
168 | goto err; |
169 | /* Use params */ | |
170 | ... | |
7312ef3f | 171 | ossl_param_bld_free(params); |
3c93fbac P |
172 | |
173 | =head2 Example 2 | |
174 | ||
175 | This example shows how to create an OSSL_PARAM array that contains an RSA | |
176 | public key. | |
177 | ||
178 | OSSL_PARAM_BLD bld; | |
179 | OSSL_PARAM *params; | |
3c93fbac | 180 | |
a1c5cefa RL |
181 | ossl_param_bld_init(&bld, &secure); |
182 | if (!ossl_param_bld_push_BN(&bld, "n", n) | |
183 | || !ossl_param_bld_push_BN(&bld, "d", d) | |
184 | || (params = ossl_param_bld_to_param(&bld)) == NULL) | |
3c93fbac P |
185 | goto err; |
186 | /* Use params */ | |
187 | ... | |
7312ef3f | 188 | ossl_param_bld_free(params); |
3c93fbac P |
189 | |
190 | =head1 SEE ALSO | |
191 | ||
6e4618a0 | 192 | L<OSSL_PARAM_int(3)>, L<OSSL_PARAM(3)> |
3c93fbac P |
193 | |
194 | =head1 HISTORY | |
195 | ||
196 | The functions described here were all added in OpenSSL 3.0. | |
197 | ||
198 | =head1 COPYRIGHT | |
199 | ||
200 | Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. | |
201 | ||
202 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
203 | this file except in compliance with the License. You can obtain a copy | |
204 | in the file LICENSE in the source distribution or at | |
205 | L<https://www.openssl.org/source/license.html>. | |
206 | ||
207 | =cut |