3aa6141f0c226293bdf97cea30e955a74fed4b43
[openssl.git] / doc / man3 / OSSL_PARAM_int.pod
1 =pod
2
3 =head1 NAME
4
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,
7 OSSL_PARAM_uint64, OSSL_PARAM_ulong, OSSL_PARAM_BN, OSSL_PARAM_utf8_string,
8 OSSL_PARAM_octet_string, OSSL_PARAM_utf8_ptr, OSSL_PARAM_octet_ptr,
9 OSSL_PARAM_END, OSSL_PARAM_construct_BN, OSSL_PARAM_construct_double,
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,
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,
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
33 =for comment generic
34
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)
42  #define OSSL_PARAM_BN(key, address, size)
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,
47                                     size_t bsize);
48  OSSL_PARAM OSSL_PARAM_construct_utf8_string(const char *key, char *buf,
49                                              size_t bsize);
50  OSSL_PARAM OSSL_PARAM_construct_octet_string(const char *key, void *buf,
51                                               size_t bsize);
52  OSSL_PARAM OSSL_PARAM_construct_utf8_ptr(const char *key, char **buf,
53                                           size_t bsize);
54  OSSL_PARAM OSSL_PARAM_construct_octet_ptr(const char *key, void **buf,
55                                            size_t bsize);
56  OSSL_PARAM OSSL_PARAM_construct_end(void);
57
58  OSSL_PARAM *OSSL_PARAM_locate(OSSL_PARAM *array, const char *key);
59  const OSSL_PARAM *OSSL_PARAM_locate_const(const OSSL_PARAM *array,
60                                            const char *key);
61
62  int OSSL_PARAM_get_TYPE(const OSSL_PARAM *p, const char *key, TYPE *val);
63  int OSSL_PARAM_set_TYPE(OSSL_PARAM *p, const char *key, TYPE val);
64
65  int OSSL_PARAM_get_BN(const OSSL_PARAM *p, const char *key, BIGNUM **val);
66  int OSSL_PARAM_set_BN(OSSL_PARAM *p, const char *key, const BIGNUM *val);
67
68  int OSSL_PARAM_get_utf8_string(const OSSL_PARAM *p, char **val,
69                                 size_t max_len);
70  int OSSL_PARAM_set_utf8_string(OSSL_PARAM *p, const char *val);
71
72  int OSSL_PARAM_get_octet_string(const OSSL_PARAM *p, void **val,
73                                  size_t max_len, size_t *used_len);
74  int OSSL_PARAM_set_octet_string(OSSL_PARAM *p, const void *val, size_t len);
75
76  int OSSL_PARAM_get_utf8_ptr(const OSSL_PARAM *p, char **val);
77  int OSSL_PARAM_set_utf8_ptr(OSSL_PARAM *p, char *val);
78
79  int OSSL_PARAM_get_octet_ptr(const OSSL_PARAM *p, void **val,
80                               size_t *used_len);
81  int OSSL_PARAM_set_octet_ptr(OSSL_PARAM *p, void *val, size_t used_len);
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(),
138 OSSL_PARAM_octet_ptr(), OSSL_PARAM_BN() are macros that provide support
139 for defining UTF8 strings, OCTET strings and big numbers.
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
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.
168 A parameter with name B<key>, storage pointer B<*buf>, size B<bsize> and
169 return size B<rsize> is created.
170
171 OSSL_PARAM_construct_octet_ptr() is a function that constructes an OCTET string
172 pointer OSSL_PARAM structure.
173 A parameter with name B<key>, storage pointer B<*buf>, size B<bsize> and
174 return size B<rsize> is created.
175
176 OSSL_PARAM_construct_end() is a function that constructs the terminating
177 OSSL_PARAM structure.
178
179 OSSL_PARAM_locate() is a function that searches an B<array> of parameters for
180 the one matching the B<key> name.
181
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
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 parameter
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 parameter 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
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>.
243
244 All other functions return B<1> on success and B<0> on failure.
245
246 =head1 NOTES
247
248 Native types will be converted as required only if the value is exactly
249 representable by the target type or parameter.
250 Apart from that, the functions must be used appropriately for the
251 expected type of the parameter.
252
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
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
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:
286
287     const char *foo = NULL;
288     char bar[1024];
289     OSSL_PARAM request[] = {
290         OSSL_PARAM_utf8_ptr("foo", foo, 0),
291         OSSL_PARAM_utf8_string("bar", bar, sizeof(bar)),
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
298     /* OSSL_PARAM *params */
299
300     OSSL_PARAM *p;
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");
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