ed82e320734eb571b9d41a7f44507887461b9d8f
[openssl.git] / doc / man3 / OSSL_PARAM_BLD.pod
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_double, OSSL_PARAM_BLD_push_BN,
12 OSSL_PARAM_BLD_push_BN_pad, OSSL_PARAM_BLD_push_utf8_string,
13 OSSL_PARAM_BLD_push_utf8_ptr, OSSL_PARAM_BLD_push_octet_string,
14 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-2020 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