]>
Commit | Line | Data |
---|---|---|
7ffbd7ca P |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
1313e37a | 5 | OSSL_PARAM_double, OSSL_PARAM_int, OSSL_PARAM_int32, OSSL_PARAM_int64, |
dc4e74ef P |
6 | OSSL_PARAM_long, OSSL_PARAM_size_t, OSSL_PARAM_time_t, OSSL_PARAM_uint, |
7 | OSSL_PARAM_uint32, OSSL_PARAM_uint64, OSSL_PARAM_ulong, OSSL_PARAM_BN, | |
8 | OSSL_PARAM_utf8_string, OSSL_PARAM_octet_string, OSSL_PARAM_utf8_ptr, | |
9 | OSSL_PARAM_octet_ptr, | |
510d0191 | 10 | OSSL_PARAM_END, OSSL_PARAM_DEFN, |
a1c5cefa RL |
11 | OSSL_PARAM_construct_double, OSSL_PARAM_construct_int, |
12 | OSSL_PARAM_construct_int32, OSSL_PARAM_construct_int64, | |
dc4e74ef P |
13 | OSSL_PARAM_construct_long, OSSL_PARAM_construct_size_t, |
14 | OSSL_PARAM_construct_time_t, OSSL_PARAM_construct_uint, | |
15 | OSSL_PARAM_construct_uint32, OSSL_PARAM_construct_uint64, | |
16 | OSSL_PARAM_construct_ulong, OSSL_PARAM_construct_BN, | |
17 | OSSL_PARAM_construct_utf8_string, OSSL_PARAM_construct_utf8_ptr, | |
18 | OSSL_PARAM_construct_octet_string, OSSL_PARAM_construct_octet_ptr, | |
19 | OSSL_PARAM_construct_end, | |
a1c5cefa | 20 | OSSL_PARAM_locate, OSSL_PARAM_locate_const, |
4e7991b4 | 21 | OSSL_PARAM_get_double, OSSL_PARAM_get_int, OSSL_PARAM_get_int32, |
dc4e74ef P |
22 | OSSL_PARAM_get_int64, OSSL_PARAM_get_long, OSSL_PARAM_get_size_t, |
23 | OSSL_PARAM_get_time_t, OSSL_PARAM_get_uint, OSSL_PARAM_get_uint32, | |
24 | OSSL_PARAM_get_uint64, OSSL_PARAM_get_ulong, OSSL_PARAM_get_BN, | |
25 | OSSL_PARAM_get_utf8_string, OSSL_PARAM_get_octet_string, | |
26 | OSSL_PARAM_get_utf8_ptr, OSSL_PARAM_get_octet_ptr, | |
ab00ddb5 | 27 | OSSL_PARAM_get_utf8_string_ptr, OSSL_PARAM_get_octet_string_ptr, |
a1c5cefa | 28 | OSSL_PARAM_set_double, OSSL_PARAM_set_int, OSSL_PARAM_set_int32, |
dc4e74ef P |
29 | OSSL_PARAM_set_int64, OSSL_PARAM_set_long, OSSL_PARAM_set_size_t, |
30 | OSSL_PARAM_set_time_t, OSSL_PARAM_set_uint, OSSL_PARAM_set_uint32, | |
31 | OSSL_PARAM_set_uint64, OSSL_PARAM_set_ulong, OSSL_PARAM_set_BN, | |
32 | OSSL_PARAM_set_utf8_string, OSSL_PARAM_set_octet_string, | |
33 | OSSL_PARAM_set_utf8_ptr, OSSL_PARAM_set_octet_ptr, | |
760aaf1b | 34 | OSSL_PARAM_UNMODIFIED, OSSL_PARAM_modified, OSSL_PARAM_set_all_unmodified |
7ffbd7ca P |
35 | - OSSL_PARAM helpers |
36 | ||
37 | =head1 SYNOPSIS | |
38 | ||
bb82531f | 39 | =for openssl generic |
1313e37a | 40 | |
7ffbd7ca P |
41 | #include <openssl/params.h> |
42 | ||
a1c5cefa RL |
43 | /* |
44 | * TYPE in function names is one of: | |
5fdaa38f | 45 | * double, int, int32, int64, long, size_t, time_t, uint, uint32, uint64, ulong |
a1c5cefa | 46 | * Corresponding TYPE in function arguments is one of: |
5fdaa38f | 47 | * double, int, int32_t, int64_t, long, size_t, time_t, unsigned int, uint32_t, |
a1c5cefa RL |
48 | * uint64_t, unsigned long |
49 | */ | |
50 | ||
7ffbd7ca | 51 | #define OSSL_PARAM_TYPE(key, address) |
a1c5cefa | 52 | #define OSSL_PARAM_BN(key, address, size) |
7ffbd7ca P |
53 | #define OSSL_PARAM_utf8_string(key, address, size) |
54 | #define OSSL_PARAM_octet_string(key, address, size) | |
55 | #define OSSL_PARAM_utf8_ptr(key, address, size) | |
56 | #define OSSL_PARAM_octet_ptr(key, address, size) | |
7ffbd7ca P |
57 | #define OSSL_PARAM_END |
58 | ||
8d5fb648 P |
59 | #define OSSL_PARAM_UNMODIFIED |
60 | ||
510d0191 MC |
61 | #define OSSL_PARAM_DEFN(key, type, addr, sz) \ |
62 | { (key), (type), (addr), (sz), OSSL_PARAM_UNMODIFIED } | |
63 | ||
a1c5cefa | 64 | OSSL_PARAM OSSL_PARAM_construct_TYPE(const char *key, TYPE *buf); |
7ffbd7ca | 65 | OSSL_PARAM OSSL_PARAM_construct_BN(const char *key, unsigned char *buf, |
4e7991b4 | 66 | size_t bsize); |
7ffbd7ca | 67 | OSSL_PARAM OSSL_PARAM_construct_utf8_string(const char *key, char *buf, |
4e7991b4 | 68 | size_t bsize); |
7ffbd7ca | 69 | OSSL_PARAM OSSL_PARAM_construct_octet_string(const char *key, void *buf, |
4e7991b4 | 70 | size_t bsize); |
7ffbd7ca | 71 | OSSL_PARAM OSSL_PARAM_construct_utf8_ptr(const char *key, char **buf, |
4e7991b4 | 72 | size_t bsize); |
7ffbd7ca | 73 | OSSL_PARAM OSSL_PARAM_construct_octet_ptr(const char *key, void **buf, |
4e7991b4 | 74 | size_t bsize); |
195852fe | 75 | OSSL_PARAM OSSL_PARAM_construct_end(void); |
7ffbd7ca P |
76 | |
77 | OSSL_PARAM *OSSL_PARAM_locate(OSSL_PARAM *array, const char *key); | |
4e7991b4 P |
78 | const OSSL_PARAM *OSSL_PARAM_locate_const(const OSSL_PARAM *array, |
79 | const char *key); | |
7ffbd7ca | 80 | |
a1c5cefa RL |
81 | int OSSL_PARAM_get_TYPE(const OSSL_PARAM *p, TYPE *val); |
82 | int OSSL_PARAM_set_TYPE(OSSL_PARAM *p, TYPE val); | |
7ffbd7ca | 83 | |
a1c5cefa RL |
84 | int OSSL_PARAM_get_BN(const OSSL_PARAM *p, BIGNUM **val); |
85 | int OSSL_PARAM_set_BN(OSSL_PARAM *p, const BIGNUM *val); | |
7ffbd7ca P |
86 | |
87 | int OSSL_PARAM_get_utf8_string(const OSSL_PARAM *p, char **val, | |
88 | size_t max_len); | |
4e7991b4 | 89 | int OSSL_PARAM_set_utf8_string(OSSL_PARAM *p, const char *val); |
7ffbd7ca P |
90 | |
91 | int OSSL_PARAM_get_octet_string(const OSSL_PARAM *p, void **val, | |
92 | size_t max_len, size_t *used_len); | |
4e7991b4 | 93 | int OSSL_PARAM_set_octet_string(OSSL_PARAM *p, const void *val, size_t len); |
7ffbd7ca | 94 | |
a1c5cefa RL |
95 | int OSSL_PARAM_get_utf8_ptr(const OSSL_PARAM *p, const char **val); |
96 | int OSSL_PARAM_set_utf8_ptr(OSSL_PARAM *p, const char *val); | |
7ffbd7ca | 97 | |
a1c5cefa | 98 | int OSSL_PARAM_get_octet_ptr(const OSSL_PARAM *p, const void **val, |
7ffbd7ca | 99 | size_t *used_len); |
a1c5cefa RL |
100 | int OSSL_PARAM_set_octet_ptr(OSSL_PARAM *p, const void *val, |
101 | size_t used_len); | |
7ffbd7ca | 102 | |
ab00ddb5 RL |
103 | int OSSL_PARAM_get_utf8_string_ptr(const OSSL_PARAM *p, const char **val); |
104 | int OSSL_PARAM_get_octet_string_ptr(const OSSL_PARAM *p, const void **val, | |
105 | size_t *used_len); | |
106 | ||
3873887e P |
107 | int OSSL_PARAM_modified(const OSSL_PARAM *param); |
108 | void OSSL_PARAM_set_all_unmodified(OSSL_PARAM *params); | |
8d5fb648 | 109 | |
7ffbd7ca P |
110 | =head1 DESCRIPTION |
111 | ||
112 | A collection of utility functions that simplify and add type safety to the | |
318a9dfa | 113 | L<OSSL_PARAM(3)> arrays. The following B<I<TYPE>> names are supported: |
7ffbd7ca P |
114 | |
115 | =over 1 | |
116 | ||
117 | =item * | |
118 | ||
119 | double | |
120 | ||
121 | =item * | |
122 | ||
123 | int | |
124 | ||
125 | =item * | |
126 | ||
127 | int32 (int32_t) | |
128 | ||
129 | =item * | |
130 | ||
131 | int64 (int64_t) | |
132 | ||
133 | =item * | |
134 | ||
135 | long int (long) | |
136 | ||
137 | =item * | |
138 | ||
5fdaa38f P |
139 | time_t |
140 | ||
141 | =item * | |
142 | ||
7ffbd7ca P |
143 | size_t |
144 | ||
145 | =item * | |
146 | ||
147 | uint32 (uint32_t) | |
148 | ||
149 | =item * | |
150 | ||
151 | uint64 (uint64_t) | |
152 | ||
153 | =item * | |
154 | ||
155 | unsigned int (uint) | |
156 | ||
157 | =item * | |
158 | ||
159 | unsigned long int (ulong) | |
160 | ||
161 | =back | |
162 | ||
163 | OSSL_PARAM_TYPE() are a series of macros designed to assist initialising an | |
318a9dfa | 164 | array of L<OSSL_PARAM(3)> structures. |
b91f41da RL |
165 | Each of these macros defines a parameter of the specified B<I<TYPE>> with the |
166 | provided I<key> and parameter variable I<address>. | |
7ffbd7ca P |
167 | |
168 | OSSL_PARAM_utf8_string(), OSSL_PARAM_octet_string(), OSSL_PARAM_utf8_ptr(), | |
4e7991b4 P |
169 | OSSL_PARAM_octet_ptr(), OSSL_PARAM_BN() are macros that provide support |
170 | for defining UTF8 strings, OCTET strings and big numbers. | |
b91f41da RL |
171 | A parameter with name I<key> is defined. |
172 | The storage for this parameter is at I<address> and is of I<size> bytes. | |
7ffbd7ca | 173 | |
7ffbd7ca | 174 | OSSL_PARAM_END provides an end of parameter list marker. |
318a9dfa | 175 | This should terminate all L<OSSL_PARAM(3)> arrays. |
510d0191 MC |
176 | |
177 | The OSSL_PARAM_DEFN() macro provides the ability to construct a single | |
318a9dfa | 178 | L<OSSL_PARAM(3)> (typically used in the construction of B<OSSL_PARAM> arrays). The |
510d0191 | 179 | I<key>, I<type>, I<addr> and I<sz> arguments correspond to the I<key>, |
318a9dfa | 180 | I<data_type>, I<data> and I<data_size> fields of the L<OSSL_PARAM(3)> structure as |
510d0191 | 181 | described on the L<OSSL_PARAM(3)> page. |
7ffbd7ca | 182 | |
318a9dfa | 183 | OSSL_PARAM_construct_TYPE() are a series of functions that create L<OSSL_PARAM(3)> |
7ffbd7ca | 184 | records dynamically. |
b91f41da RL |
185 | A parameter with name I<key> is created. |
186 | The parameter will use storage pointed to by I<buf> and return size of I<ret>. | |
7ffbd7ca P |
187 | |
188 | OSSL_PARAM_construct_BN() is a function that constructs a large integer | |
318a9dfa | 189 | L<OSSL_PARAM(3)> structure. |
b91f41da RL |
190 | A parameter with name I<key>, storage I<buf>, size I<bsize> and return |
191 | size I<rsize> is created. | |
7ffbd7ca P |
192 | |
193 | OSSL_PARAM_construct_utf8_string() is a function that constructs a UTF8 | |
318a9dfa | 194 | string L<OSSL_PARAM(3)> structure. |
b91f41da | 195 | A parameter with name I<key>, storage I<buf> and size I<bsize> is created. |
247a1786 | 196 | If I<bsize> is zero, the string length is determined using strlen(3). |
b91f41da | 197 | Generally pass zero for I<bsize> instead of calling strlen(3) yourself. |
7ffbd7ca P |
198 | |
199 | OSSL_PARAM_construct_octet_string() is a function that constructs an OCTET | |
318a9dfa | 200 | string L<OSSL_PARAM(3)> structure. |
b91f41da | 201 | A parameter with name I<key>, storage I<buf> and size I<bsize> is created. |
7ffbd7ca | 202 | |
4ccad357 | 203 | OSSL_PARAM_construct_utf8_ptr() is a function that constructs a UTF8 string |
318a9dfa | 204 | pointer L<OSSL_PARAM(3)> structure. |
b91f41da | 205 | A parameter with name I<key>, storage pointer I<*buf> and size I<bsize> |
7f588d20 | 206 | is created. |
7ffbd7ca | 207 | |
8c1cbc72 | 208 | OSSL_PARAM_construct_octet_ptr() is a function that constructs an OCTET string |
318a9dfa | 209 | pointer L<OSSL_PARAM(3)> structure. |
b91f41da | 210 | A parameter with name I<key>, storage pointer I<*buf> and size I<bsize> |
7f588d20 | 211 | is created. |
7ffbd7ca | 212 | |
195852fe | 213 | OSSL_PARAM_construct_end() is a function that constructs the terminating |
318a9dfa | 214 | L<OSSL_PARAM(3)> structure. |
195852fe | 215 | |
b91f41da RL |
216 | OSSL_PARAM_locate() is a function that searches an I<array> of parameters for |
217 | the one matching the I<key> name. | |
7ffbd7ca | 218 | |
4e7991b4 | 219 | OSSL_PARAM_locate_const() behaves exactly like OSSL_PARAM_locate() except for |
b91f41da | 220 | the presence of I<const> for the I<array> argument and its return value. |
4e7991b4 | 221 | |
b91f41da RL |
222 | OSSL_PARAM_get_TYPE() retrieves a value of type B<I<TYPE>> from the parameter |
223 | I<p>. | |
224 | The value is copied to the address I<val>. | |
7ffbd7ca P |
225 | Type coercion takes place as discussed in the NOTES section. |
226 | ||
b91f41da RL |
227 | OSSL_PARAM_set_TYPE() stores a value I<val> of type B<I<TYPE>> into the |
228 | parameter I<p>. | |
8f3b8fd6 RL |
229 | If the parameter's I<data> field is NULL, then only its I<return_size> field |
230 | will be assigned the size the parameter's I<data> buffer should have. | |
7ffbd7ca P |
231 | Type coercion takes place as discussed in the NOTES section. |
232 | ||
b91f41da RL |
233 | OSSL_PARAM_get_BN() retrieves a BIGNUM from the parameter pointed to by I<p>. |
234 | The BIGNUM referenced by I<val> is updated and is allocated if I<*val> is | |
235 | NULL. | |
7ffbd7ca | 236 | |
b91f41da | 237 | OSSL_PARAM_set_BN() stores the BIGNUM I<val> into the parameter I<p>. |
8f3b8fd6 RL |
238 | If the parameter's I<data> field is NULL, then only its I<return_size> field |
239 | will be assigned the size the parameter's I<data> buffer should have. | |
7ffbd7ca P |
240 | |
241 | OSSL_PARAM_get_utf8_string() retrieves a UTF8 string from the parameter | |
b91f41da | 242 | pointed to by I<p>. |
247a1786 | 243 | The string is stored into I<*val> with a size limit of I<max_len>, |
e304aa87 | 244 | which must be large enough to accommodate a terminating NUL byte, |
43cf27c9 | 245 | otherwise this function will fail. |
4ccad357 TM |
246 | If I<*val> is NULL, memory is allocated for the string (including the |
247 | terminating NUL byte) and I<max_len> is ignored. | |
7ffbd7ca P |
248 | If memory is allocated by this function, it must be freed by the caller. |
249 | ||
250 | OSSL_PARAM_set_utf8_string() sets a UTF8 string from the parameter pointed to | |
b91f41da | 251 | by I<p> to the value referenced by I<val>. |
43cf27c9 | 252 | If the parameter's I<data> field isn't NULL, its I<data_size> must indicate |
e304aa87 | 253 | that the buffer is large enough to accommodate the string that I<val> points at, |
43cf27c9 RL |
254 | not including the terminating NUL byte, or this function will fail. |
255 | A terminating NUL byte is added only if the parameter's I<data_size> indicates | |
256 | the buffer is longer than the string length, otherwise the string will not be | |
257 | NUL terminated. | |
8f3b8fd6 | 258 | If the parameter's I<data> field is NULL, then only its I<return_size> field |
247a1786 | 259 | will be assigned the minimum size the parameter's I<data> buffer should have |
e304aa87 | 260 | to accommodate the string, not including a terminating NUL byte. |
7ffbd7ca P |
261 | |
262 | OSSL_PARAM_get_octet_string() retrieves an OCTET string from the parameter | |
b91f41da RL |
263 | pointed to by I<p>. |
264 | The OCTETs are either stored into I<*val> with a length limit of I<max_len> or, | |
265 | in the case when I<*val> is NULL, memory is allocated and | |
266 | I<max_len> is ignored. I<*used_len> is populated with the number of OCTETs | |
267 | stored. If I<val> is NULL then the OCTETS are not stored, but I<*used_len> is | |
b756626a | 268 | still populated. |
7ffbd7ca P |
269 | If memory is allocated by this function, it must be freed by the caller. |
270 | ||
271 | OSSL_PARAM_set_octet_string() sets an OCTET string from the parameter | |
b91f41da | 272 | pointed to by I<p> to the value referenced by I<val>. |
8f3b8fd6 RL |
273 | If the parameter's I<data> field is NULL, then only its I<return_size> field |
274 | will be assigned the size the parameter's I<data> buffer should have. | |
7ffbd7ca P |
275 | |
276 | OSSL_PARAM_get_utf8_ptr() retrieves the UTF8 string pointer from the parameter | |
b91f41da | 277 | referenced by I<p> and stores it in I<*val>. |
7ffbd7ca P |
278 | |
279 | OSSL_PARAM_set_utf8_ptr() sets the UTF8 string pointer in the parameter | |
b91f41da | 280 | referenced by I<p> to the values I<val>. |
7ffbd7ca P |
281 | |
282 | OSSL_PARAM_get_octet_ptr() retrieves the OCTET string pointer from the parameter | |
b91f41da RL |
283 | referenced by I<p> and stores it in I<*val>. |
284 | The length of the OCTET string is stored in I<*used_len>. | |
7ffbd7ca P |
285 | |
286 | OSSL_PARAM_set_octet_ptr() sets the OCTET string pointer in the parameter | |
b91f41da RL |
287 | referenced by I<p> to the values I<val>. |
288 | The length of the OCTET string is provided by I<used_len>. | |
7ffbd7ca | 289 | |
ab00ddb5 | 290 | OSSL_PARAM_get_utf8_string_ptr() retrieves the pointer to a UTF8 string from |
b91f41da | 291 | the parameter pointed to by I<p>, and stores that pointer in I<*val>. |
ab00ddb5 RL |
292 | This is different from OSSL_PARAM_get_utf8_string(), which copies the |
293 | string. | |
294 | ||
295 | OSSL_PARAM_get_octet_string_ptr() retrieves the pointer to a octet string | |
b91f41da RL |
296 | from the parameter pointed to by I<p>, and stores that pointer in I<*val>, |
297 | along with the string's length in I<*used_len>. | |
ab00ddb5 RL |
298 | This is different from OSSL_PARAM_get_octet_string(), which copies the |
299 | string. | |
300 | ||
8d5fb648 P |
301 | The OSSL_PARAM_UNMODIFIED macro is used to detect if a parameter was set. On |
302 | creation, via either the macros or construct calls, the I<return_size> field | |
303 | is set to this. If the parameter is set using the calls defined herein, the | |
304 | I<return_size> field is changed. | |
305 | ||
b91f41da | 306 | OSSL_PARAM_modified() queries if the parameter I<param> has been set or not |
3873887e | 307 | using the calls defined herein. |
8d5fb648 | 308 | |
3873887e | 309 | OSSL_PARAM_set_all_unmodified() resets the unused indicator for all parameters |
b91f41da | 310 | in the array I<params>. |
8d5fb648 | 311 | |
7ffbd7ca P |
312 | =head1 RETURN VALUES |
313 | ||
314 | OSSL_PARAM_construct_TYPE(), OSSL_PARAM_construct_BN(), | |
315 | OSSL_PARAM_construct_utf8_string(), OSSL_PARAM_construct_octet_string(), | |
316 | OSSL_PARAM_construct_utf8_ptr() and OSSL_PARAM_construct_octet_ptr() | |
318a9dfa | 317 | return a populated L<OSSL_PARAM(3)> structure. |
7ffbd7ca | 318 | |
4e7991b4 | 319 | OSSL_PARAM_locate() and OSSL_PARAM_locate_const() return a pointer to |
318a9dfa | 320 | the matching L<OSSL_PARAM(3)> object. They return NULL on error or when |
b91f41da | 321 | no object matching I<key> exists in the I<array>. |
7ffbd7ca | 322 | |
b91f41da | 323 | OSSL_PARAM_modified() returns 1 if the parameter was set and 0 otherwise. |
8d5fb648 | 324 | |
b91f41da | 325 | All other functions return 1 on success and 0 on failure. |
7ffbd7ca P |
326 | |
327 | =head1 NOTES | |
328 | ||
9830e7ea P |
329 | Native types will be converted as required only if the value is exactly |
330 | representable by the target type or parameter. | |
7ffbd7ca P |
331 | Apart from that, the functions must be used appropriately for the |
332 | expected type of the parameter. | |
333 | ||
f1719858 RL |
334 | OSSL_PARAM_get_BN() and OSSL_PARAM_set_BN() only support nonnegative |
335 | B<BIGNUM>s when the desired data type is B<OSSL_PARAM_UNSIGNED_INTEGER>. | |
318a9dfa | 336 | OSSL_PARAM_construct_BN() currently constructs an L<OSSL_PARAM(3)> structure |
f1719858 | 337 | with the data type B<OSSL_PARAM_UNSIGNED_INTEGER>. |
b33fb68a | 338 | |
8f3b8fd6 | 339 | For OSSL_PARAM_construct_utf8_ptr() and OSSL_PARAM_consstruct_octet_ptr(), |
318a9dfa | 340 | I<bsize> is not relevant if the purpose is to send the L<OSSL_PARAM(3)> array |
8f3b8fd6 | 341 | to a I<responder>, i.e. to get parameter data back. |
b91f41da | 342 | In that case, I<bsize> can safely be given zero. |
f55ed701 RL |
343 | See L<OSSL_PARAM(3)/DESCRIPTION> for further information on the |
344 | possible purposes. | |
345 | ||
7ffbd7ca P |
346 | =head1 EXAMPLES |
347 | ||
348 | Reusing the examples from L<OSSL_PARAM(3)> to just show how | |
318a9dfa | 349 | L<OSSL_PARAM(3)> arrays can be handled using the macros and functions |
7ffbd7ca P |
350 | defined herein. |
351 | ||
352 | =head2 Example 1 | |
353 | ||
354 | This example is for setting parameters on some object: | |
355 | ||
356 | #include <openssl/core.h> | |
357 | ||
358 | const char *foo = "some string"; | |
247a1786 | 359 | size_t foo_l = strlen(foo); |
7ffbd7ca P |
360 | const char bar[] = "some other string"; |
361 | const OSSL_PARAM set[] = { | |
1395a84e | 362 | OSSL_PARAM_utf8_ptr("foo", &foo, foo_l), |
247a1786 | 363 | OSSL_PARAM_utf8_string("bar", bar, sizeof(bar) - 1), |
7ffbd7ca P |
364 | OSSL_PARAM_END |
365 | }; | |
366 | ||
367 | =head2 Example 2 | |
368 | ||
16bfe6ce | 369 | This example is for requesting parameters on some object, and also |
9a271795 | 370 | demonstrates that the requester isn't obligated to request all |
16bfe6ce | 371 | available parameters: |
7ffbd7ca P |
372 | |
373 | const char *foo = NULL; | |
7ffbd7ca | 374 | char bar[1024]; |
4e7991b4 | 375 | OSSL_PARAM request[] = { |
1395a84e | 376 | OSSL_PARAM_utf8_ptr("foo", &foo, 0), |
4e7991b4 | 377 | OSSL_PARAM_utf8_string("bar", bar, sizeof(bar)), |
7ffbd7ca P |
378 | OSSL_PARAM_END |
379 | }; | |
380 | ||
381 | A I<responder> that receives this array (as C<params> in this example) | |
382 | could fill in the parameters like this: | |
383 | ||
4e7991b4 | 384 | /* OSSL_PARAM *params */ |
7ffbd7ca | 385 | |
4e7991b4 | 386 | OSSL_PARAM *p; |
16bfe6ce | 387 | |
3800cc6f | 388 | if ((p = OSSL_PARAM_locate(params, "foo")) != NULL) |
16bfe6ce | 389 | OSSL_PARAM_set_utf8_ptr(p, "foo value"); |
3800cc6f | 390 | if ((p = OSSL_PARAM_locate(params, "bar")) != NULL) |
247a1786 | 391 | OSSL_PARAM_set_utf8_string(p, "bar value"); |
3800cc6f | 392 | if ((p = OSSL_PARAM_locate(params, "cookie")) != NULL) |
16bfe6ce | 393 | OSSL_PARAM_set_utf8_ptr(p, "cookie value"); |
7ffbd7ca P |
394 | |
395 | =head1 SEE ALSO | |
396 | ||
397 | L<openssl-core.h(7)>, L<OSSL_PARAM(3)> | |
398 | ||
399 | =head1 HISTORY | |
400 | ||
4674aaf4 | 401 | These APIs were introduced in OpenSSL 3.0. |
7ffbd7ca P |
402 | |
403 | =head1 COPYRIGHT | |
404 | ||
fecb3aae | 405 | Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved. |
7ffbd7ca P |
406 | |
407 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
408 | this file except in compliance with the License. You can obtain a copy | |
409 | in the file LICENSE in the source distribution or at | |
410 | L<https://www.openssl.org/source/license.html>. | |
411 | ||
412 | =cut |