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