]>
Commit | Line | Data |
---|---|---|
7ffbd7ca P |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
1313e37a P |
5 | OSSL_PARAM_double, OSSL_PARAM_int, OSSL_PARAM_int32, OSSL_PARAM_int64, |
6 | OSSL_PARAM_long, OSSL_PARAM_size_t, OSSL_PARAM_uint, OSSL_PARAM_uint32, | |
4e7991b4 | 7 | OSSL_PARAM_uint64, OSSL_PARAM_ulong, OSSL_PARAM_BN, OSSL_PARAM_utf8_string, |
1313e37a | 8 | OSSL_PARAM_octet_string, OSSL_PARAM_utf8_ptr, OSSL_PARAM_octet_ptr, |
4e7991b4 | 9 | OSSL_PARAM_END, OSSL_PARAM_construct_BN, OSSL_PARAM_construct_double, |
1313e37a P |
10 | OSSL_PARAM_construct_int, OSSL_PARAM_construct_int32, |
11 | OSSL_PARAM_construct_int64, OSSL_PARAM_construct_long, | |
12 | OSSL_PARAM_construct_size_t, OSSL_PARAM_construct_uint, | |
13 | OSSL_PARAM_construct_uint32, OSSL_PARAM_construct_uint64, | |
14 | OSSL_PARAM_construct_ulong, OSSL_PARAM_END, OSSL_PARAM_construct_BN, | |
15 | OSSL_PARAM_construct_utf8_string, OSSL_PARAM_construct_utf8_ptr, | |
16 | OSSL_PARAM_construct_octet_string, OSSL_PARAM_construct_octet_ptr, | |
4e7991b4 P |
17 | OSSL_PARAM_construct_end, OSSL_PARAM_locate, OSSL_PARAM_locate_const, |
18 | OSSL_PARAM_get_double, OSSL_PARAM_get_int, OSSL_PARAM_get_int32, | |
19 | OSSL_PARAM_get_int64, OSSL_PARAM_get_long, OSSL_PARAM_get_size_t, | |
20 | OSSL_PARAM_get_uint, OSSL_PARAM_get_uint32, OSSL_PARAM_get_uint64, | |
21 | OSSL_PARAM_get_ulong, OSSL_PARAM_set_double, OSSL_PARAM_set_int, | |
22 | OSSL_PARAM_set_int32, OSSL_PARAM_set_int64, OSSL_PARAM_set_long, | |
23 | OSSL_PARAM_set_size_t, OSSL_PARAM_set_uint, OSSL_PARAM_set_uint32, | |
24 | OSSL_PARAM_set_uint64, OSSL_PARAM_set_ulong, OSSL_PARAM_get_BN, | |
25 | OSSL_PARAM_set_BN, OSSL_PARAM_get_utf8_string, OSSL_PARAM_set_utf8_string, | |
7ffbd7ca P |
26 | OSSL_PARAM_get_octet_string, OSSL_PARAM_set_octet_string, |
27 | OSSL_PARAM_get_utf8_ptr, OSSL_PARAM_set_utf8_ptr, OSSL_PARAM_get_octet_ptr, | |
28 | OSSL_PARAM_set_octet_ptr | |
29 | - OSSL_PARAM helpers | |
30 | ||
31 | =head1 SYNOPSIS | |
32 | ||
1313e37a P |
33 | =for comment generic |
34 | ||
7ffbd7ca P |
35 | #include <openssl/params.h> |
36 | ||
37 | #define OSSL_PARAM_TYPE(key, address) | |
38 | #define OSSL_PARAM_utf8_string(key, address, size) | |
39 | #define OSSL_PARAM_octet_string(key, address, size) | |
40 | #define OSSL_PARAM_utf8_ptr(key, address, size) | |
41 | #define OSSL_PARAM_octet_ptr(key, address, size) | |
4e7991b4 | 42 | #define OSSL_PARAM_BN(key, address, size) |
7ffbd7ca P |
43 | #define OSSL_PARAM_END |
44 | ||
45 | OSSL_PARAM OSSL_PARAM_construct_TYPE(const char *key, TYPE *buf, size_t *ret); | |
46 | OSSL_PARAM OSSL_PARAM_construct_BN(const char *key, unsigned char *buf, | |
4e7991b4 | 47 | size_t bsize); |
7ffbd7ca | 48 | OSSL_PARAM OSSL_PARAM_construct_utf8_string(const char *key, char *buf, |
4e7991b4 | 49 | size_t bsize); |
7ffbd7ca | 50 | OSSL_PARAM OSSL_PARAM_construct_octet_string(const char *key, void *buf, |
4e7991b4 | 51 | size_t bsize); |
7ffbd7ca | 52 | OSSL_PARAM OSSL_PARAM_construct_utf8_ptr(const char *key, char **buf, |
4e7991b4 | 53 | size_t bsize); |
7ffbd7ca | 54 | OSSL_PARAM OSSL_PARAM_construct_octet_ptr(const char *key, void **buf, |
4e7991b4 | 55 | size_t bsize); |
195852fe | 56 | OSSL_PARAM OSSL_PARAM_construct_end(void); |
7ffbd7ca P |
57 | |
58 | OSSL_PARAM *OSSL_PARAM_locate(OSSL_PARAM *array, const char *key); | |
4e7991b4 P |
59 | const OSSL_PARAM *OSSL_PARAM_locate_const(const OSSL_PARAM *array, |
60 | const char *key); | |
7ffbd7ca P |
61 | |
62 | int OSSL_PARAM_get_TYPE(const OSSL_PARAM *p, const char *key, TYPE *val); | |
4e7991b4 | 63 | int OSSL_PARAM_set_TYPE(OSSL_PARAM *p, const char *key, TYPE val); |
7ffbd7ca P |
64 | |
65 | int OSSL_PARAM_get_BN(const OSSL_PARAM *p, const char *key, BIGNUM **val); | |
4e7991b4 | 66 | int OSSL_PARAM_set_BN(OSSL_PARAM *p, const char *key, const BIGNUM *val); |
7ffbd7ca P |
67 | |
68 | int OSSL_PARAM_get_utf8_string(const OSSL_PARAM *p, char **val, | |
69 | size_t max_len); | |
4e7991b4 | 70 | int OSSL_PARAM_set_utf8_string(OSSL_PARAM *p, const char *val); |
7ffbd7ca P |
71 | |
72 | int OSSL_PARAM_get_octet_string(const OSSL_PARAM *p, void **val, | |
73 | size_t max_len, size_t *used_len); | |
4e7991b4 | 74 | int OSSL_PARAM_set_octet_string(OSSL_PARAM *p, const void *val, size_t len); |
7ffbd7ca P |
75 | |
76 | int OSSL_PARAM_get_utf8_ptr(const OSSL_PARAM *p, char **val); | |
4e7991b4 | 77 | int OSSL_PARAM_set_utf8_ptr(OSSL_PARAM *p, char *val); |
7ffbd7ca P |
78 | |
79 | int OSSL_PARAM_get_octet_ptr(const OSSL_PARAM *p, void **val, | |
80 | size_t *used_len); | |
4e7991b4 | 81 | int OSSL_PARAM_set_octet_ptr(OSSL_PARAM *p, void *val, size_t used_len); |
7ffbd7ca P |
82 | |
83 | =head1 DESCRIPTION | |
84 | ||
85 | A collection of utility functions that simplify and add type safety to the | |
86 | OSSL_PARAM arrays. The following B<TYPE> names are supported: | |
87 | ||
88 | =over 1 | |
89 | ||
90 | =item * | |
91 | ||
92 | double | |
93 | ||
94 | =item * | |
95 | ||
96 | int | |
97 | ||
98 | =item * | |
99 | ||
100 | int32 (int32_t) | |
101 | ||
102 | =item * | |
103 | ||
104 | int64 (int64_t) | |
105 | ||
106 | =item * | |
107 | ||
108 | long int (long) | |
109 | ||
110 | =item * | |
111 | ||
112 | size_t | |
113 | ||
114 | =item * | |
115 | ||
116 | uint32 (uint32_t) | |
117 | ||
118 | =item * | |
119 | ||
120 | uint64 (uint64_t) | |
121 | ||
122 | =item * | |
123 | ||
124 | unsigned int (uint) | |
125 | ||
126 | =item * | |
127 | ||
128 | unsigned long int (ulong) | |
129 | ||
130 | =back | |
131 | ||
132 | OSSL_PARAM_TYPE() are a series of macros designed to assist initialising an | |
133 | array of OSSL_PARAM structures. | |
134 | Each of these macros defines a parameter of the specified B<TYPE> with the | |
135 | provided B<key> and parameter variable B<address>. | |
136 | ||
137 | OSSL_PARAM_utf8_string(), OSSL_PARAM_octet_string(), OSSL_PARAM_utf8_ptr(), | |
4e7991b4 P |
138 | OSSL_PARAM_octet_ptr(), OSSL_PARAM_BN() are macros that provide support |
139 | for defining UTF8 strings, OCTET strings and big numbers. | |
7ffbd7ca P |
140 | A parameter with name B<key> is defined. |
141 | The storage for this parameter is at B<address> and is of B<size> bytes. | |
142 | ||
7ffbd7ca P |
143 | OSSL_PARAM_END provides an end of parameter list marker. |
144 | This should terminate all OSSL_PARAM arrays. | |
145 | ||
146 | OSSL_PARAM_construct_TYPE() are a series of functions that create OSSL_PARAM | |
147 | records dynamically. | |
148 | A parameter with name B<key> is created. | |
149 | The parameter will use storage pointed to by B<buf> and return size of B<ret>. | |
150 | ||
151 | OSSL_PARAM_construct_BN() is a function that constructs a large integer | |
152 | OSSL_PARAM structure. | |
153 | A parameter with name B<key>, storage B<buf>, size B<bsize> and return | |
154 | size B<rsize> is created. | |
155 | ||
156 | OSSL_PARAM_construct_utf8_string() is a function that constructs a UTF8 | |
157 | string OSSL_PARAM structure. | |
158 | A parameter with name B<key>, storage B<buf>, size B<bsize> and return | |
159 | size B<rsize> is created. | |
160 | ||
161 | OSSL_PARAM_construct_octet_string() is a function that constructs an OCTET | |
162 | string OSSL_PARAM structure. | |
163 | A parameter with name B<key>, storage B<buf>, size B<bsize> and return | |
164 | size B<rsize> is created. | |
165 | ||
166 | OSSL_PARAM_construct_utf8_ptr() is a function that constructes a UTF string | |
167 | pointer OSSL_PARAM structure. | |
f55ed701 RL |
168 | A parameter with name B<key>, storage pointer B<*buf>, size B<bsize> and |
169 | return size B<rsize> is created. | |
7ffbd7ca P |
170 | |
171 | OSSL_PARAM_construct_octet_ptr() is a function that constructes an OCTET string | |
172 | pointer OSSL_PARAM structure. | |
f55ed701 RL |
173 | A parameter with name B<key>, storage pointer B<*buf>, size B<bsize> and |
174 | return size B<rsize> is created. | |
7ffbd7ca | 175 | |
195852fe RL |
176 | OSSL_PARAM_construct_end() is a function that constructs the terminating |
177 | OSSL_PARAM structure. | |
178 | ||
7ffbd7ca P |
179 | OSSL_PARAM_locate() is a function that searches an B<array> of parameters for |
180 | the one matching the B<key> name. | |
181 | ||
4e7991b4 P |
182 | OSSL_PARAM_locate_const() behaves exactly like OSSL_PARAM_locate() except for |
183 | the presence of I<const> for the B<array> argument and its return value. | |
184 | ||
7ffbd7ca P |
185 | OSSL_PARAM_get_TYPE() retrieves a value of type B<TYPE> from the parameter B<p>. |
186 | The value is copied to the address B<val>. | |
187 | Type coercion takes place as discussed in the NOTES section. | |
188 | ||
189 | OSSL_PARAM_set_TYPE() stores a value B<val> of type B<TYPE> into the paramter | |
190 | B<p>. | |
191 | Type coercion takes place as discussed in the NOTES section. | |
192 | ||
193 | OSSL_PARAM_get_BN() retrieves a BIGNUM from the parameter pointed to by B<p>. | |
194 | The BIGNUM referenced by B<val> is updated and is allocated if B<*val> is | |
195 | B<NULL>. | |
196 | ||
197 | OSSL_PARAM_set_BN() stores the BIGNUM B<val> into the paramater B<p>. | |
198 | ||
199 | OSSL_PARAM_get_utf8_string() retrieves a UTF8 string from the parameter | |
200 | pointed to by B<p>. | |
201 | The string is either stored into B<*val> with a length limit of B<max_len> or, | |
202 | in the case when B<*val> is B<NULL>, memory is allocated for the string and | |
203 | B<max_len> is ignored. | |
204 | If memory is allocated by this function, it must be freed by the caller. | |
205 | ||
206 | OSSL_PARAM_set_utf8_string() sets a UTF8 string from the parameter pointed to | |
207 | by B<p> to the value referenced by B<val>. | |
208 | ||
209 | OSSL_PARAM_get_octet_string() retrieves an OCTET string from the parameter | |
210 | pointed to by B<p>. | |
211 | The OCTETs are either stored into B<*val> with a length limit of B<max_len> or, | |
212 | in the case when B<*val> is B<NULL>, memory is allocated and | |
213 | B<max_len> is ignored. | |
214 | If memory is allocated by this function, it must be freed by the caller. | |
215 | ||
216 | OSSL_PARAM_set_octet_string() sets an OCTET string from the parameter | |
217 | pointed to by B<p> to the value referenced by B<val>. | |
218 | ||
219 | OSSL_PARAM_get_utf8_ptr() retrieves the UTF8 string pointer from the parameter | |
220 | referenced by B<p> and stores it in B<*val>. | |
221 | ||
222 | OSSL_PARAM_set_utf8_ptr() sets the UTF8 string pointer in the parameter | |
223 | referenced by B<p> to the values B<val>. | |
224 | ||
225 | OSSL_PARAM_get_octet_ptr() retrieves the OCTET string pointer from the parameter | |
226 | referenced by B<p> and stores it in B<*val>. | |
227 | The length of the OCTET string is stored in B<*used_len>. | |
228 | ||
229 | OSSL_PARAM_set_octet_ptr() sets the OCTET string pointer in the parameter | |
230 | referenced by B<p> to the values B<val>. | |
231 | The length of the OCTET string is provided by B<used_len>. | |
232 | ||
233 | =head1 RETURN VALUES | |
234 | ||
235 | OSSL_PARAM_construct_TYPE(), OSSL_PARAM_construct_BN(), | |
236 | OSSL_PARAM_construct_utf8_string(), OSSL_PARAM_construct_octet_string(), | |
237 | OSSL_PARAM_construct_utf8_ptr() and OSSL_PARAM_construct_octet_ptr() | |
238 | return a populated OSSL_PARAM structure. | |
239 | ||
4e7991b4 P |
240 | OSSL_PARAM_locate() and OSSL_PARAM_locate_const() return a pointer to |
241 | the matching OSSL_PARAM object. They return B<NULL> on error or when | |
242 | no object matching B<key> exists in the B<array>. | |
7ffbd7ca P |
243 | |
244 | All other functions return B<1> on success and B<0> on failure. | |
245 | ||
246 | =head1 NOTES | |
247 | ||
9830e7ea P |
248 | Native types will be converted as required only if the value is exactly |
249 | representable by the target type or parameter. | |
7ffbd7ca P |
250 | Apart from that, the functions must be used appropriately for the |
251 | expected type of the parameter. | |
252 | ||
f55ed701 RL |
253 | For OSSL_PARAM_get_utf8_ptr() and OSSL_PARAM_get_octet_ptr(), B<bsize> |
254 | is not relevant if the purpose is to send the B<OSSL_PARAM> array to a | |
255 | I<responder>, i.e. to get parameter data back. | |
256 | In that case, B<bsize> can safely be given zero. | |
257 | See L<OSSL_PARAM(3)/DESCRIPTION> for further information on the | |
258 | possible purposes. | |
259 | ||
7ffbd7ca P |
260 | =head1 EXAMPLES |
261 | ||
262 | Reusing the examples from L<OSSL_PARAM(3)> to just show how | |
263 | C<OSSL_PARAM> arrays can be handled using the macros and functions | |
264 | defined herein. | |
265 | ||
266 | =head2 Example 1 | |
267 | ||
268 | This example is for setting parameters on some object: | |
269 | ||
270 | #include <openssl/core.h> | |
271 | ||
272 | const char *foo = "some string"; | |
273 | size_t foo_l = strlen(foo) + 1; | |
274 | const char bar[] = "some other string"; | |
275 | const OSSL_PARAM set[] = { | |
276 | OSSL_PARAM_utf8_ptr("foo", foo, foo_l), | |
277 | OSSL_PARAM_utf8_string("bar", bar, sizeof(bar)), | |
278 | OSSL_PARAM_END | |
279 | }; | |
280 | ||
281 | =head2 Example 2 | |
282 | ||
16bfe6ce RL |
283 | This example is for requesting parameters on some object, and also |
284 | demonstrates that the requestor isn't obligated to request all | |
285 | available parameters: | |
7ffbd7ca P |
286 | |
287 | const char *foo = NULL; | |
7ffbd7ca | 288 | char bar[1024]; |
4e7991b4 P |
289 | OSSL_PARAM request[] = { |
290 | OSSL_PARAM_utf8_ptr("foo", foo, 0), | |
291 | OSSL_PARAM_utf8_string("bar", bar, sizeof(bar)), | |
7ffbd7ca P |
292 | OSSL_PARAM_END |
293 | }; | |
294 | ||
295 | A I<responder> that receives this array (as C<params> in this example) | |
296 | could fill in the parameters like this: | |
297 | ||
4e7991b4 | 298 | /* OSSL_PARAM *params */ |
7ffbd7ca | 299 | |
4e7991b4 | 300 | OSSL_PARAM *p; |
16bfe6ce RL |
301 | |
302 | if ((p = OSSL_PARAM_locate(params, "foo")) == NULL) | |
303 | OSSL_PARAM_set_utf8_ptr(p, "foo value"); | |
304 | if ((p = OSSL_PARAM_locate(params, "bar")) == NULL) | |
305 | OSSL_PARAM_set_utf8_ptr(p, "bar value"); | |
306 | if ((p = OSSL_PARAM_locate(params, "cookie")) == NULL) | |
307 | OSSL_PARAM_set_utf8_ptr(p, "cookie value"); | |
7ffbd7ca P |
308 | |
309 | =head1 SEE ALSO | |
310 | ||
311 | L<openssl-core.h(7)>, L<OSSL_PARAM(3)> | |
312 | ||
313 | =head1 HISTORY | |
314 | ||
315 | These APIs were introduced in OpenSSL 3.0.0. | |
316 | ||
317 | =head1 COPYRIGHT | |
318 | ||
319 | Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. | |
320 | ||
321 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
322 | this file except in compliance with the License. You can obtain a copy | |
323 | in the file LICENSE in the source distribution or at | |
324 | L<https://www.openssl.org/source/license.html>. | |
325 | ||
326 | =cut |