]>
Commit | Line | Data |
---|---|---|
1 | =pod | |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | OSSL_PARAM_BLD, OSSL_PARAM_BLD_new, OSSL_PARAM_BLD_to_param, | |
6 | OSSL_PARAM_BLD_free_params, OSSL_PARAM_BLD_free, OSSL_PARAM_BLD_push_int, | |
7 | OSSL_PARAM_BLD_push_uint, OSSL_PARAM_BLD_push_long, | |
8 | OSSL_PARAM_BLD_push_ulong, OSSL_PARAM_BLD_push_int32, | |
9 | OSSL_PARAM_BLD_push_uint32, OSSL_PARAM_BLD_push_int64, | |
10 | OSSL_PARAM_BLD_push_uint64, OSSL_PARAM_BLD_push_size_t, | |
11 | OSSL_PARAM_BLD_push_time_t, OSSL_PARAM_BLD_push_double, | |
12 | OSSL_PARAM_BLD_push_BN, OSSL_PARAM_BLD_push_BN_pad, | |
13 | OSSL_PARAM_BLD_push_utf8_string, OSSL_PARAM_BLD_push_utf8_ptr, | |
14 | OSSL_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_params(OSSL_PARAM *params); | |
28 | void OSSL_PARAM_BLD_free(OSSL_PARAM_BLD *bld); | |
29 | ||
30 | int OSSL_PARAM_BLD_push_TYPE(OSSL_PARAM_BLD *bld, const char *key, TYPE val); | |
31 | ||
32 | int OSSL_PARAM_BLD_push_BN(OSSL_PARAM_BLD *bld, const char *key, | |
33 | const BIGNUM *bn); | |
34 | int OSSL_PARAM_BLD_push_BN_pad(OSSL_PARAM_BLD *bld, const char *key, | |
35 | const BIGNUM *bn, size_t sz); | |
36 | ||
37 | int OSSL_PARAM_BLD_push_utf8_string(OSSL_PARAM_BLD *bld, const char *key, | |
38 | const char *buf, size_t bsize); | |
39 | int OSSL_PARAM_BLD_push_utf8_ptr(OSSL_PARAM_BLD *bld, const char *key, | |
40 | char *buf, size_t bsize); | |
41 | int OSSL_PARAM_BLD_push_octet_string(OSSL_PARAM_BLD *bld, const char *key, | |
42 | const void *buf, size_t bsize); | |
43 | int OSSL_PARAM_BLD_push_octet_ptr(OSSL_PARAM_BLD *bld, const char *key, | |
44 | void *buf, size_t bsize); | |
45 | ||
46 | ||
47 | =head1 DESCRIPTION | |
48 | ||
49 | A collection of utility functions that simplify the creation of OSSL_PARAM | |
50 | arrays. The B<I<TYPE>> names are as per L<OSSL_PARAM_int(3)>. | |
51 | ||
52 | OSSL_PARAM_BLD_new() allocates and initialises a new OSSL_PARAM_BLD structure | |
53 | so that values can be added. | |
54 | Any existing values are cleared. | |
55 | ||
56 | OSSL_PARAM_BLD_free() deallocates the memory allocates by OSSL_PARAM_BLD_new(). | |
57 | ||
58 | OSSL_PARAM_BLD_to_param() converts a built up OSSL_PARAM_BLD structure | |
59 | I<bld> into an allocated OSSL_PARAM array. | |
60 | The OSSL_PARAM array and all associated storage must be freed by calling | |
61 | OSSL_PARAM_BLD_free_params() with the functions return value. | |
62 | OSSL_PARAM_BLD_free() can safely be called any time after this function is. | |
63 | ||
64 | OSSL_PARAM_BLD_free_params() deallocates the memory allocated by | |
65 | OSSL_PARAM_BLD_to_param(). | |
66 | ||
67 | =begin comment | |
68 | ||
69 | POD is pretty good at recognising function names and making them appropriately | |
70 | bold... however, when part of the function name is variable, we have to help | |
71 | the processor along | |
72 | ||
73 | =end comment | |
74 | ||
75 | B<OSSL_PARAM_BLD_push_I<TYPE>>() are a series of functions which will create | |
76 | OSSL_PARAM objects of the specified size and correct type for the I<val> | |
77 | argument. | |
78 | I<val> is stored by value and an expression or auto variable can be used. | |
79 | ||
80 | OSSL_PARAM_BLD_push_BN() is a function that will create an OSSL_PARAM object | |
81 | that holds the specified BIGNUM I<bn>. | |
82 | If I<bn> is marked as being securely allocated, its OSSL_PARAM representation | |
83 | will also be securely allocated. | |
84 | The I<bn> argument is stored by reference and the underlying BIGNUM object | |
85 | must exist until after OSSL_PARAM_BLD_to_param() has been called. | |
86 | ||
87 | OSSL_PARAM_BLD_push_BN_pad() is a function that will create an OSSL_PARAM object | |
88 | that holds the specified BIGNUM I<bn>. | |
89 | The object will be padded to occupy exactly I<sz> bytes, if insufficient space | |
90 | is specified an error results. | |
91 | If I<bn> is marked as being securely allocated, its OSSL_PARAM representation | |
92 | will also be securely allocated. | |
93 | The I<bn> argument is stored by reference and the underlying BIGNUM object | |
94 | must exist until after OSSL_PARAM_BLD_to_param() has been called. | |
95 | ||
96 | OSSL_PARAM_BLD_push_utf8_string() is a function that will create an OSSL_PARAM | |
97 | object that references the UTF8 string specified by I<buf>. | |
98 | If the length of the string, I<bsize>, is zero then it will be calculated. | |
99 | The string that I<buf> points to is stored by reference and must remain in | |
100 | scope until after OSSL_PARAM_BLD_to_param() has been called. | |
101 | ||
102 | OSSL_PARAM_BLD_push_octet_string() is a function that will create an OSSL_PARAM | |
103 | object that references the octet string specified by I<buf> and <bsize>. | |
104 | The memory that I<buf> points to is stored by reference and must remain in | |
105 | scope until after OSSL_PARAM_BLD_to_param() has been called. | |
106 | ||
107 | OSSL_PARAM_BLD_push_utf8_ptr() is a function that will create an OSSL_PARAM | |
108 | object that references the UTF8 string specified by I<buf>. | |
109 | If the length of the string, I<bsize>, is zero then it will be calculated. | |
110 | The string I<buf> points to is stored by reference and must remain in | |
111 | scope until the OSSL_PARAM array is freed. | |
112 | ||
113 | OSSL_PARAM_BLD_push_octet_ptr() is a function that will create an OSSL_PARAM | |
114 | object that references the octet string specified by I<buf>. | |
115 | The memory I<buf> points to is stored by reference and must remain in | |
116 | scope until the OSSL_PARAM array is freed. | |
117 | ||
118 | =head1 RETURN VALUES | |
119 | ||
120 | OSSL_PARAM_BLD_new() returns the allocated OSSL_PARAM_BLD structure, or NULL | |
121 | on error. | |
122 | ||
123 | OSSL_PARAM_BLD_to_param() returns the allocated OSSL_PARAM array, or NULL | |
124 | on error. | |
125 | ||
126 | All of the OSSL_PARAM_BLD_push_TYPE functions return 1 on success and 0 | |
127 | on error. | |
128 | ||
129 | =head1 EXAMPLES | |
130 | ||
131 | Both examples creating an OSSL_PARAM array that contains an RSA key. | |
132 | For both, the predefined key variables are: | |
133 | ||
134 | BIGNUM *p, *q; /* both prime */ | |
135 | BIGNUM *n; /* = p * q */ | |
136 | unsigned int e; /* exponent, usually 65537 */ | |
137 | BIGNUM *d; /* e^-1 */ | |
138 | ||
139 | =head2 Example 1 | |
140 | ||
141 | This example shows how to create an OSSL_PARAM array that contains an RSA | |
142 | private key. | |
143 | ||
144 | OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new(); | |
145 | OSSL_PARAM *params; | |
146 | ||
147 | if (bld == NULL | |
148 | || !OSSL_PARAM_BLD_push_BN(&bld, "p", p) | |
149 | || !OSSL_PARAM_BLD_push_BN(&bld, "q", q) | |
150 | || !OSSL_PARAM_BLD_push_uint(&bld, "e", e) | |
151 | || !OSSL_PARAM_BLD_push_BN(&bld, "n", n) | |
152 | || !OSSL_PARAM_BLD_push_BN(&bld, "d", d) | |
153 | || (params = OSSL_PARAM_BLD_to_param(&bld)) == NULL) | |
154 | goto err; | |
155 | OSSL_PARAM_BLD_free(bld); | |
156 | /* Use params */ | |
157 | ... | |
158 | OSSL_PARAM_BLD_free_params(params); | |
159 | ||
160 | =head2 Example 2 | |
161 | ||
162 | This example shows how to create an OSSL_PARAM array that contains an RSA | |
163 | public key. | |
164 | ||
165 | OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new(); | |
166 | OSSL_PARAM *params; | |
167 | ||
168 | if (nld == NULL | |
169 | || !OSSL_PARAM_BLD_push_BN(bld, "n", n) | |
170 | || !OSSL_PARAM_BLD_push_BN(bld, "d", d) | |
171 | || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL) | |
172 | goto err; | |
173 | OSSL_PARAM_BLD_free(bld); | |
174 | /* Use params */ | |
175 | ... | |
176 | OSSL_PARAM_BLD_free_params(params); | |
177 | ||
178 | =head1 SEE ALSO | |
179 | ||
180 | L<OSSL_PARAM_int(3)>, L<OSSL_PARAM(3)> | |
181 | ||
182 | =head1 HISTORY | |
183 | ||
184 | The functions described here were all added in OpenSSL 3.0. | |
185 | ||
186 | =head1 COPYRIGHT | |
187 | ||
188 | Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. | |
189 | ||
190 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
191 | this file except in compliance with the License. You can obtain a copy | |
192 | in the file LICENSE in the source distribution or at | |
193 | L<https://www.openssl.org/source/license.html>. | |
194 | ||
195 | =cut |