Debian Codegraph @

upstream/debian-unstable/man3/OSSL_PARAM_BLD.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "OSSL_PARAM_BLD 3SSL"
58 .TH OSSL_PARAM_BLD 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 OSSL_PARAM_BLD, OSSL_PARAM_BLD_new, OSSL_PARAM_BLD_to_param,
65 OSSL_PARAM_BLD_free, OSSL_PARAM_BLD_push_int,
66 OSSL_PARAM_BLD_push_uint, OSSL_PARAM_BLD_push_long,
67 OSSL_PARAM_BLD_push_ulong, OSSL_PARAM_BLD_push_int32,
68 OSSL_PARAM_BLD_push_uint32, OSSL_PARAM_BLD_push_int64,
69 OSSL_PARAM_BLD_push_uint64, OSSL_PARAM_BLD_push_size_t,
70 OSSL_PARAM_BLD_push_time_t, OSSL_PARAM_BLD_push_double,
71 OSSL_PARAM_BLD_push_BN, OSSL_PARAM_BLD_push_BN_pad,
72 OSSL_PARAM_BLD_push_utf8_string, OSSL_PARAM_BLD_push_utf8_ptr,
73 OSSL_PARAM_BLD_push_octet_string, OSSL_PARAM_BLD_push_octet_ptr
74 \&\- functions to assist in the creation of OSSL_PARAM arrays
75 .SH SYNOPSIS
76 .IX Header "SYNOPSIS"
77 .Vb 1
78 \& #include <openssl/param_build.h>
79 \&
80 \& typedef struct OSSL_PARAM_BLD;
81 \&
82 \& OSSL_PARAM_BLD *OSSL_PARAM_BLD_new(void);
83 \& OSSL_PARAM *OSSL_PARAM_BLD_to_param(OSSL_PARAM_BLD *bld);
84 \& void OSSL_PARAM_BLD_free(OSSL_PARAM_BLD *bld);
85 \&
86 \& int OSSL_PARAM_BLD_push_TYPE(OSSL_PARAM_BLD *bld, const char *key, TYPE val);
87 \&
88 \& int OSSL_PARAM_BLD_push_BN(OSSL_PARAM_BLD *bld, const char *key,
89 \& const BIGNUM *bn);
90 \& int OSSL_PARAM_BLD_push_BN_pad(OSSL_PARAM_BLD *bld, const char *key,
91 \& const BIGNUM *bn, size_t sz);
92 \&
93 \& int OSSL_PARAM_BLD_push_utf8_string(OSSL_PARAM_BLD *bld, const char *key,
94 \& const char *buf, size_t bsize);
95 \& int OSSL_PARAM_BLD_push_utf8_ptr(OSSL_PARAM_BLD *bld, const char *key,
96 \& char *buf, size_t bsize);
97 \& int OSSL_PARAM_BLD_push_octet_string(OSSL_PARAM_BLD *bld, const char *key,
98 \& const void *buf, size_t bsize);
99 \& int OSSL_PARAM_BLD_push_octet_ptr(OSSL_PARAM_BLD *bld, const char *key,
100 \& void *buf, size_t bsize);
101 .Ve
102 .SH DESCRIPTION
103 .IX Header "DESCRIPTION"
104 A collection of utility functions that simplify the creation of OSSL_PARAM
105 arrays. The \fR\f(BITYPE\fR\fB\fR names are as per \fBOSSL_PARAM_int\fR\|(3).
106 .PP
107 \&\fBOSSL_PARAM_BLD_new()\fR allocates and initialises a new OSSL_PARAM_BLD structure
108 so that values can be added.
109 Any existing values are cleared.
110 .PP
111 \&\fBOSSL_PARAM_BLD_free()\fR deallocates the memory allocates by \fBOSSL_PARAM_BLD_new()\fR.
112 If the argument is NULL, nothing is done.
113 .PP
114 \&\fBOSSL_PARAM_BLD_to_param()\fR converts a built up OSSL_PARAM_BLD structure
115 \&\fIbld\fR into an allocated OSSL_PARAM array.
116 The OSSL_PARAM array and all associated storage must be freed by calling
117 \&\fBOSSL_PARAM_free()\fR with the functions return value.
118 \&\fBOSSL_PARAM_BLD_free()\fR can safely be called any time after this function is.
119 .PP
120 \&\fBOSSL_PARAM_BLD_push_\fR\f(BITYPE\fR() are a series of functions which will create
121 OSSL_PARAM objects of the specified size and correct type for the \fIval\fR
122 argument.
123 \&\fIval\fR is stored by value and an expression or auto variable can be used.
124 .PP
125 When \fR\f(BITYPE\fR\fB\fR denotes an integer type, signed integer types will normally
126 get the OSSL_PARAM type \fBOSSL_PARAM_INTEGER\fR params.
127 When \fB\fR\f(BITYPE\fR\fB\fR denotes an unsigned integer type will get the OSSL_PARAM type
128 \&\fBOSSL_PARAM_UNSIGNED_INTEGER\fR.
129 .PP
130 \&\fBOSSL_PARAM_BLD_push_BN()\fR is a function that will create an OSSL_PARAM object
131 that holds the specified BIGNUM \fIbn\fR.
132 When the \fIbn\fR is zero or positive, its OSSL_PARAM type becomes
133 \&\fBOSSL_PARAM_UNSIGNED_INTEGER\fR.
134 When the \fIbn\fR is negative, its OSSL_PARAM type becomes \fBOSSL_PARAM_INTEGER\fR.
135 If \fIbn\fR is marked as being securely allocated, its OSSL_PARAM representation
136 will also be securely allocated.
137 The \fIbn\fR argument is stored by reference and the underlying BIGNUM object
138 must exist until after \fBOSSL_PARAM_BLD_to_param()\fR has been called.
139 .PP
140 \&\fBOSSL_PARAM_BLD_push_BN_pad()\fR is a function that will create an OSSL_PARAM object
141 that holds the specified BIGNUM \fIbn\fR.
142 The object will be padded to occupy exactly \fIsz\fR bytes, if insufficient space
143 is specified an error results.
144 When the \fIbn\fR is zero or positive, its OSSL_PARAM type becomes
145 \&\fBOSSL_PARAM_UNSIGNED_INTEGER\fR.
146 When the \fIbn\fR is negative, its OSSL_PARAM type becomes \fBOSSL_PARAM_INTEGER\fR.
147 If \fIbn\fR is marked as being securely allocated, its OSSL_PARAM representation
148 will also be securely allocated.
149 The \fIbn\fR argument is stored by reference and the underlying BIGNUM object
150 must exist until after \fBOSSL_PARAM_BLD_to_param()\fR has been called.
151 .PP
152 \&\fBOSSL_PARAM_BLD_push_utf8_string()\fR is a function that will create an OSSL_PARAM
153 object that references the UTF8 string specified by \fIbuf\fR.
154 The length of the string \fIbsize\fR should not include the terminating NUL byte.
155 If it is zero then it will be calculated.
156 The string that \fIbuf\fR points to is stored by reference and must remain in
157 scope until after \fBOSSL_PARAM_BLD_to_param()\fR has been called.
158 .PP
159 \&\fBOSSL_PARAM_BLD_push_octet_string()\fR is a function that will create an OSSL_PARAM
160 object that references the octet string specified by \fIbuf\fR and <bsize>.
161 The memory that \fIbuf\fR points to is stored by reference and must remain in
162 scope until after \fBOSSL_PARAM_BLD_to_param()\fR has been called.
163 .PP
164 \&\fBOSSL_PARAM_BLD_push_utf8_ptr()\fR is a function that will create an OSSL_PARAM
165 object that references the UTF8 string specified by \fIbuf\fR.
166 The length of the string \fIbsize\fR should not include the terminating NUL byte.
167 If it is zero then it will be calculated.
168 The string \fIbuf\fR points to is stored by reference and must remain in
169 scope until the OSSL_PARAM array is freed.
170 .PP
171 \&\fBOSSL_PARAM_BLD_push_octet_ptr()\fR is a function that will create an OSSL_PARAM
172 object that references the octet string specified by \fIbuf\fR.
173 The memory \fIbuf\fR points to is stored by reference and must remain in
174 scope until the OSSL_PARAM array is freed.
175 .SH "RETURN VALUES"
176 .IX Header "RETURN VALUES"
177 \&\fBOSSL_PARAM_BLD_new()\fR returns the allocated OSSL_PARAM_BLD structure, or NULL
178 on error.
179 .PP
180 \&\fBOSSL_PARAM_BLD_to_param()\fR returns the allocated OSSL_PARAM array, or NULL
181 on error.
182 .PP
183 All of the OSSL_PARAM_BLD_push_TYPE functions return 1 on success and 0
184 on error.
185 .SH NOTES
186 .IX Header "NOTES"
187 \&\fBOSSL_PARAM_BLD_push_BN()\fR and \fBOSSL_PARAM_BLD_push_BN_pad()\fR only
188 support nonnegative \fBBIGNUM\fRs. They return an error on negative
189 \&\fBBIGNUM\fRs.
190 To pass signed \fBBIGNUM\fRs, use \fBOSSL_PARAM_BLD_push_signed_BN()\fR.
191 .SH EXAMPLES
192 .IX Header "EXAMPLES"
193 Both examples creating an OSSL_PARAM array that contains an RSA key.
194 For both, the predefined key variables are:
195 .PP
196 .Vb 6
197 \& BIGNUM *n; /* modulus */
198 \& unsigned int e; /* public exponent */
199 \& BIGNUM *d; /* private exponent */
200 \& BIGNUM *p, *q; /* first two prime factors */
201 \& BIGNUM *dmp1, *dmq1; /* first two CRT exponents */
202 \& BIGNUM *iqmp; /* first CRT coefficient */
203 .Ve
204 .SS "Example 1"
205 .IX Subsection "Example 1"
206 This example shows how to create an OSSL_PARAM array that contains an RSA
207 private key.
208 .PP
209 .Vb 2
210 \& OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new();
211 \& OSSL_PARAM *params = NULL;
212 \&
213 \& if (bld == NULL
214 \& || !OSSL_PARAM_BLD_push_BN(bld, "n", n)
215 \& || !OSSL_PARAM_BLD_push_uint(bld, "e", e)
216 \& || !OSSL_PARAM_BLD_push_BN(bld, "d", d)
217 \& || !OSSL_PARAM_BLD_push_BN(bld, "rsa\-factor1", p)
218 \& || !OSSL_PARAM_BLD_push_BN(bld, "rsa\-factor2", q)
219 \& || !OSSL_PARAM_BLD_push_BN(bld, "rsa\-exponent1", dmp1)
220 \& || !OSSL_PARAM_BLD_push_BN(bld, "rsa\-exponent2", dmq1)
221 \& || !OSSL_PARAM_BLD_push_BN(bld, "rsa\-coefficient1", iqmp)
222 \& || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL)
223 \& goto err;
224 \& OSSL_PARAM_BLD_free(bld);
225 \& /* Use params */
226 \& ...
227 \& OSSL_PARAM_free(params);
228 .Ve
229 .SS "Example 2"
230 .IX Subsection "Example 2"
231 This example shows how to create an OSSL_PARAM array that contains an RSA
232 public key.
233 .PP
234 .Vb 2
235 \& OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new();
236 \& OSSL_PARAM *params = NULL;
237 \&
238 \& if (nld == NULL
239 \& || !OSSL_PARAM_BLD_push_BN(bld, "n", n)
240 \& || !OSSL_PARAM_BLD_push_uint(bld, "e", e)
241 \& || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL)
242 \& goto err;
243 \& OSSL_PARAM_BLD_free(bld);
244 \& /* Use params */
245 \& ...
246 \& OSSL_PARAM_free(params);
247 .Ve
248 .SH "SEE ALSO"
249 .IX Header "SEE ALSO"
250 \&\fBOSSL_PARAM_int\fR\|(3), \fBOSSL_PARAM\fR\|(3), \fBOSSL_PARAM_free\fR\|(3)
251 .SH HISTORY
252 .IX Header "HISTORY"
253 The functions described here were all added in OpenSSL 3.0.
254 .SH COPYRIGHT
255 .IX Header "COPYRIGHT"
256 Copyright 2019\-2024 The OpenSSL Project Authors. All Rights Reserved.
257 .PP
258 Licensed under the Apache License 2.0 (the "License"). You may not use
259 this file except in compliance with the License. You can obtain a copy
260 in the file LICENSE in the source distribution or at
261 <https://www.openssl.org/source/license.html>.